/ Hex Artifact Content
Login

Artifact 82977ae32ba5f5a115d4434418087c9c1088f643:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  y are supported 
07d0: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
07e0: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
07f0: 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  nly.  Applicatio
0800: 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64  n writers should
0810: 20 62 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a   be aware that.*
0820: 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69  * experimental i
0830: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73 75  nterfaces are su
0840: 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
0850: 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65  in point release
0860: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d  s..**.** These m
0870: 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65  acros used to re
0880: 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73  solve to various
0890: 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c   kinds of compil
08a0: 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a  er magic that.**
08b0: 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20   would generate 
08c0: 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73  warning messages
08d0: 20 77 68 65 6e 20 74 68 65 79 20 77 65 72 65 20   when they were 
08e0: 75 73 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a  used.  But that.
08f0: 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69  ** compiler magi
0900: 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72  c ended up gener
0910: 61 74 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75  ating such a flu
0920: 72 72 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72  rry of bug repor
0930: 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61  ts.** that we ha
0940: 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20  ve taken it all 
0950: 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63  out and gone bac
0960: 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c  k to using simpl
0970: 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73  e.** noop macros
0980: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
0990: 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23  ITE_DEPRECATED.#
09a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58  define SQLITE_EX
09b0: 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a  PERIMENTAL../*.*
09c0: 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65 20 73  * Ensure these s
09d0: 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20  ymbols were not 
09e0: 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20  defined by some 
09f0: 70 72 65 76 69 6f 75 73 20 68 65 61 64 65 72 20  previous header 
0a00: 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  file..*/.#ifdef 
0a10: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23  SQLITE_VERSION.#
0a20: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0a30: 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66  RSION.#endif.#if
0a40: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0a50: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65  ON_NUMBER.# unde
0a60: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a70: 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a  _NUMBER.#endif..
0a80: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
0a90: 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62  Compile-Time Lib
0aa0: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
0ab0: 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  bers.**.** ^(The
0ac0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0ad0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0ae0: 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71   macro in the sq
0af0: 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a  lite3.h header.*
0b00: 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61  * evaluates to a
0b10: 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20   string literal 
0b20: 74 68 61 74 20 69 73 20 74 68 65 20 53 51 4c 69  that is the SQLi
0b30: 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68  te version in th
0b40: 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59  e.** format "X.Y
0b50: 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73 20 74  .Z" where X is t
0b60: 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e  he major version
0b70: 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20   number (always 
0b80: 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33  3 for.** SQLite3
0b90: 29 20 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d  ) and Y is the m
0ba0: 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d  inor version num
0bb0: 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65  ber and Z is the
0bc0: 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e   release number.
0bd0: 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  )^.** ^(The [SQL
0be0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0bf0: 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ER] C preprocess
0c00: 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65  or macro resolve
0c10: 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a  s to an integer.
0c20: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61 6c 75  ** with the valu
0c30: 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59  e (X*1000000 + Y
0c40: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65  *1000 + Z) where
0c50: 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65   X, Y, and Z are
0c60: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d   the same.** num
0c70: 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51  bers used in [SQ
0c80: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e  LITE_VERSION].)^
0c90: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56  .** The SQLITE_V
0ca0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f  ERSION_NUMBER fo
0cb0: 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65  r any given rele
0cc0: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ase of SQLite wi
0cd0: 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61  ll also.** be la
0ce0: 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 72 65  rger than the re
0cf0: 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68  lease from which
0d00: 20 69 74 20 69 73 20 64 65 72 69 76 65 64 2e 20   it is derived. 
0d10: 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a   Either Y will.*
0d20: 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61  * be held consta
0d30: 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  nt and Z will be
0d40: 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20   incremented or 
0d50: 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69  else Y will be i
0d60: 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e  ncremented.** an
0d70: 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65  d Z will be rese
0d80: 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  t to zero..**.**
0d90: 20 53 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33   Since version 3
0da0: 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f  .6.18, SQLite so
0db0: 75 72 63 65 20 63 6f 64 65 20 68 61 73 20 62 65  urce code has be
0dc0: 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65  en stored in the
0dd0: 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74  .** <a href="htt
0de0: 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73  p://www.fossil-s
0df0: 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20  cm.org/">Fossil 
0e00: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0e10: 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74  nagement.** syst
0e20: 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51  em</a>.  ^The SQ
0e30: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d  LITE_SOURCE_ID m
0e40: 61 63 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74  acro evaluates t
0e50: 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68  o.** a string wh
0e60: 69 63 68 20 69 64 65 6e 74 69 66 69 65 73 20 61  ich identifies a
0e70: 20 70 61 72 74 69 63 75 6c 61 72 20 63 68 65 63   particular chec
0e80: 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a  k-in of SQLite.*
0e90: 2a 20 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e  * within its con
0ea0: 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67  figuration manag
0eb0: 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e  ement system.  ^
0ec0: 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  The SQLITE_SOURC
0ed0: 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63  E_ID.** string c
0ee0: 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 65  ontains the date
0ef0: 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65   and time of the
0f00: 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20   check-in (UTC) 
0f10: 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68  and an SHA1.** h
0f20: 61 73 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72  ash of the entir
0f30: 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a  e source tree..*
0f40: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
0f50: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
0f60: 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  on()],.** [sqlit
0f70: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
0f80: 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65  mber()], [sqlite
0f90: 33 5f 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a  3_sourceid()],.*
0fa0: 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f  * [sqlite_versio
0fb0: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
0fc0: 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a  _source_id()]..*
0fd0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
0fe0: 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20  _VERSION        
0ff0: 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69  "--VERS--".#defi
1000: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
1010: 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49  N_NUMBER --VERSI
1020: 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66  ON-NUMBER--.#def
1030: 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  ine SQLITE_SOURC
1040: 45 5f 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55  E_ID      "--SOU
1050: 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a  RCE-ID--"../*.**
1060: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
1070: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
1080: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b  ion Numbers.** K
1090: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
10a0: 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65  _version, sqlite
10b0: 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a  3_sourceid.**.**
10c0: 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   These interface
10d0: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
10e0: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
10f0: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
1100: 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  RSION],.** [SQLI
1110: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1120: 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  R], and [SQLITE_
1130: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1140: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73  processor macros
1150: 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f  .** but are asso
1160: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
1170: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
1180: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
1190: 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a  le.  ^(Cautious.
11a0: 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  ** programmers m
11b0: 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73  ight include ass
11c0: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
11d0: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63   in their applic
11e0: 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69  ation to.** veri
11f0: 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72  fy that values r
1200: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1210: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63   interfaces matc
1220: 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a  h the macros in.
1230: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61  ** the header, a
1240: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74  nd thus insure t
1250: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  hat the applicat
1260: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ion is.** compil
1270: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67  ed with matching
1280: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61   library and hea
1290: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  der files..**.**
12a0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
12b0: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71  e>.** assert( sq
12c0: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
12d0: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54  _number()==SQLIT
12e0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
12f0: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73   );.** assert( s
1300: 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f  trcmp(sqlite3_so
1310: 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f  urceid(),SQLITE_
1320: 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b  SOURCE_ID)==0 );
1330: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1340: 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  mp(sqlite3_libve
1350: 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56  rsion(),SQLITE_V
1360: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
1370: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1380: 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
1390: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
13a0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
13b0: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ant contains the
13c0: 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45   text of [SQLITE
13d0: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63  _VERSION].** mac
13e0: 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ro.  ^The sqlite
13f0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66  3_libversion() f
1400: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1410: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1420: 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74  .** to the sqlit
1430: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1440: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54  ing constant.  T
1450: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
1460: 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74  rsion().** funct
1470: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
1480: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
1490: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
14a0: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
14b0: 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63  ave.** direct ac
14c0: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63  cess to string c
14d0: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
14e0: 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a  the DLL.  ^The.*
14f0: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  * sqlite3_libver
1500: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75  sion_number() fu
1510: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1520: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
1530: 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  to.** [SQLITE_VE
1540: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20  RSION_NUMBER].  
1550: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75  ^The sqlite3_sou
1560: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e  rceid() function
1570: 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70   returns .** a p
1580: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
1590: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73  ng constant whos
15a0: 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73  e value is the s
15b0: 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b  ame as the .** [
15c0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
15d0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
15e0: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65   macro..**.** Se
15f0: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f  e also: [sqlite_
1600: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
1610: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
1620: 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ()]..*/.SQLITE_E
1630: 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72  XTERN const char
1640: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
1650: 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  [];.const char *
1660: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1670: 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20  on(void);.const 
1680: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f  char *sqlite3_so
1690: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e  urceid(void);.in
16a0: 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  t sqlite3_libver
16b0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64  sion_number(void
16c0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16d0: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
16e0: 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e  rary Compilation
16f0: 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73   Options Diagnos
1700: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tics.**.** ^The 
1710: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1720: 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e  ption_used() fun
1730: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20  ction returns 0 
1740: 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74  or 1 .** indicat
1750: 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 20  ing whether the 
1760: 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e  specified option
1770: 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 20   was defined at 
1780: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  .** compile time
1790: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20  .  ^The SQLITE_ 
17a0: 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d  prefix may be om
17b0: 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a  itted from the .
17c0: 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70  ** option name p
17d0: 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33  assed to sqlite3
17e0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
17f0: 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e  sed().  .**.** ^
1800: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
1810: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1820: 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  function allows 
1830: 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65  iterating.** ove
1840: 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70  r the list of op
1850: 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20  tions that were 
1860: 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69  defined at compi
1870: 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65  le time by.** re
1880: 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68  turning the N-th
1890: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70   compile time op
18a0: 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49  tion string.  ^I
18b0: 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  f N is out of ra
18c0: 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  nge,.** sqlite3_
18d0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
18e0: 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  t() returns a NU
18f0: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
1900: 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72  e SQLITE_ .** pr
1910: 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20  efix is omitted 
1920: 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73  from any strings
1930: 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a   returned by .**
1940: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1950: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a  option_get()..**
1960: 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72  .** ^Support for
1970: 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20   the diagnostic 
1980: 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65  functions sqlite
1990: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
19a0: 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71  used().** and sq
19b0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
19c0: 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65  ion_get() may be
19d0: 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 63   omitted by spec
19e0: 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b  ifying the .** [
19f0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50  SQLITE_OMIT_COMP
1a00: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d  ILEOPTION_DIAGS]
1a10: 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69   option at compi
1a20: 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53  le time..**.** S
1a30: 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e  ee also: SQL fun
1a40: 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63  ctions [sqlite_c
1a50: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1a60: 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1a70: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1a80: 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65  n_get()] and the
1a90: 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e   [compile_option
1aa0: 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69  s pragma]..*/.#i
1ab0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
1ac0: 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f  T_COMPILEOPTION_
1ad0: 44 49 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65  DIAGS.int sqlite
1ae0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1af0: 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20  used(const char 
1b00: 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73  *zOptName);.cons
1b10: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1b20: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b30: 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66  t(int N);.#endif
1b40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b50: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66  : Test To See If
1b60: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20   The Library Is 
1b70: 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a  Threadsafe.**.**
1b80: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68   ^The sqlite3_th
1b90: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
1ba0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ion returns zero
1bb0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
1bc0: 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f  ** SQLite was co
1bd0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65  mpiled with mute
1be0: 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65  xing code omitte
1bf0: 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20  d due to the.** 
1c00: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1c10: 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  FE] compile-time
1c20: 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65   option being se
1c30: 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51  t to 0..**.** SQ
1c40: 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70  Lite can be comp
1c50: 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 74  iled with or wit
1c60: 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57  hout mutexes.  W
1c70: 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  hen.** the [SQLI
1c80: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43  TE_THREADSAFE] C
1c90: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1ca0: 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d  cro is 1 or 2, m
1cb0: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
1cc0: 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65  abled and SQLite
1cd0: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20   is threadsafe. 
1ce0: 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51   When the.** [SQ
1cf0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d00: 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a   macro is 0, .**
1d10: 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65   the mutexes are
1d20: 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f   omitted.  Witho
1d30: 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20  ut the mutexes, 
1d40: 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a  it is not safe.*
1d50: 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20  * to use SQLite 
1d60: 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f  concurrently fro
1d70: 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  m more than one 
1d80: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e  thread..**.** En
1d90: 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69  abling mutexes i
1da0: 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62  ncurs a measurab
1db0: 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70  le performance p
1dc0: 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66  enalty..** So if
1dd0: 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d   speed is of utm
1de0: 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20  ost importance, 
1df0: 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74  it makes sense t
1e00: 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  o disable.** the
1e10: 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66   mutexes.  But f
1e20: 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74  or maximum safet
1e30: 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  y, mutexes shoul
1e40: 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  d be enabled..**
1e50: 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 65   ^The default be
1e60: 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75  havior is for mu
1e70: 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62  texes to be enab
1e80: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  led..**.** This 
1e90: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
1ea0: 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c   used by an appl
1eb0: 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20  ication to make 
1ec0: 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
1ed0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69   version of SQLi
1ee0: 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c 69  te that it is li
1ef0: 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61  nking against wa
1f00: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
1f10: 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 73  ** the desired s
1f20: 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53  etting of the [S
1f30: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1f40: 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54  ] macro..**.** T
1f50: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e  his interface on
1f60: 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68  ly reports on th
1f70: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  e compile-time m
1f80: 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20  utex setting.** 
1f90: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1fa0: 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e  HREADSAFE] flag.
1fb0: 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
1fc0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
1fd0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fe0: 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d  E=1 or =2 then m
1ff0: 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c  utexes are enabl
2000: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 75  ed by default bu
2010: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c  t.** can be full
2020: 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64  y or partially d
2030: 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20  isabled using a 
2040: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2050: 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69  _config()].** wi
2060: 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 51  th the verbs [SQ
2070: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
2080: 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49  LETHREAD], [SQLI
2090: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
20a0: 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  HREAD],.** or [S
20b0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
20c0: 49 41 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65  IALIZED].  ^(The
20d0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
20e0: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
20f0: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
2100: 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79  ction shows only
2110: 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   the compile-tim
2120: 65 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20  e setting of.** 
2130: 74 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e  thread safety, n
2140: 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20  ot any run-time 
2150: 63 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20  changes to that 
2160: 73 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a  setting made by.
2170: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  ** sqlite3_confi
2180: 67 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  g(). In other wo
2190: 72 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20  rds, the return 
21a0: 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
21b0: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a  e3_threadsafe().
21c0: 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20  ** is unchanged 
21d0: 62 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  by calls to sqli
21e0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a  te3_config().)^.
21f0: 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74  **.** See the [t
2200: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64  hreading mode] d
2210: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
2220: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
2230: 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20  rmation..*/.int 
2240: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2250: 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  fe(void);../*.**
2260: 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
2270: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48  ase Connection H
2280: 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44  andle.** KEYWORD
2290: 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  S: {database con
22a0: 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61  nection} {databa
22b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a  se connections}.
22c0: 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20  **.** Each open 
22d0: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
22e0: 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  is represented b
22f0: 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  y a pointer to a
2300: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a  n instance of.**
2310: 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75   the opaque stru
2320: 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c  cture named "sql
2330: 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73  ite3".  It is us
2340: 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66  eful to think of
2350: 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70   an sqlite3.** p
2360: 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a  ointer as an obj
2370: 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ect.  The [sqlit
2380: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
2390: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
23a0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
23b0: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
23c0: 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f  faces are its co
23d0: 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20  nstructors, and 
23e0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
23f0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2400: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72  3_close_v2()] ar
2410: 65 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72  e its destructor
2420: 73 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61  s.  There are ma
2430: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65  ny other.** inte
2440: 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a  rfaces (such as.
2450: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2460: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
2470: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2480: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ion()], and.** [
2490: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
24a0: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20  eout()] to name 
24b0: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20  but three) that 
24c0: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61  are methods on a
24d0: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a  n.** sqlite3 obj
24e0: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ect..*/.typedef 
24f0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73  struct sqlite3 s
2500: 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43  qlite3;../*.** C
2510: 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20  API3REF: 64-Bit 
2520: 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a  Integer Types.**
2530: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
2540: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75  e_int64 sqlite_u
2550: 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61  int64.**.** Beca
2560: 75 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20  use there is no 
2570: 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77  cross-platform w
2580: 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34  ay to specify 64
2590: 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70  -bit integer typ
25a0: 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63  es.** SQLite inc
25b0: 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66  ludes typedefs f
25c0: 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  or 64-bit signed
25d0: 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e   and unsigned in
25e0: 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  tegers..**.** Th
25f0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
2600: 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  and sqlite3_uint
2610: 36 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65  64 are the prefe
2620: 72 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69  rred type defini
2630: 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71  tions..** The sq
2640: 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73  lite_int64 and s
2650: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70  qlite_uint64 typ
2660: 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  es are supported
2670: 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a   for backwards.*
2680: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
2690: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  only..**.** ^The
26a0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
26b0: 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  nd sqlite_int64 
26c0: 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20  types can store 
26d0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a  integer values.*
26e0: 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33  * between -92233
26f0: 37 32 30 33 36 38 35 34 37 37 35 38 30 38 20 61  72036854775808 a
2700: 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36 38 35  nd +922337203685
2710: 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76  4775807 inclusiv
2720: 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
2730: 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73  te3_uint64 and s
2740: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70  qlite_uint64 typ
2750: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
2760: 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20  eger values .** 
2770: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31  between 0 and +1
2780: 38 34 34 36 37 34 34 30 37 33 37 30 39 35 35 31  8446744073709551
2790: 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a  615 inclusive..*
27a0: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
27b0: 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70  INT64_TYPE.  typ
27c0: 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  edef SQLITE_INT6
27d0: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e  4_TYPE sqlite_in
27e0: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
27f0: 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49  nsigned SQLITE_I
2800: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
2810: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64  _uint64;.#elif d
2820: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
2830: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
2840: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
2850: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
2860: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2870: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
2880: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
2890: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
28a0: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
28b0: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
28c0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
28d0: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
28e0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
28f0: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
2900: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2910: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
2920: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
2930: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
2940: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
2950: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
2960: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
2970: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
2980: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
2990: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
29a0: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
29b0: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
29c0: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
29d0: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
29e0: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
29f0: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
2a00: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
2a10: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2a20: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  Connection.**.**
2a30: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2a40: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2a50: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2a60: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2a70: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2a80: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2a90: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2aa0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2ab0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2ac0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2ad0: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2ae0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2af0: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2b00: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2b10: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2b20: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2b30: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2b40: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2b50: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2b60: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2b70: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2b80: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2b90: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2ba0: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2bb0: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2bc0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2bd0: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2be0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2bf0: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2c00: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2c10: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2c20: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2c30: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2c40: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2c50: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2c60: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2c70: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2c80: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2c90: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ca0: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2cb0: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2cc0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
2cd0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
2ce0: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
2cf0: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
2d00: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2d10: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
2d20: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
2d30: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
2d40: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
2d50: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
2d60: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
2d70: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
2d80: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
2d90: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
2da0: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
2db0: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
2dc0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
2dd0: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
2de0: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
2df0: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
2e00: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
2e10: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2e20: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
2e30: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e40: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
2e50: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
2e60: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
2e70: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
2e80: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
2e90: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
2ea0: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
2eb0: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
2ec0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
2ed0: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
2ee0: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
2ef0: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
2f00: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
2f10: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
2f20: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
2f30: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
2f40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2f50: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
2f60: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
2f70: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2f80: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
2f90: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
2fa0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
2fb0: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
2fc0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
2fd0: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
2fe0: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
2ff0: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3000: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3010: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3020: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3030: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
3040: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
3050: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
3060: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
3070: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
3080: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
3090: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
30a0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
30b0: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
30c0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
30d0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
30e0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
30f0: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3100: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3110: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3120: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3130: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
3140: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
3150: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
3160: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
3170: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3180: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
3190: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
31a0: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
31b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
31c0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
31d0: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
31e0: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
31f0: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3200: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3210: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3220: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3230: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
3240: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
3250: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
3260: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
3270: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
3280: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
3290: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
32a0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
32b0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
32c0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
32d0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
32e0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
32f0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3300: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3310: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3320: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3330: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
3340: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
3350: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
3360: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
3370: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
3380: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65  erface.**.** The
3390: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
33a0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
33b0: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
33c0: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
33d0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
33e0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
33f0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
3400: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
3410: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
3420: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
3430: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
3440: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
3450: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
3460: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
3470: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
3480: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
3490: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
34a0: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
34b0: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
34c0: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
34d0: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
34e0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
34f0: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
3500: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
3510: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
3520: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3530: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
3540: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
3550: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
3560: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3570: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
3580: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
3590: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
35a0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
35b0: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
35c0: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
35d0: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
35e0: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
35f0: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
3600: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
3610: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3620: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
3630: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
3640: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
3650: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
3660: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
3670: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
3680: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
3690: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
36a0: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
36b0: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
36c0: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
36d0: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
36e0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
36f0: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
3700: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
3710: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3720: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
3730: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
3740: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
3750: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
3760: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
3770: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
3780: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
3790: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
37a0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
37b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
37c0: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
37d0: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
37e0: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
37f0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
3800: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3810: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
3820: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
3830: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
3840: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
3850: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
3860: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
3870: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
3880: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
3890: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
38a0: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
38b0: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
38c0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
38d0: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73  meter of.** of s
38e0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
38f0: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3900: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3910: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3920: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3930: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
3940: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3950: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3960: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3970: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3980: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3990: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
39a0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
39b0: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
39c0: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
39d0: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
39e0: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
39f0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3a00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3a10: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3a20: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3a30: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3a40: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3a50: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3a60: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3a70: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3a80: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3a90: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3aa0: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3ab0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3ac0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3ad0: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3ae0: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3af0: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3b00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3b10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3b20: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3b30: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3b40: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3b50: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3b60: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3b70: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3b80: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3b90: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3ba0: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3bb0: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3bc0: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3bd0: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3be0: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3bf0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3c00: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3c10: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3c20: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3c30: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3c40: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3c50: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3c60: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3c70: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3c80: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3c90: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3ca0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3cb0: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
3cc0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3cd0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
3ce0: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
3cf0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3d00: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3d10: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
3d20: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
3d30: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
3d40: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
3d50: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
3d60: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
3d70: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
3d80: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
3d90: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
3da0: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
3db0: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
3dc0: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
3dd0: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
3de0: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
3df0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
3e00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3e10: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68  t insure that th
3e20: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
3e30: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3e40: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
3e50: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
3e60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3e70: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
3e80: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3e90: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
3ea0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3eb0: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
3ec0: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
3ed0: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
3ee0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
3ef0: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
3f00: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
3f10: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3f20: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3f30: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
3f40: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
3f50: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
3f60: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
3f70: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
3f80: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
3f90: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
3fa0: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
3fb0: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
3fc0: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
3fd0: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
3fe0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ff0: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4000: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4010: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4020: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4030: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
4040: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
4050: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
4060: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
4070: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
4080: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
4090: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40c0: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
40d0: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
40e0: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
40f0: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4110: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4120: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4130: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4140: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4150: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
4160: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
4170: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
4180: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
4190: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
41a0: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
41b0: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
41c0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
41d0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
41e0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
41f0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4200: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4210: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4220: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4230: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4240: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
4250: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
4260: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
4270: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
4280: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
4290: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
42a0: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
42b0: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
42c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
42d0: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
42e0: 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20  /* SQL error or 
42f0: 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65  missing database
4300: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4310: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4320: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4330: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
4340: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
4350: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
4360: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
4370: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
4380: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4390: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
43a0: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
43b0: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
43c0: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
43d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
43e0: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
43f0: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4400: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4410: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4420: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4430: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
4440: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
4450: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
4460: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
4470: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
4480: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
4490: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
44a0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
44b0: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
44c0: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
44d0: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
44e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
44f0: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4500: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4510: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4520: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4530: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4540: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
4550: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
4560: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
4570: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
4580: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
4590: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
45a0: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
45b0: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
45c0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
45d0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
45e0: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
45f0: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4600: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4610: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4620: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4630: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
4640: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
4650: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
4660: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
4670: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
4680: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
4690: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
46a0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
46b0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
46c0: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
46d0: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
46e0: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
46f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4700: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4710: 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d  * Database is em
4720: 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pty */.#define S
4730: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
4740: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
4750: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
4760: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
4770: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
4780: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
4790: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
47a0: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
47b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
47c0: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
47d0: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
47e0: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
47f0: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4800: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4810: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4820: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4830: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4840: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
4850: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
4860: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
4870: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4880: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
4890: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
48a0: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
48b0: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
48c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
48d0: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
48e0: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
48f0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4900: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4910: 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69      24   /* Auxi
4920: 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66  liary database f
4930: 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23  ormat error */.#
4940: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41  define SQLITE_RA
4950: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f  NGE       25   /
4960: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
4970: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20  to sqlite3_bind 
4980: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a  out of range */.
4990: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
49a0: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20  OTADB      26   
49b0: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74  /* File opened t
49c0: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74  hat is not a dat
49d0: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
49e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
49f0: 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a  ICE      27   /*
4a00: 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66   Notifications f
4a10: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
4a20: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4a30: 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20  ITE_WARNING     
4a40: 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73  28   /* Warnings
4a50: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f   from sqlite3_lo
4a60: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  g() */.#define S
4a70: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4a80: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4a90: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4aa0: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4ab0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4ac0: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4ad0: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4ae0: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4af0: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4b00: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4b10: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4b20: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4b30: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4b40: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4b50: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4b60: 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a   definitions}.**
4b70: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
4b80: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
4b90: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
4ba0: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
4bb0: 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a   of 30 integer.*
4bc0: 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  * [result codes]
4bd0: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4be0: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
4bf0: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a   that many of.**
4c00: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
4c10: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72  des are too coar
4c20: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
4c30: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
4c40: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
4c50: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
4c60: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
4c70: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
4c80: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4c90: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4ca0: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4cb0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4cc0: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20  rsion 3.3.8 and 
4cd0: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a  later) include.*
4ce0: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64  * support for ad
4cf0: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20  ditional result 
4d00: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69  codes that provi
4d10: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  de more detailed
4d20: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
4d30: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68  about errors. Th
4d40: 65 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65  ese [extended re
4d50: 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20  sult codes] are 
4d60: 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
4d70: 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20  led.** on a per 
4d80: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4d90: 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20  ion basis using 
4da0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
4db0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
4dc0: 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f  codes()] API.  O
4dd0: 72 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 20  r, the extended 
4de0: 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  code for.** the 
4df0: 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f  most recent erro
4e00: 72 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  r can be obtaine
4e10: 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
4e20: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
4e30: 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  code()]..*/.#def
4e40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4e50: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
4e60: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4e70: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
4e80: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4e90: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20  SHORT_READ      
4ea0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4eb0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
4ec0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57  e SQLITE_IOERR_W
4ed0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
4ee0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4ef0: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
4f00: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
4f10: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
4f20: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f30: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
4f40: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
4f50: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28  _FSYNC         (
4f60: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4f70: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
4f80: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e  QLITE_IOERR_TRUN
4f90: 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53  CATE          (S
4fa0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36  QLITE_IOERR | (6
4fb0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4fc0: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54  LITE_IOERR_FSTAT
4fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4fe0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c  LITE_IOERR | (7<
4ff0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5000: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b  ITE_IOERR_UNLOCK
5010: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5020: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c  ITE_IOERR | (8<<
5030: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5040: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20  TE_IOERR_RDLOCK 
5050: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5060: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38  TE_IOERR | (9<<8
5070: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5080: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20  E_IOERR_DELETE  
5090: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38  E_IOERR | (10<<8
50b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50c0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20  E_IOERR_BLOCKED 
50d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38  E_IOERR | (11<<8
50f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5100: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20  E_IOERR_NOMEM   
5110: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5120: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38  E_IOERR | (12<<8
5130: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5140: 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20  E_IOERR_ACCESS  
5150: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5160: 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38  E_IOERR | (13<<8
5170: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5180: 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53  E_IOERR_CHECKRES
5190: 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54  ERVEDLOCK (SQLIT
51a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38  E_IOERR | (14<<8
51b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
51c0: 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20  E_IOERR_LOCK    
51d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
51e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38  E_IOERR | (15<<8
51f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5200: 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20  E_IOERR_CLOSE   
5210: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5220: 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38  E_IOERR | (16<<8
5230: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5240: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53  E_IOERR_DIR_CLOS
5250: 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  E         (SQLIT
5260: 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38  E_IOERR | (17<<8
5270: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5280: 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20  E_IOERR_SHMOPEN 
5290: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
52a0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38  E_IOERR | (18<<8
52b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
52c0: 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20  E_IOERR_SHMSIZE 
52d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
52e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38  E_IOERR | (19<<8
52f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5300: 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20  E_IOERR_SHMLOCK 
5310: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5320: 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38  E_IOERR | (20<<8
5330: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5340: 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20  E_IOERR_SHMMAP  
5350: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5360: 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38  E_IOERR | (21<<8
5370: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5380: 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20  E_IOERR_SEEK    
5390: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
53a0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38  E_IOERR | (22<<8
53b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
53c0: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e  E_IOERR_DELETE_N
53d0: 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54  OENT      (SQLIT
53e0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38  E_IOERR | (23<<8
53f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5400: 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20  E_IOERR_MMAP    
5410: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5420: 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38  E_IOERR | (24<<8
5430: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5440: 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50  E_IOERR_GETTEMPP
5450: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5460: 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38  E_IOERR | (25<<8
5470: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5480: 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48  E_IOERR_CONVPATH
5490: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
54a0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38  E_IOERR | (26<<8
54b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
54c0: 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43  E_LOCKED_SHAREDC
54d0: 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54  ACHE      (SQLIT
54e0: 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c  E_LOCKED |  (1<<
54f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5500: 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59  TE_BUSY_RECOVERY
5510: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5520: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c  TE_BUSY   |  (1<
5530: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5540: 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f  ITE_BUSY_SNAPSHO
5550: 54 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  T           (SQL
5560: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32  ITE_BUSY   |  (2
5570: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5580: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
5590: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
55a0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
55b0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
55c0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
55d0: 49 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28  ISDIR          (
55e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
55f0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5600: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5610: 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20  N_FULLPATH      
5620: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5630: 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  N | (3<<8)).#def
5640: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5650: 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20  PEN_CONVPATH    
5660: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
5670: 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  PEN | (4<<8)).#d
5680: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
5690: 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20  RUPT_VTAB       
56a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52       (SQLITE_COR
56b0: 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23  RUPT | (1<<8)).#
56c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
56d0: 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20  ADONLY_RECOVERY 
56e0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
56f0: 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29  ADONLY | (1<<8))
5700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5710: 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43  READONLY_CANTLOC
5720: 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  K       (SQLITE_
5730: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38  READONLY | (2<<8
5740: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5750: 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42  E_READONLY_ROLLB
5760: 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  ACK       (SQLIT
5770: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c  E_READONLY | (3<
5780: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5790: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d  ITE_READONLY_DBM
57a0: 4f 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c  OVED        (SQL
57b0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
57c0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
57d0: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
57e0: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
57f0: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
5800: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5810: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5820: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
5830: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5840: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5850: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5860: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
5870: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5880: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
5890: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
58a0: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
58b0: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
58c0: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
58d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
58e0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
58f0: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
5900: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
5910: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5920: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5930: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
5940: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5950: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
5960: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5970: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
5980: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5990: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
59a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
59b0: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
59c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
59d0: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
59e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
59f0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
5a00: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
5a10: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
5a20: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5a30: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5a40: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
5a50: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5a60: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
5a70: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5a80: 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20  INT_ROWID       
5a90: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5aa0: 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64  INT |(10<<8)).#d
5ab0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
5ac0: 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20  ICE_RECOVER_WAL 
5ad0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54       (SQLITE_NOT
5ae0: 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ICE | (1<<8)).#d
5af0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
5b00: 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c  ICE_RECOVER_ROLL
5b10: 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54  BACK (SQLITE_NOT
5b20: 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ICE | (2<<8)).#d
5b30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
5b40: 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20  NING_AUTOINDEX  
5b50: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52       (SQLITE_WAR
5b60: 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23  NING | (1<<8)).#
5b70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
5b80: 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20  TH_USER         
5b90: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55        (SQLITE_AU
5ba0: 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a  TH | (1<<8))../*
5bb0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
5bc0: 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65  ags For File Ope
5bd0: 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a  n Operations.**.
5be0: 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c  ** These bit val
5bf0: 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  ues are intended
5c00: 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a   for use in the.
5c10: 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ** 3rd parameter
5c20: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5c30: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
5c40: 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20  rface and.** in 
5c50: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
5c60: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
5c70: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
5c80: 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  hod..*/.#define 
5c90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
5ca0: 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30  ONLY         0x0
5cb0: 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66  0000001  /* Ok f
5cc0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5cd0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5ce0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
5cf0: 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30  WRITE        0x0
5d00: 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66  0000002  /* Ok f
5d10: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5d20: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5d30: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
5d40: 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30  TE           0x0
5d50: 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66  0000004  /* Ok f
5d60: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5d70: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5d80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
5d90: 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30  TEONCLOSE    0x0
5da0: 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20  0000008  /* VFS 
5db0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5dc0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
5dd0: 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30  USIVE        0x0
5de0: 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20  0000010  /* VFS 
5df0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5e00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f  SQLITE_OPEN_AUTO
5e10: 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30  PROXY        0x0
5e20: 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20  0000020  /* VFS 
5e30: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5e40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
5e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5e60: 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66  0000040  /* Ok f
5e70: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5e80: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5e90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f  SQLITE_OPEN_MEMO
5ea0: 52 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30  RY           0x0
5eb0: 30 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66  0000080  /* Ok f
5ec0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5ed0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5ee0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
5ef0: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
5f00: 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20  0000100  /* VFS 
5f10: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5f20: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
5f30: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
5f40: 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20  0000200  /* VFS 
5f50: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5f60: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
5f70: 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30  SIENT_DB     0x0
5f80: 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20  0000400  /* VFS 
5f90: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5fa0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
5fb0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
5fc0: 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20  0000800  /* VFS 
5fd0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5fe0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
5ff0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
6000: 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20  0001000  /* VFS 
6010: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
6020: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
6030: 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30  OURNAL       0x0
6040: 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20  0002000  /* VFS 
6050: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
6060: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
6070: 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30  ER_JOURNAL   0x0
6080: 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20  0004000  /* VFS 
6090: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
60a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
60b0: 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30  TEX          0x0
60c0: 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0008000  /* Ok f
60d0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
60e0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
60f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
6100: 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30  MUTEX        0x0
6110: 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0010000  /* Ok f
6120: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
6130: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
6140: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
6150: 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30  EDCACHE      0x0
6160: 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0020000  /* Ok f
6170: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
6180: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
6190: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
61a0: 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30  ATECACHE     0x0
61b0: 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0040000  /* Ok f
61c0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
61d0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
61e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20  SQLITE_OPEN_WAL 
61f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6200: 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20  0080000  /* VFS 
6210: 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65  only */../* Rese
6220: 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20  rved:           
6230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6240: 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a  00F00000 */../*.
6250: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76  ** CAPI3REF: Dev
6260: 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74  ice Characterist
6270: 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44  ics.**.** The xD
6280: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
6290: 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  tics method of t
62a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
62b0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63  ethods].** objec
62c0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  t returns an int
62d0: 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20  eger which is a 
62e0: 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a  vector of these.
62f0: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
6300: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
6310: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
6320: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
6330: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
6340: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
6350: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
6360: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
6370: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
6380: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6390: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
63a0: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
63b0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
63c0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
63d0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
63e0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
63f0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6400: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
6410: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
6420: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
6430: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
6440: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
6450: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
6460: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
6470: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
6480: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6490: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
64a0: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
64b0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
64c0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
64d0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
64e0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
64f0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
6500: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
6510: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
6520: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
6530: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
6540: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
6550: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
6560: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
6570: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
6580: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
6590: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
65a0: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
65b0: 72 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c  rite().  The SQL
65c0: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
65d0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72  AFE_OVERWRITE pr
65e0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
65f0: 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f  t.** after reboo
6600: 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72  t following a cr
6610: 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73  ash or power los
6620: 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65  s, the only byte
6630: 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74  s in a.** file t
6640: 68 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e  hat were written
6650: 20 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74   at the applicat
6660: 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20  ion level might 
6670: 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  have changed.** 
6680: 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e  and that adjacen
6690: 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79  t bytes, even by
66a0: 74 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73  tes within the s
66b0: 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a  ame sector are.*
66c0: 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  * guaranteed to 
66d0: 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54  be unchanged.  T
66e0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
66f0: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
6700: 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e  _OPEN.** flag in
6710: 64 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69  dicate that a fi
6720: 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c  le cannot be del
6730: 65 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20  eted when open. 
6740: 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49   The.** SQLITE_I
6750: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66  OCAP_IMMUTABLE f
6760: 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68  lag indicates th
6770: 61 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f  at the file is o
6780: 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  n.** read-only m
6790: 65 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20  edia and cannot 
67a0: 62 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20  be changed even 
67b0: 62 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74  by processes wit
67c0: 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72  h.** elevated pr
67d0: 69 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65  ivileges..*/.#de
67e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
67f0: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
6800: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6810: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
6820: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
6830: 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20  12              
6840: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
6850: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6860: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
6870: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6880: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
6890: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20  _IOCAP_ATOMIC2K 
68a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
68b0: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
68c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
68d0: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20  OMIC4K          
68e0: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
68f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6900: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
6910: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6920: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
6930: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6940: 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20  IC16K           
6950: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64     0x00000040.#d
6960: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6970: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20  AP_ATOMIC32K    
6980: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6990: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0080.#define SQL
69a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
69b0: 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  64K             
69c0: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
69d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
69e0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
69f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
6a00: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6a10: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
6a20: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30  AL             0
6a30: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e  x00000400.#defin
6a40: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
6a50: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
6a60: 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30  OPEN  0x00000800
6a70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6a80: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6a90: 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30  OVERWRITE    0x0
6aa0: 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20  0001000.#define 
6ab0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
6ac0: 55 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  UTABLE          
6ad0: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a      0x00002000..
6ae0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6af0: 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76  File Locking Lev
6b00: 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  els.**.** SQLite
6b10: 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65   uses one of the
6b20: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
6b30: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  s as the second.
6b40: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  ** argument to c
6b50: 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f  alls it makes to
6b60: 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64   the xLock() and
6b70: 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f   xUnlock() metho
6b80: 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c  ds.** of an [sql
6b90: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6ba0: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66   object..*/.#def
6bb0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6bc0: 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a  NONE          0.
6bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6be0: 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20  OCK_SHARED      
6bf0: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
6c00: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
6c10: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
6c20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
6c30: 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66  ING       3.#def
6c40: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6c50: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a  EXCLUSIVE     4.
6c60: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6c70: 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   Synchronization
6c80: 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a   Type Flags.**.*
6c90: 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  * When SQLite in
6ca0: 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28  vokes the xSync(
6cb0: 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a  ) method of an.*
6cc0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
6cd0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74  thods] object it
6ce0: 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74   uses a combinat
6cf0: 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  ion of.** these 
6d00: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
6d10: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
6d20: 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ument..**.** Whe
6d30: 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  n the SQLITE_SYN
6d40: 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20  C_DATAONLY flag 
6d50: 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e  is used, it mean
6d60: 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79  s that the.** sy
6d70: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c  nc operation onl
6d80: 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68  y needs to flush
6d90: 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74   data to mass st
6da0: 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a  orage.  Inode.**
6db0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65   information nee
6dc0: 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64  d not be flushed
6dd0: 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  . If the lower f
6de0: 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20  our bits of the 
6df0: 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51  flag.** equal SQ
6e00: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
6e10: 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20  , that means to 
6e20: 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  use normal fsync
6e30: 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a  () semantics..**
6e40: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
6e50: 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51  ur bits equal SQ
6e60: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
6e70: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f  that means.** to
6e80: 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74   use Mac OS X st
6e90: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73  yle fullsync ins
6ea0: 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e  tead of fsync().
6eb0: 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f  .**.** Do not co
6ec0: 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45  nfuse the SQLITE
6ed0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
6ee0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6ef0: 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20  L flags.** with 
6f00: 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  the [PRAGMA sync
6f10: 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20  hronous]=NORMAL 
6f20: 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  and [PRAGMA sync
6f30: 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a  hronous]=FULL.**
6f40: 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20   settings.  The 
6f50: 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61  [synchronous pra
6f60: 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20  gma] determines 
6f70: 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68  when calls to th
6f80: 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d  e.** xSync VFS m
6f90: 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20  ethod occur and 
6fa0: 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c  applies uniforml
6fb0: 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61  y across all pla
6fc0: 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53  tforms..** The S
6fd0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6fe0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
6ff0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74  C_FULL flags det
7000: 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e  ermine how.** en
7010: 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72  ergetic or rigor
7020: 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20  ous or forceful 
7030: 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69  the sync operati
7040: 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f  ons are and.** o
7050: 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65  nly make a diffe
7060: 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58  rence on Mac OSX
7070: 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74   for the default
7080: 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a   SQLite code..**
7090: 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46   (Third-party VF
70a0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
70b0: 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b  s might also mak
70c0: 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
70d0: 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c  n.** between SQL
70e0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
70f0: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
7100: 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20  FULL, but among 
7110: 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67  the.** operating
7120: 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c   systems nativel
7130: 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  y supported by S
7140: 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20  QLite, only Mac 
7150: 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f  OSX.** cares abo
7160: 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63  ut the differenc
7170: 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e.).*/.#define S
7180: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
7190: 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32  L        0x00002
71a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
71b0: 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20  SYNC_FULL       
71c0: 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69     0x00003.#defi
71d0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  ne SQLITE_SYNC_D
71e0: 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30  ATAONLY      0x0
71f0: 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0010../*.** CAPI
7200: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
7210: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e  ce Open File Han
7220: 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71  dle.**.** An [sq
7230: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7240: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
7250: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68   open file in th
7260: 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  e .** [sqlite3_v
7270: 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63  fs | OS interfac
7280: 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76  e layer].  Indiv
7290: 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61  idual OS interfa
72a0: 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ce.** implementa
72b0: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61  tions will.** wa
72c0: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74  nt to subclass t
72d0: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70  his object by ap
72e0: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e  pending addition
72f0: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72  al fields.** for
7300: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20   their own use. 
7310: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e   The pMethods en
7320: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72  try is a pointer
7330: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
7340: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
7350: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
7360: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70  es methods for p
7370: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f  erforming.** I/O
7380: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
7390: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f  he open file..*/
73a0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
73b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c  sqlite3_file sql
73c0: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63  ite3_file;.struc
73d0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b  t sqlite3_file {
73e0: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20  .  const struct 
73f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7400: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f  ds *pMethods;  /
7410: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e  * Methods for an
7420: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b   open file */.};
7430: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7440: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46  : OS Interface F
7450: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68  ile Virtual Meth
7460: 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ods Object.**.**
7470: 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e   Every file open
7480: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
7490: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
74a0: 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61  thod populates a
74b0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  n.** [sqlite3_fi
74c0: 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20  le] object (or, 
74d0: 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61  more commonly, a
74e0: 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
74f0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7500: 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20  e] object) with 
7510: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
7520: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
7530: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73   object..** This
7540: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
7550: 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64  the methods used
7560: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
7570: 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ous operations.*
7580: 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70  * against the op
7590: 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e  en file represen
75a0: 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ted by the [sqli
75b0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
75c0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ..**.** If the [
75d0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
75e0: 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74  n] method sets t
75f0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
7600: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
7610: 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55   .** to a non-NU
7620: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
7630: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f   the sqlite3_io_
7640: 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d  methods.xClose m
7650: 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20  ethod.** may be 
7660: 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20  invoked even if 
7670: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
7680: 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64  .xOpen] reported
7690: 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e   that it failed.
76a0: 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61    The.** only wa
76b0: 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63  y to prevent a c
76c0: 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f  all to xClose fo
76d0: 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64  llowing a failed
76e0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
76f0: 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74  pen].** is for t
7700: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7710: 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68  xOpen] to set th
7720: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
7730: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a  Methods element.
7740: 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ** to NULL..**.*
7750: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
7760: 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61  ment to xSync ma
7770: 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  y be one of [SQL
7780: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d  ITE_SYNC_NORMAL]
7790: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53   or.** [SQLITE_S
77a0: 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20  YNC_FULL].  The 
77b0: 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20  first choice is 
77c0: 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  the normal fsync
77d0: 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ()..** The secon
77e0: 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61  d choice is a Ma
77f0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
7800: 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c  lsync.  The [SQL
7810: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7820: 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62  Y].** flag may b
7830: 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64  e ORed in to ind
7840: 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20  icate that only 
7850: 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20  the data of the 
7860: 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20  file.** and not 
7870: 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20  its inode needs 
7880: 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a  to be synced..**
7890: 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20  .** The integer 
78a0: 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28  values to xLock(
78b0: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
78c0: 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75  are one of.** <u
78d0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
78e0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a  TE_LOCK_NONE],.*
78f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7900: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
7910: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7920: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20  K_RESERVED],.** 
7930: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7940: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a  K_PENDING], or.*
7950: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7960: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a  OCK_EXCLUSIVE]..
7970: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63  ** </ul>.** xLoc
7980: 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68  k() increases th
7990: 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28  e lock. xUnlock(
79a0: 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20  ) decreases the 
79b0: 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68  lock..** The xCh
79c0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28  eckReservedLock(
79d0: 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20  ) method checks 
79e0: 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61  whether any data
79f0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
7a00: 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68  .** either in th
7a10: 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e  is process or in
7a20: 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63   some other proc
7a30: 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20  ess, is holding 
7a40: 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50  a RESERVED,.** P
7a50: 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55  ENDING, or EXCLU
7a60: 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  SIVE lock on the
7a70: 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72   file.  It retur
7a80: 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75  ns true.** if su
7a90: 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73  ch a lock exists
7aa0: 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72   and false other
7ab0: 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  wise..**.** The 
7ac0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
7ad0: 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72  ethod is a gener
7ae0: 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ic interface tha
7af0: 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a  t allows custom.
7b00: 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ** VFS implement
7b10: 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74  ations to direct
7b20: 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70  ly control an op
7b30: 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68  en file using th
7b40: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
7b50: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e  le_control()] in
7b60: 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65  terface.  The se
7b70: 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65  cond "op" argume
7b80: 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65  nt is an.** inte
7b90: 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65  ger opcode.  The
7ba0: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
7bb0: 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69  is a generic poi
7bc0: 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f  nter intended to
7bd0: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  .** point to a s
7be0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61  tructure that ma
7bf0: 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65  y contain argume
7c00: 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20  nts or space in 
7c10: 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74  which to.** writ
7c20: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e  e return values.
7c30: 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73    Potential uses
7c40: 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f   for xFileContro
7c50: 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20  l() might be.** 
7c60: 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61  functions to ena
7c70: 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63  ble blocking loc
7c80: 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73  ks with timeouts
7c90: 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a  , to change the.
7ca0: 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74  ** locking strat
7cb0: 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  egy (for example
7cc0: 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65   to use dot-file
7cd0: 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75   locks), to inqu
7ce0: 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65  ire.** about the
7cf0: 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63   status of a loc
7d00: 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73  k, or to break s
7d10: 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65  tale locks.  The
7d20: 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20   SQLite.** core 
7d30: 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63  reserves all opc
7d40: 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31  odes less than 1
7d50: 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75  00 for its own u
7d60: 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63  se..** A [file c
7d70: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c  ontrol opcodes |
7d80: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
7d90: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
7da0: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
7db0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
7dc0: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
7dd0: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
7de0: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
7df0: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
7e00: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
7e10: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
7e20: 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  .  VFS implement
7e30: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a  ations should.**
7e40: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
7e50: 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69  NOTFOUND] for fi
7e60: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
7e70: 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  es that they do 
7e80: 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65  not.** recognize
7e90: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
7ea0: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
7eb0: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
7ec0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
7ed0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
7ee0: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
7ef0: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
7f00: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
7f10: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
7f20: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
7f30: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
7f40: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
7f50: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
7f60: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
7f70: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
7f80: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
7f90: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
7fa0: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
7fb0: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
7fc0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
7fd0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
7fe0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7ff0: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
8000: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8010: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
8020: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8030: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
8040: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8050: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
8060: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8070: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
8080: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8090: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
80a0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
80b0: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
80c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
80d0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
80e0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
80f0: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
8100: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8110: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
8120: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8130: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
8140: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
8150: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8160: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
8170: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
8180: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
8190: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
81a0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
81b0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
81c0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
81d0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
81e0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
81f0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
8200: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
8210: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
8220: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
8230: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
8240: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
8250: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
8260: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
8270: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
8280: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
8290: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
82a0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
82b0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
82c0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
82d0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
82e0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
82f0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
8300: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
8310: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
8320: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
8330: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
8340: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
8350: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
8360: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
8370: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
8380: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
8390: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
83a0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
83b0: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
83c0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
83d0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
83e0: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
83f0: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
8400: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
8410: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
8420: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
8430: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
8440: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
8450: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
8460: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
8470: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
8480: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
8490: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
84a0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
84b0: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
84c0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
84d0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
84e0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
84f0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
8500: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
8510: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
8520: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
8530: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
8540: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
8550: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
8560: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
8570: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
8580: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
8590: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
85a0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
85b0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
85c0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
85d0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
85e0: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
85f0: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
8600: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
8610: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
8620: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
8630: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
8640: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
8650: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
8660: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8670: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
8680: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8690: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
86a0: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
86b0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
86c0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
86d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
86e0: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
86f0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
8700: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
8710: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
8720: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8730: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
8740: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
8750: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8760: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8770: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8780: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
8790: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
87a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
87b0: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
87c0: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
87d0: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
87e0: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
87f0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
8800: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
8810: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
8820: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
8830: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8840: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
8850: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8860: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
8870: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
8880: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
8890: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
88a0: 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29  .  int (*xFetch)
88b0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
88c0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
88d0: 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76  fst, int iAmt, v
88e0: 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74  oid **pp);.  int
88f0: 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c   (*xUnfetch)(sql
8900: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8910: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
8920: 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20   void *p);.  /* 
8930: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
8940: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
8950: 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64  ion 3 */.  /* Ad
8960: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
8970: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
8980: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
8990: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
89a0: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
89b0: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
89c0: 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  codes.** KEYWORD
89d0: 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  S: {file control
89e0: 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20   opcodes} {file 
89f0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a  control opcode}.
8a00: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
8a10: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
8a20: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
8a30: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
8a40: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
8a50: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
8a60: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
8a70: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
8a80: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
8a90: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  .** interface..*
8aa0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8ab0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
8ac0: 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54  LOCKSTATE]].** T
8ad0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8ae0: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
8af0: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
8b00: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
8b10: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
8b20: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
8b30: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
8b40: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
8b50: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
8b60: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
8b70: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
8b80: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
8b90: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
8ba0: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
8bb0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
8bc0: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
8bd0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
8be0: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
8bf0: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
8c00: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
8c10: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
8c20: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
8c30: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
8c40: 67 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76  g and is only av
8c50: 61 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65  ailable when the
8c60: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20   SQLITE_TEST.** 
8c70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
8c80: 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
8c90: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8ca0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8cb0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
8cc0: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
8cd0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8ce0: 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69   by SQLite to gi
8cf0: 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61  ve the VFS.** la
8d00: 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f  yer a hint of ho
8d10: 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61  w large the data
8d20: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67  base file will g
8d30: 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67  row to be during
8d40: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
8d50: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68  transaction.  Th
8d60: 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67  is hint is not g
8d70: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
8d80: 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a  accurate but it.
8d90: 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73  ** is often clos
8da0: 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69  e.  The underlyi
8db0: 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f  ng VFS might cho
8dc0: 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61  ose to prealloca
8dd0: 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  te database.** f
8de0: 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20  ile space based 
8df0: 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20  on this hint in 
8e00: 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72  order to help wr
8e10: 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61  ites to the data
8e20: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e  base.** file run
8e30: 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c   faster..**.** <
8e40: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8e50: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a  L_CHUNK_SIZE]].*
8e60: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
8e70: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20  NTL_CHUNK_SIZE] 
8e80: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
8e90: 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74  o request that t
8ea0: 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64  he VFS.** extend
8eb0: 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20  s and truncates 
8ec0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8ed0: 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61  e in chunks of a
8ee0: 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a   size specified.
8ef0: 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20  ** by the user. 
8f00: 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
8f10: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
8f20: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
8f30: 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74  should .** point
8f40: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28   to an integer (
8f50: 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69  type int) contai
8f60: 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75  ning the new chu
8f70: 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a  nk-size to use.*
8f80: 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61  * for the nomina
8f90: 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c  ted database. Al
8fa0: 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73  locating databas
8fb0: 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20  e file space in 
8fc0: 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20  large.** chunks 
8fd0: 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69  (say 1MB at a ti
8fe0: 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20  me), may reduce 
8ff0: 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67  file-system frag
9000: 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  mentation and.**
9010: 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d   improve perform
9020: 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73  ance on some sys
9030: 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tems..**.** <li>
9040: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  [[SQLITE_FCNTL_F
9050: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a  ILE_POINTER]].**
9060: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9070: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
9080: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9090: 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e  to obtain a poin
90a0: 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ter.** to the [s
90b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
90c0: 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  ect associated w
90d0: 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
90e0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
90f0: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68  nection.  See th
9100: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
9110: 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d  control()] docum
9120: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
9130: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
9140: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  mation..**.** <l
9150: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9160: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a  _SYNC_OMITTED]].
9170: 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20  ** No longer in 
9180: 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  use..**.** <li>[
9190: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
91a0: 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NC]].** The [SQL
91b0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20  ITE_FCNTL_SYNC] 
91c0: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
91d0: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
91e0: 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20  y SQLite and.** 
91f0: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
9200: 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f  immediately befo
9210: 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  re the xSync met
9220: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  hod is invoked o
9230: 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  n a.** database 
9240: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e  file descriptor.
9250: 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e   Or, if the xSyn
9260: 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20  c method is not 
9270: 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61  invoked .** beca
9280: 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73  use the user has
9290: 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69   configured SQLi
92a0: 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41  te with .** [PRA
92b0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20  GMA synchronous 
92c0: 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f  | PRAGMA synchro
92d0: 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20  nous=OFF] it is 
92e0: 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65  invoked in place
92f0: 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e   .** of the xSyn
9300: 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73  c method. In mos
9310: 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69  t cases, the poi
9320: 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61  nter argument pa
9330: 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69  ssed with.** thi
9340: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
9350: 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c  s NULL. However,
9360: 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65   if the database
9370: 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73   file is being s
9380: 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74  ynced.** as part
9390: 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61   of a multi-data
93a0: 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65  base commit, the
93b0: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
93c0: 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e   to a nul-termin
93d0: 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63  ated.** string c
93e0: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72  ontaining the tr
93f0: 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65  ansactions maste
9400: 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e  r-journal file n
9410: 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20  ame. VFSes that 
9420: 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  .** do not need 
9430: 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75  this signal shou
9440: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
9450: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  re this opcode. 
9460: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a  Applications .**
9470: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
9480: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9490: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
94a0: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
94b0: 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64  ing so may .** d
94c0: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61  isrupt the opera
94d0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
94e0: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
94f0: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
9500: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
9510: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
9520: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a  MIT_PHASETWO]].*
9530: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9540: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
9550: 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  TWO] opcode is g
9560: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
9570: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  lly by SQLite.**
9580: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65   and sent to the
9590: 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61   VFS after a tra
95a0: 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65  nsaction has bee
95b0: 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65  n committed imme
95c0: 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62  diately.** but b
95d0: 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61  efore the databa
95e0: 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20  se is unlocked. 
95f0: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  VFSes that do no
9600: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
9610: 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c  al.** should sil
9620: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
9630: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
9640: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
9650: 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
9660: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9670: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63  )] with this opc
9680: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
9690: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
96a0: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  .** operation of
96b0: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
96c0: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72   VFSes that do r
96d0: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
96e0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
96f0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
9700: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  ETRY]].** ^The [
9710: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
9720: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
9730: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
9740: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
9750: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
9760: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
9770: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
9780: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
9790: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
97a0: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
97b0: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  er to provide ro
97c0: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20  bustness in the 
97d0: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61  presence of.** a
97e0: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61  nti-virus progra
97f0: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ms.  By default,
9800: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
9810: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65   will retry file
9820: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77   read,.** file w
9830: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64  rite, and file d
9840: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  elete operations
9850: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
9860: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
9870: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
9880: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
9890: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
98a0: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
98b0: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
98c0: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
98d0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
98e0: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
98f0: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
9900: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
9910: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73  these two values
9920: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
9930: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
9940: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
9950: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
9960: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
9970: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
9980: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
9990: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
99a0: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
99b0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
99c0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
99d0: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
99e0: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
99f0: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
9a00: 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79   i the new retry
9a10: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73   count and the s
9a20: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  econd.** integer
9a30: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20   is the delay.  
9a40: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65  If either intege
9a50: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
9a60: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a  hen the setting.
9a70: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
9a80: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68  d but instead th
9a90: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
9aa0: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73   that setting is
9ab0: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f   written.** into
9ac0: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79   the array entry
9ad0: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63  , allowing the c
9ae0: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74  urrent retry set
9af0: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69  tings to be.** i
9b00: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
9b10: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65  e zDbName parame
9b20: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  ter is ignored..
9b30: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9b40: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
9b50: 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  _WAL]].** ^The [
9b60: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
9b70: 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65  SIST_WAL] opcode
9b80: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9b90: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9ba0: 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20  persistent [WAL 
9bb0: 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f  | Write Ahead Lo
9bc0: 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20  g] setting.  By 
9bd0: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78  default, the aux
9be0: 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20  iliary.** write 
9bf0: 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68  ahead log and sh
9c00: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
9c10: 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73  s used for trans
9c20: 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a  action control.*
9c30: 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  * are automatica
9c40: 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e  lly deleted when
9c50: 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e   the latest conn
9c60: 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61  ection to the da
9c70: 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73  tabase.** closes
9c80: 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69  .  Setting persi
9c90: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63  stent WAL mode c
9ca0: 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65  auses those file
9cb0: 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74  s to persist aft
9cc0: 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65  er.** close.  Pe
9cd0: 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c  rsisting the fil
9ce0: 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65  es is useful whe
9cf0: 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65  n other processe
9d00: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a  s that do not.**
9d10: 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d   have write perm
9d20: 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69  ission on the di
9d30: 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69  rectory containi
9d40: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
9d50: 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20  file want.** to 
9d60: 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73  read the databas
9d70: 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57  e file, as the W
9d80: 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  AL and shared me
9d90: 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20  mory files must 
9da0: 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65  exist.** in orde
9db0: 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  r for the databa
9dc0: 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c  se to be readabl
9dd0: 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  e.  The fourth p
9de0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
9df0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9e00: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
9e10: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
9e20: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
9e30: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
9e40: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
9e50: 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69  to disable persi
9e60: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f  stent WAL mode o
9e70: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65  r 1 to enable pe
9e80: 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20  rsistent.** WAL 
9e90: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
9ea0: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
9eb0: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
9ec0: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
9ed0: 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73  rent.** WAL pers
9ee0: 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e  istence setting.
9ef0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9f00: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
9f10: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  AFE_OVERWRITE]].
9f20: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
9f30: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
9f40: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
9f50: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
9f60: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
9f70: 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77   persistent "pow
9f80: 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65  ersafe-overwrite
9f90: 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74  " or "PSOW" sett
9fa0: 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73  ing.  The PSOW s
9fb0: 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d  etting.** determ
9fc0: 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45  ines the [SQLITE
9fd0: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
9fe0: 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20  _OVERWRITE] bit 
9ff0: 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63  of the.** xDevic
a000: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
a010: 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f   methods. The fo
a020: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
a030: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
a040: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
a050: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
a060: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
a070: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
a080: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
a090: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
a0a0: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
a0b0: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
a0c0: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20   zero-damage.** 
a0d0: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
a0e0: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
a0f0: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
a100: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
a110: 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d  rent.** zero-dam
a120: 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67  age mode setting
a130: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a140: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
a150: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
a160: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
a170: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
a180: 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  s invoked by SQL
a190: 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e  ite after openin
a1a0: 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61  g.** a write tra
a1b0: 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69  nsaction to indi
a1c0: 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73  cate that, unles
a1d0: 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62  s it is rolled b
a1e0: 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20  ack for some.** 
a1f0: 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69  reason, the enti
a200: 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  re database file
a210: 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69   will be overwri
a220: 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72  tten by the curr
a230: 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ent .** transact
a240: 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65  ion. This is use
a250: 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72  d by VACUUM oper
a260: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ations..**.** <l
a270: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a280: 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54  _VFSNAME]].** ^T
a290: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a2a0: 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65  _VFSNAME] opcode
a2b0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
a2c0: 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  obtain the names
a2d0: 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65   of.** all [VFSe
a2e0: 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  s] in the VFS st
a2f0: 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20  ack.  The names 
a300: 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73  are of all VFS s
a310: 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  hims and the.** 
a320: 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76  final bottom-lev
a330: 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74  el VFS are writt
a340: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
a350: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
a360: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
a370: 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75  ()] and the resu
a380: 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  lt is stored in 
a390: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
a3a0: 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66  le.** that the f
a3b0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a3c0: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  of [sqlite3_file
a3d0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e  _control()] poin
a3e0: 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61  ts to..** The ca
a3f0: 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69  ller is responsi
a400: 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20  ble for freeing 
a410: 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20  the memory when 
a420: 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a  done.  As with.*
a430: 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72  * all file-contr
a440: 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72  ol actions, ther
a450: 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65  e is no guarante
a460: 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c  e that this will
a470: 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20   actually.** do 
a480: 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65  anything.  Calle
a490: 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61  rs should initia
a4a0: 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76  lize the char* v
a4b0: 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c  ariable to a NUL
a4c0: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20  L.** pointer in 
a4d0: 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63  case this file-c
a4e0: 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d  ontrol is not im
a4f0: 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73  plemented.  This
a500: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
a510: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
a520: 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20   diagnostic use 
a530: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  only..**.** <li>
a540: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
a550: 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e  RAGMA]].** ^When
a560: 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20  ever a [PRAGMA] 
a570: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72  statement is par
a580: 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f  sed, an [SQLITE_
a590: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a  FCNTL_PRAGMA] .*
a5a0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  * file control i
a5b0: 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70  s sent to the op
a5c0: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  en [sqlite3_file
a5d0: 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70  ] object corresp
a5e0: 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65  onding.** to the
a5f0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
a600: 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67  o which the prag
a610: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66  ma statement ref
a620: 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65  ers. ^The argume
a630: 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51  nt.** to the [SQ
a640: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a650: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
a660: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a  is an array of.*
a670: 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  * pointers to st
a680: 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69  rings (char**) i
a690: 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f  n which the seco
a6a0: 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68  nd element of th
a6b0: 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68  e array.** is th
a6c0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72  e name of the pr
a6d0: 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69  agma and the thi
a6e0: 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68  rd element is th
a6f0: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  e argument to th
a700: 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e  e.** pragma or N
a710: 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d  ULL if the pragm
a720: 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e  a has no argumen
a730: 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  t.  ^The handler
a740: 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49   for an.** [SQLI
a750: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a760: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61   file control ca
a770: 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b  n optionally mak
a780: 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d  e the first elem
a790: 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68  ent.** of the ch
a7a0: 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f  ar** argument po
a7b0: 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
a7c0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
a7d0: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
a7e0: 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69  ].** or the equi
a7f0: 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20  valent and that 
a800: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f  string will beco
a810: 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  me the result of
a820: 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a   the pragma or.*
a830: 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  * the error mess
a840: 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d  age if the pragm
a850: 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65  a fails. ^If the
a860: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
a870: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
a880: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
a890: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
a8a0: 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a  , then normal .*
a8b0: 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65  * [PRAGMA] proce
a8c0: 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e  ssing continues.
a8d0: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
a8e0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
a8f0: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
a900: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
a910: 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61  OK], then the pa
a920: 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61  rser assumes tha
a930: 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73  t the.** VFS has
a940: 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41   handled the PRA
a950: 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74  GMA itself and t
a960: 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61  he parser genera
a970: 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70  tes a no-op.** p
a980: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
a990: 74 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69  t if result stri
a9a0: 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74  ng is NULL, or t
a9b0: 68 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f  hat returns a co
a9c0: 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  py.** of the res
a9d0: 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68  ult string if th
a9e0: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d  e string is non-
a9f0: 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  NULL..** ^If the
aa00: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
aa10: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
aa20: 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  rol returns.** a
aa30: 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f  ny result code o
aa40: 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
aa50: 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45  E_OK] or [SQLITE
aa60: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74  _NOTFOUND], that
aa70: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74   means.** that t
aa80: 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72  he VFS encounter
aa90: 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c  ed an error whil
aaa0: 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b  e handling the [
aab0: 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a  PRAGMA] and the.
aac0: 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f  ** compilation o
aad0: 66 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69  f the PRAGMA fai
aae0: 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ls with an error
aaf0: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
ab00: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
ab10: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63   file control oc
ab20: 63 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69  curs at the begi
ab30: 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20  nning of pragma 
ab40: 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73  statement analys
ab50: 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20  is and so.** it 
ab60: 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72  is able to overr
ab70: 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52  ide built-in [PR
ab80: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73  AGMA] statements
ab90: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
aba0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
abb0: 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65  ANDLER]].** ^The
abc0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42   [SQLITE_FCNTL_B
abd0: 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66  USYHANDLER].** f
abe0: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20  ile-control may 
abf0: 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51  be invoked by SQ
ac00: 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61  Lite on the data
ac10: 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65  base file handle
ac20: 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65  .** shortly afte
ac30: 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69  r it is opened i
ac40: 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69  n order to provi
ac50: 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20  de a custom VFS 
ac60: 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74  with access.** t
ac70: 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  o the connection
ac80: 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63  s busy-handler c
ac90: 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67  allback. The arg
aca0: 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65  ument is of type
acb0: 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20   (void **).** - 
acc0: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20  an array of two 
acd0: 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e  (void *) values.
ace0: 20 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64   The first (void
acf0: 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69   *) actually poi
ad00: 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63  nts.** to a func
ad10: 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e  tion of type (in
ad20: 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20  t (*)(void *)). 
ad30: 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f  In order to invo
ad40: 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ke the connectio
ad50: 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c  ns.** busy-handl
ad60: 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  er, this functio
ad70: 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f  n should be invo
ad80: 6b 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63  ked with the sec
ad90: 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a  ond (void *) in.
ada0: 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20  ** the array as 
adb0: 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e  the only argumen
adc0: 74 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  t. If it returns
add0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
ade0: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
adf0: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69   should be retri
ae00: 65 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e  ed. If it return
ae10: 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74  s zero, the cust
ae20: 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62  om VFS should ab
ae30: 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72  andon the.** cur
ae40: 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a  rent operation..
ae50: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
ae60: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
ae70: 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c  ENAME]].** ^Appl
ae80: 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f  ication can invo
ae90: 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  ke the [SQLITE_F
aea0: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
aeb0: 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a  E] file-control.
aec0: 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74  ** to have SQLit
aed0: 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20  e generate a.** 
aee0: 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61  temporary filena
aef0: 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  me using the sam
af00: 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74  e algorithm that
af10: 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20   is followed to 
af20: 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70  generate.** temp
af30: 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20  orary filenames 
af40: 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20  for TEMP tables 
af50: 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e  and other intern
af60: 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a  al uses.  The.**
af70: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
af80: 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69   be a char** whi
af90: 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65  ch will be fille
afa0: 64 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e  d with the filen
afb0: 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69  ame.** written i
afc0: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
afd0: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
afe0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68  3_malloc()].  Th
aff0: 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a  e caller should.
b000: 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ** invoke [sqlit
b010: 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68  e3_free()] on th
b020: 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69  e result to avoi
b030: 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e  d a memory leak.
b040: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b050: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
b060: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
b070: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
b080: 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  SIZE] file contr
b090: 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75  ol is used to qu
b0a0: 65 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a  ery or set the.*
b0b0: 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  * maximum number
b0c0: 20 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77   of bytes that w
b0d0: 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20  ill be used for 
b0e0: 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f  memory-mapped I/
b0f0: 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  O..** The argume
b100: 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
b110: 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79  to a value of ty
b120: 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  pe sqlite3_int64
b130: 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61   that.** is an a
b140: 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20  dvisory maximum 
b150: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
b160: 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d  in the file to m
b170: 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a  emory map.  The.
b180: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76  ** pointer is ov
b190: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
b1a0: 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54  he old value.  T
b1b0: 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20  he limit is not 
b1c0: 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68  changed if.** th
b1d0: 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c  e value original
b1e0: 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73  ly pointed to is
b1f0: 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73   negative, and s
b200: 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69  o the current li
b210: 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71  mit .** can be q
b220: 75 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e  ueried by passin
b230: 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74  g in a pointer t
b240: 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  o a negative num
b250: 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69  ber.  This.** fi
b260: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le-control is us
b270: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
b280: 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47   implement [PRAG
b290: 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a  MA mmap_size]..*
b2a0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b2b0: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a  E_FCNTL_TRACE]].
b2c0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
b2d0: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65  CNTL_TRACE] file
b2e0: 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65   control provide
b2f0: 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72  s advisory infor
b300: 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65  mation.** to the
b310: 20 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20   VFS about what 
b320: 74 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72  the higher layer
b330: 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20  s of the SQLite 
b340: 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e  stack are doing.
b350: 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f  .** This file co
b360: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79  ntrol is used by
b370: 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69   some VFS activi
b380: 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d  ty tracing [shim
b390: 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  s]..** The argum
b3a0: 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65  ent is a zero-te
b3b0: 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e  rminated string.
b3c0: 20 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20    Higher layers 
b3d0: 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  in the.** SQLite
b3e0: 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72   stack may gener
b3f0: 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66  ate instances of
b400: 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72   this file contr
b410: 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51  ol if.** the [SQ
b420: 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54  LITE_USE_FCNTL_T
b430: 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  RACE] compile-ti
b440: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
b450: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  bled..**.** <li>
b460: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48  [[SQLITE_FCNTL_H
b470: 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68  AS_MOVED]].** Th
b480: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b490: 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20  HAS_MOVED] file 
b4a0: 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65  control interpre
b4b0: 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20  ts its argument 
b4c0: 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  as a.** pointer 
b4d0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e  to an integer an
b4e0: 64 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f  d it writes a bo
b4f0: 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20  olean into that 
b500: 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e  integer dependin
b510: 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  g.** on whether 
b520: 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20  or not the file 
b530: 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64  has been renamed
b540: 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65  , moved, or dele
b550: 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20  ted since it.** 
b560: 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64  was first opened
b570: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b580: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
b590: 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a  _SET_HANDLE]].**
b5a0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b5b0: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
b5c0: 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  DLE] opcode is u
b5d0: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
b5e0: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
b5f0: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46  de causes the xF
b600: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
b610: 64 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69  d to swap the fi
b620: 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74  le handle with t
b630: 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65  he one.** pointe
b640: 64 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67  d to by the pArg
b650: 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73   argument.  This
b660: 20 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75   capability is u
b670: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
b680: 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e  ng.** and only n
b690: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
b6a0: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
b6b0: 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64  _TEST is defined
b6c0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b6d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
b6e0: 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  LOCK]].** The [S
b6f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f  QLITE_FCNTL_WAL_
b700: 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e  BLOCK] is a sign
b710: 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61  al to the VFS la
b720: 79 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68  yer that it migh
b730: 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67  t.** be advantag
b740: 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e  eous to block on
b750: 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f   the next WAL lo
b760: 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69  ck if the lock i
b770: 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c  s not immediatel
b780: 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20  y.** available. 
b790: 20 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74   The WAL subsyst
b7a0: 65 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73  em issues this s
b7b0: 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72  ignal during rar
b7c0: 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63  e.** circumstanc
b7d0: 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  es in order to f
b7e0: 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74  ix a problem wit
b7f0: 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72  h priority inver
b800: 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  sion..** Applica
b810: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d  tions should <em
b820: 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68  >not</em> use th
b830: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e  is file-control.
b840: 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  .**.** </ul>.*/.
b850: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b860: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20  CNTL_LOCKSTATE  
b870: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
b880: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b890: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
b8a0: 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64  YFILE       2.#d
b8b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b8c0: 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_SET_LOCKPROXY
b8d0: 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65  FILE       3.#de
b8e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b8f0: 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  L_LAST_ERRNO    
b900: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
b910: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b920: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
b930: 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
b940: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b950: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20  CHUNK_SIZE      
b960: 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
b970: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  e SQLITE_FCNTL_F
b980: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  ILE_POINTER     
b990: 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
b9a0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
b9b0: 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20  NC_OMITTED      
b9c0: 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
b9d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
b9e0: 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20  32_AV_RETRY     
b9f0: 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
ba00: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
ba10: 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20  IST_WAL         
ba20: 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
ba30: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
ba40: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
ba50: 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    11.#define SQL
ba60: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
ba70: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
ba80: 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   12.#define SQLI
ba90: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
baa0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
bab0: 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  13.#define SQLIT
bac0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20  E_FCNTL_PRAGMA  
bad0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
bae0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
baf0: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
bb00: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35  ER            15
bb10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bb20: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
bb30: 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a  ME           16.
bb40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bb50: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  CNTL_MMAP_SIZE  
bb60: 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23              18.#
bb70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bb80: 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20  NTL_TRACE       
bb90: 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64             19.#d
bba0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bbb0: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20  TL_HAS_MOVED    
bbc0: 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65            20.#de
bbd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bbe0: 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  L_SYNC          
bbf0: 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66           21.#def
bc00: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bc10: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
bc20: 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69          22.#defi
bc30: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bc40: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
bc50: 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e         23.#defin
bc60: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
bc70: 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20  AL_BLOCK        
bc80: 20 20 20 20 20 20 32 34 0a 0a 2f 2a 20 64 65 70        24../* dep
bc90: 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f  recated names */
bca0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bcb0: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
bcc0: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43  E      SQLITE_FC
bcd0: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
bce0: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51  YFILE.#define SQ
bcf0: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_SET_LOCKPRO
bd00: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49  XYFILE      SQLI
bd10: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43  TE_FCNTL_SET_LOC
bd20: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69  KPROXYFILE.#defi
bd30: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
bd40: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
bd50: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
bd60: 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a  ST_ERRNO.../*.**
bd70: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
bd80: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68   Handle.**.** Th
bd90: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
bda0: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
bdb0: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
bdc0: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
bdd0: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
bde0: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
bdf0: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
be00: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
be10: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
be20: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
be30: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
be40: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
be50: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
be60: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
be70: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
be80: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
be90: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
bea0: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
beb0: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
bec0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
bed0: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
bee0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
bef0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
bf00: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62   OS Interface Ob
bf10: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ject.**.** An in
bf20: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71  stance of the sq
bf30: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
bf40: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
bf50: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a  erface between.*
bf60: 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * the SQLite cor
bf70: 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c  e and the underl
bf80: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
bf90: 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73  ystem.  The "vfs
bfa0: 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65  ".** in the name
bfb0: 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73   of the object s
bfc0: 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75  tands for "virtu
bfd0: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e  al file system".
bfe0: 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46    See.** the [VF
bff0: 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74  S | VFS document
c000: 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68  ation] for furth
c010: 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  er information..
c020: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
c030: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
c040: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
c050: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
c060: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
c070: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
c080: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
c090: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
c0a0: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
c0b0: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
c0c0: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
c0d0: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
c0e0: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
c0f0: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
c100: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
c110: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
c120: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
c130: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
c140: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
c150: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
c160: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
c170: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
c180: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
c190: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
c1a0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
c1b0: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
c1c0: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
c1d0: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
c1e0: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
c1f0: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
c200: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
c210: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
c220: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
c230: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
c240: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
c250: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
c260: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
c270: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
c280: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
c290: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
c2a0: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
c2b0: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
c2c0: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
c2d0: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
c2e0: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
c2f0: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
c300: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
c310: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
c320: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
c330: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
c340: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
c350: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
c360: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
c370: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
c380: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
c390: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
c3a0: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
c3b0: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
c3c0: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
c3d0: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
c3e0: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
c3f0: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
c400: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
c410: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
c420: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
c430: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
c440: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
c450: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
c460: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
c470: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
c480: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
c490: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
c4a0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
c4b0: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
c4c0: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
c4d0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
c4e0: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
c4f0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
c500: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
c510: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
c520: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
c530: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
c540: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
c550: 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c  .xOpen]].** ^SQL
c560: 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
c570: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
c580: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
c590: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65  Open.** is eithe
c5a0: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
c5b0: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69   or string obtai
c5c0: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c  ned.** from xFul
c5d0: 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68  lPathname() with
c5e0: 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66   an optional suf
c5f0: 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49  fix added..** ^I
c600: 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64  f a suffix is ad
c610: 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65  ded to the zFile
c620: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20  name parameter, 
c630: 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69  it will.** consi
c640: 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22  st of a single "
c650: 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c  -" character fol
c660: 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65  lowed by no more
c670: 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68   than.** 11 alph
c680: 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20  anumeric and/or 
c690: 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a  "-" characters..
c6a0: 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68  ** ^SQLite furth
c6b0: 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  er guarantees th
c6c0: 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  at.** the string
c6d0: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
c6e0: 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74  nd unchanged unt
c6f0: 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a  il xClose() is.*
c700: 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73  * called. Becaus
c710: 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75  e of the previou
c720: 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74  s sentence,.** t
c730: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
c740: 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f  ] can safely sto
c750: 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  re a pointer to 
c760: 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  the.** filename 
c770: 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72  if it needs to r
c780: 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65  emember the file
c790: 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65  name for some re
c7a0: 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ason..** If the 
c7b0: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
c7c0: 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20  ter to xOpen is 
c7d0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
c7e0: 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73  hen xOpen.** mus
c7f0: 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e  t invent its own
c800: 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20   temporary name 
c810: 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e  for the file.  ^
c820: 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a  Whenever the .**
c830: 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   xFilename param
c840: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20  eter is NULL it 
c850: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65  will also be the
c860: 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a   case that the.*
c870: 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  * flags paramete
c880: 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b  r will include [
c890: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
c8a0: 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a  TEONCLOSE]..**.*
c8b0: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
c8c0: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20  ment to xOpen() 
c8d0: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74  includes all bit
c8e0: 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20  s set in.** the 
c8f0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
c900: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
c910: 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73  v2()].  Or if [s
c920: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
c930: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
c940: 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  en16()] is used,
c950: 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c   then flags incl
c960: 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a  udes at least.**
c970: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
c980: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
c990: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
c9a0: 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20   .** If xOpen() 
c9b0: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
c9c0: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
c9d0: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
c9e0: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
c9f0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
ca00: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
ca10: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
ca20: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
ca30: 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61   ^(SQLite will a
ca40: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
ca50: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
ca60: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28  gs to the xOpen(
ca70: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e  ).** call, depen
ca80: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65  ding on the obje
ca90: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a  ct being opened:
caa0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
cab0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
cac0: 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_MAIN_DB].** <l
cad0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
cae0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _MAIN_JOURNAL].*
caf0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
cb00: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a  OPEN_TEMP_DB].**
cb10: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
cb20: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
cb30: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
cb40: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
cb50: 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  T_DB].** <li>  [
cb60: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
cb70: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
cb80: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
cb90: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  STER_JOURNAL].**
cba0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
cbb0: 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  PEN_WAL].** </ul
cbc0: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  >)^.**.** The fi
cbd0: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
cbe0: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
cbf0: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
cc00: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65  ags to.** change
cc10: 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c   the way it deal
cc20: 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46  s with files.  F
cc30: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  or example, an a
cc40: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68  pplication.** th
cc50: 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  at does not care
cc60: 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63   about crash rec
cc70: 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63  overy or rollbac
cc80: 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20  k might make.** 
cc90: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f  the open of a jo
cca0: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d  urnal file a no-
ccb0: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  op.  Writes to t
ccc0: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  his journal woul
ccd0: 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d  d.** also be no-
cce0: 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74  ops, and any att
ccf0: 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65  empt to read the
cd00: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72   journal would r
cd10: 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
cd20: 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69  IOERR.  Or the i
cd30: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
cd40: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
cd50: 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  at a database.**
cd60: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f   file will be do
cd70: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
cd80: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
cd90: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
cda0: 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  ndom.** order an
cdb0: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
cdc0: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
cdd0: 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51  dingly..**.** SQ
cde0: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
cdf0: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
ce00: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
ce10: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
ce20: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
ce30: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
ce40: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
ce50: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
ce60: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
ce70: 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  E].** </ul>.**.*
ce80: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  * The [SQLITE_OP
ce90: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
cea0: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
ceb0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a   file should be.
cec0: 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ** deleted when 
ced0: 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e  it is closed.  ^
cee0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
cef0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
cf00: 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66  ** will be set f
cf10: 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65  or TEMP database
cf20: 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72  s and their jour
cf30: 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a  nals, transient.
cf40: 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e  ** databases, an
cf50: 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a  d subjournals..*
cf60: 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
cf70: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
cf80: 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73  ] flag is always
cf90: 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63   used in conjunc
cfa0: 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  tion.** with the
cfb0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
cfc0: 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63  EATE] flag, whic
cfd0: 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63  h are both direc
cfe0: 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73  tly.** analogous
cff0: 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61   to the O_EXCL a
d000: 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73  nd O_CREAT flags
d010: 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70   of the POSIX op
d020: 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68  en().** API.  Th
d030: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58  e SQLITE_OPEN_EX
d040: 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68  CLUSIVE flag, wh
d050: 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74  en paired with t
d060: 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50  he .** SQLITE_OP
d070: 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73  EN_CREATE, is us
d080: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
d090: 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  hat file should 
d0a0: 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65  always.** be cre
d0b0: 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69  ated, and that i
d0c0: 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66  t is an error if
d0d0: 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73   it already exis
d0e0: 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e  ts..** It is <i>
d0f0: 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20  not</i> used to 
d100: 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c  indicate the fil
d110: 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e  e should be open
d120: 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75  ed .** for exclu
d130: 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a  sive access..**.
d140: 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f  ** ^At least szO
d150: 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d  sFile bytes of m
d160: 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61  emory are alloca
d170: 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  ted by SQLite.**
d180: 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73   to hold the  [s
d190: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72  qlite3_file] str
d1a0: 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73  ucture passed as
d1b0: 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   the third.** ar
d1c0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e  gument to xOpen.
d1d0: 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68    The xOpen meth
d1e0: 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  od does not have
d1f0: 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20   to.** allocate 
d200: 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69  the structure; i
d210: 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69  t should just fi
d220: 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20  ll it in.  Note 
d230: 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65  that.** the xOpe
d240: 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65  n method must se
d250: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
d260: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65  le.pMethods to e
d270: 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64  ither.** a valid
d280: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
d290: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20  hods] object or 
d2a0: 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20  to NULL.  xOpen 
d2b0: 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20  must do.** this 
d2c0: 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e  even if the open
d2d0: 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20   fails.  SQLite 
d2e0: 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65  expects that the
d2f0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
d300: 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e  ethods.** elemen
d310: 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  t will be valid 
d320: 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75  after xOpen retu
d330: 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f  rns regardless o
d340: 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a  f the success.**
d350: 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74   or failure of t
d360: 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a  he xOpen call..*
d370: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
d380: 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20  fs.xAccess]].** 
d390: 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d  ^The flags argum
d3a0: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
d3b0: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
d3c0: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
d3d0: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
d3e0: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
d3f0: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
d400: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
d410: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
d420: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
d430: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
d440: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
d450: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
d460: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
d470: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
d480: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
d490: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
d4a0: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
d4b0: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
d4c0: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
d4d0: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
d4e0: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
d4f0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
d500: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
d510: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78  athname.  The ex
d520: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
d530: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
d540: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
d550: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
d560: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
d570: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
d580: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  uffer.** is not 
d590: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
d5a0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
d5b0: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
d5c0: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69  ed. Since this i
d5d0: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20  s.** handled as 
d5e0: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
d5f0: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70   SQLite, vfs imp
d600: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
d610: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20  uld endeavor.** 
d620: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
d630: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74  by setting mxPat
d640: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
d650: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
d660: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  lue..**.** The x
d670: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53  Randomness(), xS
d680: 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74  leep(), xCurrent
d690: 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72  Time(), and xCur
d6a0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a  rentTimeInt64().
d6b0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ** interfaces ar
d6c0: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
d6d0: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
d6e0: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
d6f0: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
d700: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
d710: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
d720: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
d730: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
d740: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
d750: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
d760: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
d770: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
d780: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
d790: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
d7a0: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
d7b0: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
d7c0: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
d7d0: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
d7e0: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
d7f0: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
d800: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
d810: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
d820: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
d830: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
d840: 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75  given.  ^The xCu
d850: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
d860: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
d870: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
d880: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
d890: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  t date and time 
d8a0: 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67  as.** a floating
d8b0: 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a   point value..**
d8c0: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
d8d0: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
d8e0: 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20   returns, as an 
d8f0: 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c  integer, the Jul
d900: 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65  ian.** Day Numbe
d910: 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20  r multiplied by 
d920: 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75  86400000 (the nu
d930: 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
d940: 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34  onds in .** a 24
d950: 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a  -hour day).  .**
d960: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
d970: 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69  e the xCurrentTi
d980: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
d990: 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72   to get the curr
d9a0: 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20  ent.** date and 
d9b0: 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74  time if that met
d9c0: 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65  hod is available
d9d0: 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73   (if iVersion is
d9e0: 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65   2 or .** greate
d9f0: 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69  r and the functi
da00: 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
da10: 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c  t NULL) and will
da20: 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f   fall back.** to
da30: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20   xCurrentTime() 
da40: 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  if xCurrentTimeI
da50: 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69  nt64() is unavai
da60: 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lable..**.** ^Th
da70: 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  e xSetSystemCall
da80: 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61  (), xGetSystemCa
da90: 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53  ll(), and xNestS
daa0: 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65  ystemCall() inte
dab0: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
dac0: 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51  t used by the SQ
dad0: 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73  Lite core.  Thes
dae0: 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72  e optional inter
daf0: 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
db00: 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46  ed.** by some VF
db10: 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74  Ses to facilitat
db20: 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65  e testing of the
db30: 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76   VFS code. By ov
db40: 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73  erriding .** sys
db50: 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66  tem calls with f
db60: 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69  unctions under i
db70: 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65  ts control, a te
db80: 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a  st program can.*
db90: 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74  * simulate fault
dba0: 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64  s and error cond
dbb0: 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c  itions that woul
dbc0: 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64  d otherwise be d
dbd0: 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69  ifficult.** or i
dbe0: 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64  mpossible to ind
dbf0: 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66  uce.  The set of
dc00: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68   system calls th
dc10: 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  at can be overri
dc20: 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66  dden.** varies f
dc30: 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61  rom one VFS to a
dc40: 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d  nother, and from
dc50: 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20   one version of 
dc60: 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20  the same VFS to 
dc70: 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70  the.** next.  Ap
dc80: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
dc90: 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66  use these interf
dca0: 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65  aces must be pre
dcb0: 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a  pared for any.**
dcc0: 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65   or all of these
dcd0: 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62   interfaces to b
dce0: 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68  e NULL or for th
dcf0: 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20  eir behavior to 
dd00: 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f  change.** from o
dd10: 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68  ne release to th
dd20: 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  e next.  Applica
dd30: 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61  tions must not a
dd40: 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73  ttempt to access
dd50: 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65  .** any of these
dd60: 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20   methods if the 
dd70: 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20  iVersion of the 
dd80: 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e  VFS is less than
dd90: 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73   3..*/.typedef s
dda0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
ddb0: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74  s sqlite3_vfs;.t
ddc0: 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
ddd0: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
dde0: 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74  r)(void);.struct
ddf0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
de00: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
de10: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
de20: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
de30: 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79  umber (currently
de40: 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f   3) */.  int szO
de50: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
de60: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
de70: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
de80: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
de90: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
dea0: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
deb0: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
dec0: 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  th */.  sqlite3_
ded0: 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20  vfs *pNext;     
dee0: 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65   /* Next registe
def0: 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e  red VFS */.  con
df00: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20  st char *zName; 
df10: 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
df20: 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69   this virtual fi
df30: 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76  le system */.  v
df40: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
df50: 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74          /* Point
df60: 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
df70: 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20  n-specific data 
df80: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  */.  int (*xOpen
df90: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
dfa0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
dfb0: 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e, sqlite3_file*
dfc0: 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
dfd0: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
dfe0: 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69  *pOutFlags);.  i
dff0: 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71  nt (*xDelete)(sq
e000: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e010: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
e020: 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69  nt syncDir);.  i
e030: 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71  nt (*xAccess)(sq
e040: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e050: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
e060: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
e070: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
e080: 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28  *xFullPathname)(
e090: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
e0a0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
e0b0: 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20   int nOut, char 
e0c0: 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
e0d0: 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74  (*xDlOpen)(sqlit
e0e0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
e0f0: 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b  har *zFilename);
e100: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72  .  void (*xDlErr
e110: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
e120: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
e130: 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76  r *zErrMsg);.  v
e140: 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28  oid (*(*xDlSym)(
e150: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
e160: 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
e170: 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b  zSymbol))(void);
e180: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
e190: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
e1a0: 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
e1b0: 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
e1c0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
e1d0: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
e1e0: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
e1f0: 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
e200: 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
e210: 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
e220: 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
e230: 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
e240: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74  *);.  int (*xGet
e250: 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74  LastError)(sqlit
e260: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68  e3_vfs*, int, ch
e270: 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  ar *);.  /*.  **
e280: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
e290: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
e2a0: 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74  n 1 of the sqlit
e2b0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a  e_vfs object.  *
e2c0: 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  * definition.  T
e2d0: 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77  hose that follow
e2e0: 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65   are added in ve
e2f0: 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72  rsion 2 or later
e300: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43  .  */.  int (*xC
e310: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29  urrentTimeInt64)
e320: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73  (sqlite3_vfs*, s
e330: 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a  qlite3_int64*);.
e340: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
e350: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
e360: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e  in versions 1 an
e370: 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74  d 2 of the sqlit
e380: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
e390: 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61  ** Those below a
e3a0: 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  re for version 3
e3b0: 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20   and greater..  
e3c0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53  */.  int (*xSetS
e3d0: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
e3e0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
e3f0: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
e400: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
e410: 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63  ;.  sqlite3_sysc
e420: 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79  all_ptr (*xGetSy
e430: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
e440: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e450: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f  ar *zName);.  co
e460: 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78  nst char *(*xNex
e470: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
e480: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
e490: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
e4a0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
e4b0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
e4c0: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72  n versions 1 thr
e4d0: 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71  ough 3 of the sq
e4e0: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
e4f0: 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73  .  ** New fields
e500: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
e510: 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69   in figure versi
e520: 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69  ons.  The iVersi
e530: 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69  on.  ** value wi
e540: 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65  ll increment whe
e550: 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65  never this happe
e560: 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ns. .  */.};../*
e570: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
e580: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
e590: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ess VFS method.*
e5a0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
e5b0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
e5c0: 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
e5d0: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
e5e0: 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
e5f0: 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
e600: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
e610: 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72  ect.  They deter
e620: 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e  mine.** what kin
e630: 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73  d of permissions
e640: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
e650: 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66  hod is looking f
e660: 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  or..** With SQLI
e670: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
e680: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
e690: 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63  thod.** simply c
e6a0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
e6b0: 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a  e file exists..*
e6c0: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
e6d0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20  CESS_READWRITE, 
e6e0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
e6f0: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
e700: 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64  ther the named d
e710: 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68  irectory is both
e720: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
e730: 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74  itable.** (in ot
e740: 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69  her words, if fi
e750: 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64  les can be added
e760: 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72  , removed, and r
e770: 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a  enamed within.**
e780: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e   the directory).
e790: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41  .** The SQLITE_A
e7a0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
e7b0: 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72  constant is curr
e7c0: 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20  ently used only 
e7d0: 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f  by the.** [temp_
e7e0: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
e7f0: 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20  pragma], though 
e800: 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67  this could chang
e810: 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a  e in a future.**
e820: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
e830: 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  te..** With SQLI
e840: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20  TE_ACCESS_READ, 
e850: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
e860: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
e870: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73  ther the file is
e880: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
e890: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
e8a0: 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a  AD constant is.*
e8b0: 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73  * currently unus
e8c0: 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69  ed, though it mi
e8d0: 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61  ght be used in a
e8e0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
e8f0: 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f  of.** SQLite..*/
e900: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e910: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
e920: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
e930: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
e940: 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62  TE 1   /* Used b
e950: 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74  y PRAGMA temp_st
e960: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f  ore_directory */
e970: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e980: 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
e990: 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a   2   /* Unused *
e9a0: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
e9b0: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
e9c0: 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65   xShmLock VFS me
e9d0: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
e9e0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
e9f0: 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61  ts define the va
ea00: 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70  rious locking op
ea10: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f  erations.** allo
ea20: 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c  wed by the xShmL
ea30: 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73  ock method of [s
ea40: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
ea50: 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c  s].  The.** foll
ea60: 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e  owing are the on
ea70: 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61  ly legal combina
ea80: 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74  tions of flags t
ea90: 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63  o the.** xShmLoc
eaa0: 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  k method:.**.** 
eab0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  <ul>.** <li>  SQ
eac0: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
ead0: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
eae0: 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
eaf0: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
eb00: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
eb10: 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  E.** <li>  SQLIT
eb20: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
eb30: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
eb40: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
eb50: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
eb60: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
eb70: 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VE.** </ul>.**.*
eb80: 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67  * When unlocking
eb90: 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45  , the same SHARE
eba0: 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66  D or EXCLUSIVE f
ebb0: 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70  lag must be supp
ebc0: 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67  lied as.** was g
ebd0: 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72  iven on the corr
ebe0: 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20  esponding lock. 
ebf0: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d   .**.** The xShm
ec00: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20  Lock method can 
ec10: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
ec20: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
ec30: 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74  SHARED or.** bet
ec40: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
ec50: 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74  d EXCLUSIVE.  It
ec60: 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69   cannot transiti
ec70: 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45  on between SHARE
ec80: 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49  D.** and EXCLUSI
ec90: 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  VE..*/.#define S
eca0: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
ecb0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
ecc0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
ecd0: 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
ece0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48  ne SQLITE_SHM_SH
ecf0: 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65  ARED       4.#de
ed00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
ed10: 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a  EXCLUSIVE    8..
ed20: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
ed30: 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b  Maximum xShmLock
ed40: 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65   index.**.** The
ed50: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
ed60: 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   on [sqlite3_io_
ed70: 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65  methods] may use
ed80: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
ed90: 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70  en 0 and this up
eda0: 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73  per bound as its
edb0: 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65   "offset" argume
edc0: 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  nt..** The SQLit
edd0: 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65  e core will neve
ede0: 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71  r attempt to acq
edf0: 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20  uire or release 
ee00: 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64  a.** lock outsid
ee10: 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a  e of this range.
ee20: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ee30: 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20  E_SHM_NLOCK     
ee40: 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     8.../*.** CAP
ee50: 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a  I3REF: Initializ
ee60: 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  e The SQLite Lib
ee70: 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rary.**.** ^The 
ee80: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ee90: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69  ze() routine ini
eea0: 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20  tializes the.** 
eeb0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
eec0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68   ^The sqlite3_sh
eed0: 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65  utdown() routine
eee0: 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  .** deallocates 
eef0: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68  any resources th
ef00: 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65  at were allocate
ef10: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  d by sqlite3_ini
ef20: 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68  tialize()..** Th
ef30: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
ef40: 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64   designed to aid
ef50: 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74   in process init
ef60: 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a  ialization and.*
ef70: 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d  * shutdown on em
ef80: 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20  bedded systems. 
ef90: 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70   Workstation app
efa0: 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a  lications using.
efb0: 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c  ** SQLite normal
efc0: 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ly do not need t
efd0: 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  o invoke either 
efe0: 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
eff0: 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  s..**.** A call 
f000: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
f010: 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65  alize() is an "e
f020: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
f030: 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66  f it is.** the f
f040: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
f050: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f060: 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67  s invoked during
f070: 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66   the lifetime of
f080: 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c  .** the process,
f090: 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65   or if it is the
f0a0: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
f0b0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f0c0: 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66   is invoked.** f
f0d0: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20  ollowing a call 
f0e0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
f0f0: 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61  own().  ^(Only a
f100: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
f110: 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69  .** of sqlite3_i
f120: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73  nitialize() does
f130: 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74   any initializat
f140: 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ion.  All other 
f150: 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72  calls.** are har
f160: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
f170: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
f180: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f190: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
f1a0: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
f1b0: 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
f1c0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
f1d0: 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65  shutdown() since
f1e0: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
f1f0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20  3_initialize(). 
f200: 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66   ^(Only.** an ef
f210: 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20  fective call to 
f220: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f230: 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e  () does any dein
f240: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  itialization..**
f250: 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64   All other valid
f260: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
f270: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65  3_shutdown() are
f280: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
f290: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  .)^.**.** The sq
f2a0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f2b0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
f2c0: 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20  threadsafe, but 
f2d0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f2e0: 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54  ().** is not.  T
f2f0: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
f300: 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  own() interface 
f310: 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c  must only be cal
f320: 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69  led from a.** si
f330: 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c  ngle thread.  Al
f340: 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  l open [database
f350: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75   connections] mu
f360: 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64  st be closed and
f370: 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51   all.** other SQ
f380: 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d  Lite resources m
f390: 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  ust be deallocat
f3a0: 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f  ed prior to invo
f3b0: 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  king.** sqlite3_
f3c0: 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a  shutdown()..**.*
f3d0: 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68  * Among other th
f3e0: 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69  ings, ^sqlite3_i
f3f0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c  nitialize() will
f400: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
f410: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53  e3_os_init().  S
f420: 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74  imilarly, ^sqlit
f430: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
f440: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c   will invoke sql
f450: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a  ite3_os_end()..*
f460: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
f470: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
f480: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
f490: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
f4a0: 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f  ccess..** ^If fo
f4b0: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73  r some reason, s
f4c0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f4d0: 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  e() is unable to
f4e0: 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74   initialize.** t
f4f0: 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68  he library (perh
f500: 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65  aps it is unable
f510: 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e   to allocate a n
f520: 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73  eeded resource s
f530: 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65  uch.** as a mute
f540: 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e  x) it returns an
f550: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74   [error code] ot
f560: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
f570: 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _OK]..**.** ^The
f580: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f590: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
f5a0: 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
f5b0: 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
f5c0: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
f5d0: 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
f5e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
f5f0: 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
f600: 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
f610: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f620: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
f630: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
f640: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
f650: 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
f660: 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
f670: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
f680: 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
f690: 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
f6a0: 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
f6b0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
f6c0: 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
f6d0: 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
f6e0: 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
f6f0: 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51   ^However, if SQ
f700: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
f710: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
f720: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
f730: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
f740: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68   option, then th
f750: 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c  e automatic call
f760: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  s to sqlite3_ini
f770: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65  tialize().** are
f780: 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65   omitted and the
f790: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
f7a0: 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69  t call sqlite3_i
f7b0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
f7c0: 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ctly.** prior to
f7d0: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
f7e0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
f7f0: 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20  e.  For maximum 
f800: 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20  portability,.** 
f810: 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
f820: 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
f830: 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b  ons always invok
f840: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
f850: 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74  lize().** direct
f860: 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ly prior to usin
f870: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
f880: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
f890: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a  uture releases.*
f8a0: 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  * of SQLite may 
f8b0: 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49  require this.  I
f8c0: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
f8d0: 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69  he behavior exhi
f8e0: 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51  bited.** when SQ
f8f0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
f900: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d   with [SQLITE_OM
f910: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67  IT_AUTOINIT] mig
f920: 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a  ht become the.**
f930: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
f940: 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  r in some future
f950: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
f960: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te..**.** The sq
f970: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
f980: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65  routine does ope
f990: 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
f9a0: 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61  ecific.** initia
f9b0: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  lization of the 
f9c0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
f9d0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
f9e0: 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  end().** routine
f9f0: 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
fa00: 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  ct of sqlite3_os
fa10: 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61  _init().  Typica
fa20: 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f  l tasks.** perfo
fa30: 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f  rmed by these ro
fa40: 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61  utines include a
fa50: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61  llocation or dea
fa60: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
fa70: 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73  static resources
fa80: 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  , initialization
fa90: 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61   of global varia
faa0: 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67  bles,.** setting
fab0: 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73   up a default [s
fac0: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75  qlite3_vfs] modu
fad0: 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75  le, or setting u
fae0: 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63  p.** a default c
faf0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69  onfiguration usi
fb00: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ng [sqlite3_conf
fb10: 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ig()]..**.** The
fb20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
fb30: 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  uld never invoke
fb40: 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
fb50: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20  os_init().** or 
fb60: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
fb70: 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20   directly.  The 
fb80: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
fb90: 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a  ld only invoke.*
fba0: 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
fbb0: 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lize() and sqlit
fbc0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
fbd0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
fbe0: 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  nit().** interfa
fbf0: 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74  ce is called aut
fc00: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
fc10: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fc20: 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  () and.** sqlite
fc30: 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
fc40: 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
fc50: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
fc60: 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
fc70: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
fc80: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
fc90: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
fca0: 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
fcb0: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
fcc0: 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
fcd0: 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69  led for Unix, Wi
fce0: 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a  ndows, or OS/2..
fcf0: 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20  ** When [custom 
fd00: 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66  builds | built f
fd10: 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72  or other platfor
fd20: 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68  ms].** (using th
fd30: 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48  e [SQLITE_OS_OTH
fd40: 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ER=1] compile-ti
fd50: 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
fd60: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
fd70: 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
fd80: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
fd90: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
fda0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
fdb0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
fdc0: 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
fdd0: 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
fde0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
fdf0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
fe00: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
fe10: 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
fe20: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
fe30: 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
fe40: 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72   some other [err
fe50: 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a  or code] upon.**
fe60: 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74   failure..*/.int
fe70: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fe80: 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ize(void);.int s
fe90: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fea0: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
feb0: 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
fec0: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
fed0: 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
fee0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
fef0: 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
ff00: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
ff10: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
ff20: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
ff30: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
ff40: 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
ff50: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
ff60: 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
ff70: 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
ff80: 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
ff90: 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
ffa0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
ffb0: 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
ffc0: 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
ffd0: 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
ffe0: 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
fff0: 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
10000 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
10010 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
10020 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
10030 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
10040 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
10050 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
10060 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  eds..**.** The s
10070 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10080 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
10090 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
100a0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
100b0 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
100c0 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
100d0 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
100e0 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
100f0 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
10100 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
10110 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  g() is running. 
10120 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71   Furthermore, sq
10130 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a  lite3_config().*
10140 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
10150 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
10160 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
10170 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
10180 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10190 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
101a0 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
101b0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
101c0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
101d0 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c  config() is call
101e0 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
101f0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
10200 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73  and before.** [s
10210 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10220 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20  )] then it will 
10230 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49  return SQLITE_MI
10240 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68  SUSE..** Note, h
10250 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71  owever, that ^sq
10260 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
10270 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
10280 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
10290 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
102a0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
102b0 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
102c0 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
102d0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
102e0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
102f0 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
10300 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66  integer.** [conf
10310 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10320 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
10330 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
10340 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
10350 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
10360 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
10370 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
10380 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
10390 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
103a0 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
103b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
103c0 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ..**.** ^When a 
103d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
103e0 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
103f0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
10400 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
10410 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70  ]..** ^If the op
10420 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
10430 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
10440 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
10450 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68  ption.** then th
10460 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
10470 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  ns a non-zero [e
10480 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69  rror code]..*/.i
10490 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  nt sqlite3_confi
104a0 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  g(int, ...);../*
104b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
104c0 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65  nfigure database
104d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a   connections.**.
104e0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
104f0 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
10500 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
10510 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
10520 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
10530 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
10540 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
10550 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
10560 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
10570 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
10580 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
10590 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
105a0 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
105b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
105c0 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
105d0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
105e0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  )..**.** The sec
105f0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
10600 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
10610 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
10620 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42  he.** [SQLITE_DB
10630 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
10640 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
10650 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65   verb] - an inte
10660 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61  ger code .** tha
10670 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
10680 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
10690 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
106a0 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
106b0 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62  nfigured..** Sub
106c0 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
106d0 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  s vary depending
106e0 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72   on the configur
106f0 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a  ation verb..**.*
10700 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
10710 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
10720 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
10730 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
10740 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
10750 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
10760 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sful..*/.int sql
10770 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
10780 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
10790 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
107a0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
107b0 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
107c0 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
107d0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
107e0 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
107f0 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
10800 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
10810 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
10820 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
10830 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
10840 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
10850 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
10860 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
10870 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
10880 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
10890 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
108a0 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
108b0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
108c0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
108d0 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
108e0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
108f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
10900 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
10910 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
10920 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
10930 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
10940 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
10950 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
10960 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
10970 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
10980 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
10990 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
109a0 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
109b0 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
109c0 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
109d0 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
109e0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
109f0 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
10a00 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
10a10 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
10a20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
10a30 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
10a40 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
10a50 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
10a60 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
10a70 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
10a80 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
10a90 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
10aa0 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
10ab0 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
10ac0 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
10ad0 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
10ae0 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
10af0 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
10b00 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
10b10 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
10b20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10b30 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
10b40 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
10b50 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
10b60 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
10b70 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
10b80 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
10b90 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
10ba0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
10bb0 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
10bc0 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
10bd0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
10be0 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
10bf0 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
10c00 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
10c10 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
10c20 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
10c30 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52   The xMalloc, xR
10c40 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65  ealloc, and xFre
10c50 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  e methods must w
10c60 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
10c70 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
10c80 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
10c90 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
10ca0 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
10cb0 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  rary..** ^SQLite
10cc0 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
10cd0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
10ce0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
10cf0 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
10d00 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
10d10 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
10d20 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a  o xRoundup..**.*
10d30 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
10d40 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
10d50 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
10d60 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
10d70 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
10d80 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
10d90 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
10da0 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
10db0 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
10dc0 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
10dd0 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
10de0 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
10df0 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
10e00 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
10e10 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
10e20 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
10e30 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
10e40 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
10e50 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
10e60 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
10e70 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
10e80 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
10e90 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
10ea0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10eb0 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
10ec0 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
10ed0 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
10ee0 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
10ef0 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
10f00 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
10f10 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45  power of 2..** E
10f20 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
10f30 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63  cation request c
10f40 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68  oming in through
10f50 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
10f60 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
10f70 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69  e3_realloc()] fi
10f80 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64  rst calls xRound
10f90 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70  up.  If xRoundup
10fa0 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20   returns 0, .** 
10fb0 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20  that causes the 
10fc0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65  corresponding me
10fd0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10fe0 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54  to fail..**.** T
10ff0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
11000 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
11010 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11020 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  .  For example,.
11030 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
11040 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
11050 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
11060 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
11070 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
11080 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
11090 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
110a0 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
110b0 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
110c0 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
110d0 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
110e0 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
110f0 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
11100 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
11110 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
11120 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
11130 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
11140 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
11150 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
11160 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
11170 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
11180 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
11190 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
111a0 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
111b0 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
111c0 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
111d0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
111e0 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
111f0 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
11200 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
11210 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11220 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
11230 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
11240 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
11250 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
11260 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
11270 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
11280 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
11290 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
112a0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
112b0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
112c0 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
112d0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
112e0 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
112f0 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
11300 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
11310 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
11320 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
11330 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
11340 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
11350 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
11360 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
11370 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
11380 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
11390 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
113a0 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
113b0 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
113c0 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
113d0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
113e0 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
113f0 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
11400 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
11410 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
11420 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
11430 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
11440 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
11450 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11460 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
11470 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
11480 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11490 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
114a0 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
114b0 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
114c0 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
114d0 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
114e0 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
114f0 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
11500 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
11510 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
11520 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
11530 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
11540 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
11550 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
11560 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
11570 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
11580 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
11590 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
115a0 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
115b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
115c0 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
115d0 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
115e0 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
115f0 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
11600 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
11610 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
11620 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
11630 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
11640 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
11650 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
11660 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
11670 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
11680 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
11690 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
116a0 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
116b0 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
116c0 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
116d0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
116e0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
116f0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
11700 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11710 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
11720 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
11730 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
11740 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
11750 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
11760 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
11770 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
11780 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
11790 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
117a0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
117b0 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
117c0 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
117d0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
117e0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
117f0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
11800 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11810 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
11820 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
11830 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
11840 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
11850 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
11860 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11870 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
11880 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
11890 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
118a0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
118b0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
118c0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
118d0 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
118e0 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
118f0 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
11900 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
11910 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
11920 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
11930 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
11940 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
11950 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
11960 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
11970 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
11980 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
11990 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
119a0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
119b0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
119c0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
119d0 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
119e0 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
119f0 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
11a00 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
11a10 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
11a20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
11a30 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
11a40 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
11a50 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
11a60 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
11a70 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
11a80 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
11a90 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
11aa0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
11ab0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
11ac0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
11ad0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
11ae0 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
11af0 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
11b00 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
11b10 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
11b20 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
11b30 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
11b40 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
11b50 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
11b60 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
11b70 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
11b80 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
11b90 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11ba0 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
11bb0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11bc0 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
11bd0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11be0 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
11bf0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
11c00 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
11c10 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
11c20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
11c30 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
11c40 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
11c50 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
11c60 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
11c70 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
11c80 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
11c90 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
11ca0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
11cb0 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
11cc0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
11cd0 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
11ce0 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
11cf0 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
11d00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11d10 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
11d20 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
11d30 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
11d40 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
11d50 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
11d60 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
11d70 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
11d80 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
11d90 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
11da0 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
11db0 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
11dc0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
11dd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11de0 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
11df0 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
11e00 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
11e10 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
11e20 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
11e30 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
11e40 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
11e50 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
11e60 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
11e70 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
11e80 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
11e90 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
11ea0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
11eb0 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
11ec0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
11ed0 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
11ee0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
11ef0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
11f00 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11f10 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
11f20 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
11f30 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
11f40 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11f50 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
11f60 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
11f70 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
11f80 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
11f90 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
11fa0 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
11fb0 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
11fc0 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
11fd0 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
11fe0 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
11ff0 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
12000 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
12010 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
12020 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12030 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
12040 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
12050 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
12060 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
12070 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
12080 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
12090 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
120a0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
120b0 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
120c0 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
120d0 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
120e0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
120f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12100 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
12110 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
12120 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
12130 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
12140 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
12150 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12160 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
12170 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
12180 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
12190 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
121a0 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
121b0 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
121c0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
121d0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
121e0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
121f0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
12200 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
12210 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
12220 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
12230 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
12240 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
12250 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
12260 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12270 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
12280 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
12290 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
122a0 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
122b0 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
122c0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
122d0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
122e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
122f0 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
12300 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
12310 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
12320 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
12330 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
12340 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
12350 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
12360 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
12370 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
12380 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
12390 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
123a0 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  e..** The argume
123b0 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
123c0 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
123d0 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
123e0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
123f0 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
12400 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
12410 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12420 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
12430 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
12440 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
12450 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
12460 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
12470 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
12480 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
12490 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
124a0 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
124b0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
124c0 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
124d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
124e0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d  NFIG_GETMALLOC]]
124f0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12500 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
12510 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
12520 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12530 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74  TMALLOC option t
12540 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
12550 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
12560 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
12570 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
12580 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
12590 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
125a0 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  re..** The [sqli
125b0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
125c0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
125d0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
125e0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
125f0 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
12600 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
12610 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
12620 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
12630 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
12640 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
12650 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
12660 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
12670 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
12680 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
12690 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
126a0 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
126b0 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
126c0 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
126d0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
126e0 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
126f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
12700 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
12710 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
12720 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
12730 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  S option takes s
12740 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
12750 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69  f type int,.** i
12760 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
12770 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
12780 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
12790 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
127a0 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  n of.** memory a
127b0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
127c0 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
127d0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
127e0 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a  tatistics are.**
127f0 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66   disabled, the f
12800 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20  ollowing SQLite 
12810 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d  interfaces becom
12820 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61  e non-operationa
12830 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20  l:.**   <ul>.** 
12840 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
12850 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a  memory_used()].*
12860 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
12870 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
12880 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  er()].**   <li> 
12890 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
128a0 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a  ap_limit64()].**
128b0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
128c0 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20  _status64()].** 
128d0 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
128e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
128f0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
12900 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
12910 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
12920 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
12930 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
12940 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
12950 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
12960 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
12970 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
12980 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
12990 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
129a0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
129b0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d  CONFIG_SCRATCH]]
129c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
129d0 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
129e0 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
129f0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
12a00 43 48 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  CH option specif
12a10 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
12a20 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  ory buffer.** th
12a30 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
12a40 65 20 66 6f 72 20 73 63 72 61 74 63 68 20 6d 65  e for scratch me
12a50 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72 65 20 61  mory.  ^(There a
12a60 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
12a70 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f  ts.** to SQLITE_
12a80 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3a 20  CONFIG_SCRATCH: 
12a90 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
12aa0 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
12ab0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
12ac0 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
12ad0 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
12ae0 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77   will be.** draw
12af0 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  n, the size of e
12b00 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  ach scratch allo
12b10 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20  cation (sz),.** 
12b20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
12b30 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63  number of scratc
12b40 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e  h allocations (N
12b50 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73  ).)^.** The firs
12b60 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
12b70 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
12b80 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  an 8-byte aligne
12b90 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61  d buffer.** of a
12ba0 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
12bb0 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
12bc0 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f   ^SQLite will no
12bd0 74 20 75 73 65 20 6d 6f 72 65 20 74 68 61 6e 20  t use more than 
12be0 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66  one scratch buff
12bf0 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 0a  ers per thread..
12c00 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
12c10 6e 65 76 65 72 20 72 65 71 75 65 73 74 20 61 20  never request a 
12c20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74  scratch buffer t
12c30 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e  hat is more than
12c40 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20   6.** times the 
12c50 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
12c60 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  ze..** ^If SQLit
12c70 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64  e needs needs ad
12c80 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61  ditional.** scra
12c90 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  tch memory beyon
12ca0 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
12cb0 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69  ed by this confi
12cc0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c  guration option,
12cd0 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   then .** [sqlit
12ce0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c  e3_malloc()] wil
12cf0 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  l be used to obt
12d00 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e  ain the memory n
12d10 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68  eeded.<p>.** ^Wh
12d20 65 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  en the applicati
12d30 6f 6e 20 70 72 6f 76 69 64 65 73 20 61 6e 79 20  on provides any 
12d40 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72 61 74 63  amount of scratc
12d50 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a  h memory using.*
12d60 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
12d70 53 43 52 41 54 43 48 2c 20 53 51 4c 69 74 65 20  SCRATCH, SQLite 
12d80 61 76 6f 69 64 73 20 75 6e 6e 65 63 65 73 73 61  avoids unnecessa
12d90 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c  ry large.** [sql
12da0 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70  ite3_malloc|heap
12db0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a   allocations]..*
12dc0 2a 20 54 68 69 73 20 63 61 6e 20 68 65 6c 70 20  * This can help 
12dd0 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72  [Robson proof|pr
12de0 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  event memory all
12df0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 73  ocation failures
12e00 5d 20 64 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a  ] due to heap.**
12e10 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69   fragmentation i
12e20 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62  n low-memory emb
12e30 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a  edded systems..*
12e40 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
12e50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
12e60 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51  GECACHE]] <dt>SQ
12e70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
12e80 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
12e90 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
12ea0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
12eb0 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
12ec0 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
12ed0 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
12ee0 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
12ef0 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
12f00 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20  page cache with 
12f10 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65  the default page
12f20 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
12f30 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54  entation.  .** T
12f40 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
12f50 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  n should not be 
12f60 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69  used if an appli
12f70 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61  cation-define pa
12f80 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
12f90 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f  ementation is lo
12fa0 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  aded using the [
12fb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
12fc0 41 43 48 45 32 5d 0a 2a 2a 20 63 6f 6e 66 69 67  ACHE2].** config
12fd0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 0a  uration option..
12fe0 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68  ** ^There are th
12ff0 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
13000 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
13010 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69 6e  AGECACHE: A poin
13020 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65  ter to.** 8-byte
13030 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f   aligned.** memo
13040 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ry, the size of 
13050 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72  each page buffer
13060 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
13070 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28  umber of pages (
13080 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
13090 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
130a0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
130b0 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73   largest databas
130c0 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77  e page.** (a pow
130d0 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
130e0 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33 36 29  n 512 and 65536)
130f0 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61   plus some extra
13100 20 62 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a   bytes for each.
13110 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20  ** page header. 
13120 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
13130 65 78 74 72 61 20 62 79 74 65 73 20 6e 65 65 64  extra bytes need
13140 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 68  ed by the page h
13150 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20  eader.** can be 
13160 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
13170 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
13180 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
13190 5d 20 6f 70 74 69 6f 6e 20 0a 2a 2a 20 74 6f 20  ] option .** to 
131a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
131b0 29 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61  )]..** ^It is ha
131c0 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72  rmless, apart fr
131d0 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65  om the wasted me
131e0 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65  mory,.** for the
131f0 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f   sz parameter to
13200 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
13210 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65 20  necessary.  The 
13220 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
13230 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 65 72  t should pointer
13240 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c   to an 8-byte al
13250 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d  igned block of m
13260 65 6d 6f 72 79 20 74 68 61 74 0a 2a 2a 20 69 73  emory that.** is
13270 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
13280 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  ytes of memory, 
13290 6f 74 68 65 72 77 69 73 65 20 73 75 62 73 65 71  otherwise subseq
132a0 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73  uent behavior is
132b0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
132c0 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
132d0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
132e0 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69  ovided by the fi
132f0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
13300 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d  satisfy its.** m
13310 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20  emory needs for 
13320 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65  the first N page
13330 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74  s that it adds t
13340 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64  o cache.  ^If ad
13350 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
13360 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
13370 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
13380 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
13390 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20  by this option, 
133a0 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67  then.** SQLite g
133b0 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
133c0 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68  malloc()] for th
133d0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f  e additional sto
133e0 72 61 67 65 20 73 70 61 63 65 2e 3c 2f 64 64 3e  rage space.</dd>
133f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13400 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64  CONFIG_HEAP]] <d
13410 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13420 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  HEAP</dt>.** <dd
13430 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
13440 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e  NFIG_HEAP option
13450 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
13460 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
13470 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74  r .** that SQLit
13480 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61  e will use for a
13490 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
134a0 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  c memory allocat
134b0 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79  ion needs.** bey
134c0 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64  ond those provid
134d0 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54  ed for by [SQLIT
134e0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
134f0 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  ] and.** [SQLITE
13500 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
13510 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49  E]..** ^The SQLI
13520 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f  TE_CONFIG_HEAP o
13530 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
13540 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74  ailable if SQLit
13550 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  e is compiled.**
13560 20 77 69 74 68 20 65 69 74 68 65 72 20 5b 53 51   with either [SQ
13570 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
13580 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  YS3] or [SQLITE_
13590 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20  ENABLE_MEMSYS5] 
135a0 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  and returns.** [
135b0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
135c0 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69   invoked otherwi
135d0 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72  se..** ^There ar
135e0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
135f0 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  s to SQLITE_CONF
13600 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38  IG_HEAP:.** An 8
13610 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f  -byte aligned po
13620 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
13630 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  ory,.** the numb
13640 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
13650 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
13660 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
13670 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
13680 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  e..** ^If the fi
13690 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
136a0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
136b0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
136c0 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
136d0 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
136e0 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
136f0 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
13700 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
13710 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
13720 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
13730 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
13740 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
13750 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65  ALLOC].  ^If the
13760 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  .** memory point
13770 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  er is not NULL t
13780 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
13790 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
137a0 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
137b0 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
137c0 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
137d0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
137e0 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  eds..** The firs
137f0 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
13800 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d  emory pointer) m
13810 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
13820 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62  o an 8-byte.** b
13830 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
13840 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
13850 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  f SQLite will be
13860 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
13870 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
13880 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61  ation size is ca
13890 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52  pped at 2**12. R
138a0 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73  easonable values
138b0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69  .** for the mini
138c0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
138d0 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72  ize are 2**5 thr
138e0 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a  ough 2**8.</dd>.
138f0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13900 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64  ONFIG_MUTEX]] <d
13910 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13920 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
13930 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
13940 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74  CONFIG_MUTEX opt
13950 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
13960 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
13970 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  h is a.** pointe
13980 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
13990 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
139a0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
139b0 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
139c0 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
139d0 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65  fies alternative
139e0 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
139f0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
13a00 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65  used.** in place
13a10 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
13a20 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
13a30 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74  QLite.)^  ^SQLit
13a40 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
13a50 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
13a60 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
13a70 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
13a80 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65  structure before
13a90 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
13aa0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13ab0 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20  )] returns. ^If 
13ac0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
13ad0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
13ae0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13af0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
13b00 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
13b10 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
13b20 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
13b30 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
13b40 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
13b50 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
13b60 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
13b70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
13b80 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
13b90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
13ba0 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
13bb0 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
13bc0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
13bd0 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
13be0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13bf0 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74  G_GETMUTEX]] <dt
13c00 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
13c10 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
13c20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
13c30 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
13c40 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  X option takes a
13c50 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
13c60 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
13c70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
13c80 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
13c90 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
13ca0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
13cb0 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
13cc0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a  _mutex_methods].
13cd0 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
13ce0 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
13cf0 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
13d00 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  d mutex routines
13d10 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
13d20 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
13d30 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
13d40 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c  efault mutex all
13d50 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
13d60 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
13d70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b  er used to track
13d80 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72   mutex usage for
13d90 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20   performance.** 
13da0 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73  profiling or tes
13db0 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c  ting, for exampl
13dc0 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  e.   ^If SQLite 
13dd0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13de0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
13df0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
13e00 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
13e10 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
13e20 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
13e30 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
13e40 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
13e50 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
13e60 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
13e70 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
13e80 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
13e90 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
13ea0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63  ONFIG_GETMUTEX c
13eb0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13ec0 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
13ed0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
13ee0 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
13ef0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
13f00 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51  OKASIDE]] <dt>SQ
13f10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
13f20 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
13f30 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
13f40 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
13f50 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
13f60 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
13f70 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68   determine.** th
13f80 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f  e default size o
13f90 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  f lookaside memo
13fa0 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61  ry on each [data
13fb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
13fc0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
13fd0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
13fe0 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
13ff0 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
14000 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
14010 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
14020 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
14030 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
14040 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14050 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45  ion.)^  ^(SQLITE
14060 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
14070 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69  E.** sets the <i
14080 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
14090 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
140a0 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
140b0 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
140c0 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74  option to [sqlit
140d0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
140e0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
140f0 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
14100 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
14110 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
14120 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
14130 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
14140 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14150 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
14160 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
14170 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
14180 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
14190 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f  IG_PCACHE2 optio
141a0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
141b0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
141c0 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  is .** a pointer
141d0 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   to an [sqlite3_
141e0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
141f0 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
14200 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 0a  bject specifies.
14210 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ** the interface
14220 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67   to a custom pag
14230 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
14240 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51  tation.)^.** ^SQ
14250 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
14260 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
14270 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
14280 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a  2] object.</dd>.
14290 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
142a0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
142b0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
142c0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c  NFIG_GETPCACHE2<
142d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
142e0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
142f0 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70 74 69  _GETPCACHE2 opti
14300 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
14310 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
14320 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
14330 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   to an [sqlite3_
14340 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
14350 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65   object.  SQLite
14360 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68   copies of.** th
14370 65 20 63 75 72 72 65 6e 74 20 70 61 67 65 20 63  e current page c
14380 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
14390 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62  ion into that ob
143a0 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ject.)^ </dd>.**
143b0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
143c0 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51  FIG_LOG]] <dt>SQ
143d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
143e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  /dt>.** <dd> The
143f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
14400 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  OG option is use
14410 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74  d to configure t
14420 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f  he SQLite.** glo
14430 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e  bal [error log].
14440 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45  .** (^The SQLITE
14450 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
14460 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
14470 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65  uments: a pointe
14480 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69  r to a.** functi
14490 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73  on with a call s
144a0 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64  ignature of void
144b0 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  (*)(void*,int,co
144c0 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20  nst char*), .** 
144d0 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  and a pointer to
144e0 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66   void. ^If the f
144f0 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
14500 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20  is not NULL, it 
14510 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79  is.** invoked by
14520 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
14530 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68   to process each
14540 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20   logging event. 
14550 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63   ^If the.** func
14560 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
14570 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74  NULL, the [sqlit
14580 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66  e3_log()] interf
14590 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f  ace becomes a no
145a0 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69  -op..** ^The voi
145b0 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  d pointer that i
145c0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
145d0 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f  ument to SQLITE_
145e0 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a  CONFIG_LOG is.**
145f0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
14600 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
14610 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70  ameter to the ap
14620 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
14630 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
14640 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68  tion whenever th
14650 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  at function is i
14660 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65  nvoked.  ^The se
14670 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
14680 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20  o.** the logger 
14690 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f  function is a co
146a0 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  py of the first 
146b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
146c0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
146d0 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  * [sqlite3_log()
146e0 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e  ] call and is in
146f0 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b  tended to be a [
14700 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
14710 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  an.** [extended 
14720 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e  result code].  ^
14730 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
14740 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
14750 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c  e logger is.** l
14760 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72  og message after
14770 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20   formatting via 
14780 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
14790 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  f()]..** The SQL
147a0 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65  ite logging inte
147b0 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65  rface is not ree
147c0 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67  ntrant; the logg
147d0 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  er function.** s
147e0 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61  upplied by the a
147f0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
14800 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53  not invoke any S
14810 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
14820 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74  .** In a multi-t
14830 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
14840 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61  ion, the applica
14850 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
14860 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
14870 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
14880 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  fe. </dd>.**.** 
14890 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
148a0 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  URI]] <dt>SQLITE
148b0 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c  _CONFIG_URI.** <
148c0 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  dd>^(The SQLITE_
148d0 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f  CONFIG_URI optio
148e0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
148f0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
14900 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e  e int..** If non
14910 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20  -zero, then URI 
14920 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
14930 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66  ally enabled. If
14940 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
14950 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20  s zero,.** then 
14960 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
14970 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
14980 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e  d.)^ ^If URI han
14990 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
149a0 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c  y.** enabled, al
149b0 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73  l filenames pass
149c0 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ed to [sqlite3_o
149d0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
149e0 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20  _open_v2()],.** 
149f0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
14a00 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69  )] or.** specifi
14a10 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41  ed as part of [A
14a20 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20  TTACH] commands 
14a30 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
14a40 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c  as URIs, regardl
14a50 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65  ess.** of whethe
14a60 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51  r or not the [SQ
14a70 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
14a80 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
14a90 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
14aa0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
14ab0 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20  ened. ^If it is 
14ac0 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
14ad0 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  d, filenames are
14ae0 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72  .** only interpr
14af0 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20  eted as URIs if 
14b00 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
14b10 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20  URI flag is set 
14b20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61  when the.** data
14b30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
14b40 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20  is opened. ^(By 
14b50 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e  default, URI han
14b60 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
14b70 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54  y.** disabled. T
14b80 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
14b90 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20   may be changed 
14ba0 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74  by compiling wit
14bb0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
14bc0 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c  _USE_URI] symbol
14bd0 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a   defined.)^.**.*
14be0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14bf0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
14c00 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49  _SCAN]] <dt>SQLI
14c10 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
14c20 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a  NG_INDEX_SCAN.**
14c30 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
14c40 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
14c50 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69  _INDEX_SCAN opti
14c60 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
14c70 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67  e integer.** arg
14c80 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69  ument which is i
14c90 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
14ca0 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72  boolean in order
14cb0 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
14cc0 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65  sable.** the use
14cd0 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
14ce0 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61  ices for full ta
14cf0 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65  ble scans in the
14d00 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72   query optimizer
14d10 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
14d20 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74  t setting is det
14d30 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68  ermined.** by th
14d40 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f  e [SQLITE_ALLOW_
14d50 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
14d60 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  CAN] compile-tim
14d70 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20  e option, or is 
14d80 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20  "on".** if that 
14d90 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
14da0 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ion is omitted..
14db0 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74  ** The ability t
14dc0 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73  o disable the us
14dd0 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e  e of covering in
14de0 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74  dices for full t
14df0 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73  able scans.** is
14e00 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e   because some in
14e10 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20  correctly coded 
14e20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69  legacy applicati
14e30 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e  ons might malfun
14e40 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68  ction.** when th
14e50 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69  e optimization i
14e60 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76  s enabled.  Prov
14e70 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74  iding the abilit
14e80 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20  y to.** disable 
14e90 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
14ea0 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65   allows the olde
14eb0 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61  r, buggy applica
14ec0 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72  tion code to wor
14ed0 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61  k.** without cha
14ee0 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65  nge even with ne
14ef0 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
14f00 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  SQLite..**.** [[
14f10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14f20 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f  ACHE]] [[SQLITE_
14f30 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14f40 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
14f50 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61  _CONFIG_PCACHE a
14f60 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  nd SQLITE_CONFIG
14f70 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64  _GETPCACHE.** <d
14f80 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73  d> These options
14f90 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e   are obsolete an
14fa0 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  d should not be 
14fb0 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65  used by new code
14fc0 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65  ..** They are re
14fd0 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77  tained for backw
14fe0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
14ff0 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e  ty but are now n
15000 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  o-ops..** </dd>.
15010 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15020 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a  ONFIG_SQLLOG]].*
15030 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
15040 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64  FIG_SQLLOG.** <d
15050 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  d>This option is
15060 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
15070 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d  if sqlite is com
15080 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
15090 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
150a0 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f  _SQLLOG] pre-pro
150b0 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66  cessor macro def
150c0 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20  ined. The first 
150d0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a  argument should.
150e0 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ** be a pointer 
150f0 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
15100 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f   type void(*)(vo
15110 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e  id*,sqlite3*,con
15120 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a  st char*, int)..
15130 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68  ** The second sh
15140 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20  ould be of type 
15150 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c  (void*). The cal
15160 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
15170 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a   by the library.
15180 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61  ** in three sepa
15190 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63  rate circumstanc
151a0 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62  es, identified b
151b0 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73  y the value pass
151c0 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  ed as the.** fou
151d0 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49  rth parameter. I
151e0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
151f0 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65  ameter is 0, the
15200 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
15210 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73  onnection.** pas
15220 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
15230 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a  d argument has j
15240 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e  ust been opened.
15250 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
15260 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ent.** points to
15270 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69   a buffer contai
15280 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66  ning the name of
15290 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
152a0 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a  se file. If the.
152b0 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
152c0 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74  ter is 1, then t
152d0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
152e0 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20   that the third 
152f0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69  parameter.** poi
15300 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20  nts to has just 
15310 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f  been executed. O
15320 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68  r, if the fourth
15330 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c   parameter is 2,
15340 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e   then.** the con
15350 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61  nection being pa
15360 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
15370 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
15380 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68  being closed. Th
15390 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
153a0 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e  eter is passed N
153b0 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65  ULL In this case
153c0 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66  .  An example of
153d0 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63   using this.** c
153e0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
153f0 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20  ion can be seen 
15400 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c  in the "test_sql
15410 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69  log.c" source fi
15420 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e  le in.** the can
15430 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f  onical SQLite so
15440 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a  urce tree.</dd>.
15450 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15460 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d  ONFIG_MMAP_SIZE]
15470 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
15480 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
15490 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f  .** <dd>^SQLITE_
154a0 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
154b0 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69   takes two 64-bi
154c0 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74  t integer (sqlit
154d0 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73  e3_int64) values
154e0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65  .** that are the
154f0 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69   default mmap si
15500 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65  ze limit (the de
15510 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f  fault setting fo
15520 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61  r.** [PRAGMA mma
15530 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65  p_size]) and the
15540 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
15550 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
15560 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
15570 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65  t setting can be
15580 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65   overridden by e
15590 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
155a0 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  nection using.**
155b0 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41   either the [PRA
155c0 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63  GMA mmap_size] c
155d0 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73  ommand, or by us
155e0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ing the.** [SQLI
155f0 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
15600 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
15610 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d  .  ^(The maximum
15620 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
15630 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69  ze.** will be si
15640 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
15650 20 69 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f   if necessary so
15660 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f   that it does no
15670 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20  t exceed the.** 
15680 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78  compile-time max
15690 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73  imum mmap size s
156a0 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
156b0 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49  LITE_MAX_MMAP_SI
156c0 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ZE] compile-time
156d0 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49   option.)^.** ^I
156e0 66 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e  f either argumen
156f0 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  t to this option
15700 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
15710 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74  en that argument
15720 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74   is.** changed t
15730 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69  o its compile-ti
15740 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  me default..**.*
15750 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15760 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
15770 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
15780 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
15790 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54  APSIZE.** <dd>^T
157a0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
157b0 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
157c0 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
157d0 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69  vailable if SQLi
157e0 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
157f0 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69  d for Windows wi
15800 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57  th the [SQLITE_W
15810 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65  IN32_MALLOC] pre
15820 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
15830 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51  .** defined. ^SQ
15840 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
15850 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73  2_HEAPSIZE takes
15860 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e   a 32-bit unsign
15870 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  ed integer value
15880 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69 66 69  .** that specifi
15890 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73  es the maximum s
158a0 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65 61 74  ize of the creat
158b0 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b  ed heap..**.** [
158c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
158d0 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a  CACHE_HDRSZ]].**
158e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
158f0 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a  IG_PCACHE_HDRSZ.
15900 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
15910 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15920 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61  _HDRSZ option ta
15930 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72  kes a single par
15940 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ameter which.** 
15950 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
15960 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77  an integer and w
15970 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20  rites into that 
15980 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62  integer the numb
15990 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62  er of extra.** b
159a0 79 74 65 73 20 70 65 72 20 70 61 67 65 20 72 65  ytes per page re
159b0 71 75 69 72 65 64 20 66 6f 72 20 65 61 63 68 20  quired for each 
159c0 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f  page in [SQLITE_
159d0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
159e0 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74  ]..** The amount
159f0 20 6f 66 20 65 78 74 72 61 20 73 70 61 63 65 20   of extra space 
15a00 72 65 71 75 69 72 65 64 20 63 61 6e 20 63 68 61  required can cha
15a10 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  nge depending on
15a20 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a   the compiler,.*
15a30 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72  * target platfor
15a40 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65  m, and SQLite ve
15a50 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  rsion..**.** [[S
15a60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
15a70 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  SZ]].** <dt>SQLI
15a80 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a  TE_CONFIG_PMASZ.
15a90 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
15aa0 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20  TE_CONFIG_PMASZ 
15ab0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15ac0 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20  ingle parameter 
15ad0 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75  which.** is an u
15ae0 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
15af0 61 6e 64 20 73 65 74 73 20 74 68 65 20 22 4d 69  and sets the "Mi
15b00 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20  nimum PMA Size" 
15b10 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72  for the multithr
15b20 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20  eaded.** sorter 
15b30 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  to that integer.
15b40 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69    The default mi
15b50 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69  nimum PMA Size i
15b60 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20  s set by the.** 
15b70 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50  [SQLITE_SORTER_P
15b80 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  MASZ] compile-ti
15b90 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20  me option.  New 
15ba0 74 68 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e  threads are laun
15bb0 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20  ched.** to help 
15bc0 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74  with sort operat
15bd0 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74  ions when multit
15be0 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a  hreaded sorting.
15bf0 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75  ** is enabled (u
15c00 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  sing the [PRAGMA
15c10 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e   threads] comman
15c20 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e  d) and the amoun
15c30 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20  t of content.** 
15c40 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65 78 63  to be sorted exc
15c50 65 65 64 73 20 74 68 65 20 70 61 67 65 20 73 69  eeds the page si
15c60 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e  ze times the min
15c70 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  imum of the.** [
15c80 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a  PRAGMA cache_siz
15c90 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74  e] setting and t
15ca0 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 20 3c 2f  his value..** </
15cb0 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
15cc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
15cd0 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a  GLETHREAD  1  /*
15ce0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
15cf0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
15d00 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f  LTITHREAD   2  /
15d10 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
15d20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
15d30 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20  ERIALIZED    3  
15d40 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
15d50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15d60 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20  MALLOC        4 
15d70 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
15d80 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
15d90 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15da0 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20  G_GETMALLOC     
15db0 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  5  /* sqlite3_me
15dc0 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
15dd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15de0 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20  FIG_SCRATCH     
15df0 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    6  /* void*, i
15e00 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
15e10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15e20 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
15e30 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c      7  /* void*,
15e40 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
15e50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15e60 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20  _CONFIG_HEAP    
15e70 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64        8  /* void
15e80 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e  *, int nByte, in
15e90 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  t min */.#define
15ea0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
15eb0 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20  EMSTATUS     9  
15ec0 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64  /* boolean */.#d
15ed0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15ee0 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20  FIG_MUTEX       
15ef0 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   10  /* sqlite3_
15f00 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
15f10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15f20 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
15f30 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69       11  /* sqli
15f40 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
15f50 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75  s* */./* previou
15f60 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  sly SQLITE_CONFI
15f70 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20  G_CHUNKALLOC 12 
15f80 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75  which is now unu
15f90 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65  sed. */ .#define
15fa0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
15fb0 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20  OOKASIDE    13  
15fc0 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  /* int int */.#d
15fd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15fe0 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20  FIG_PCACHE      
15ff0 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f   14  /* no-op */
16000 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16010 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
16020 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70      15  /* no-op
16030 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16040 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20  TE_CONFIG_LOG   
16050 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46         16  /* xF
16060 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64  unc, void* */.#d
16070 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16080 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20  FIG_URI         
16090 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   17  /* int */.#
160a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
160b0 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 20  NFIG_PCACHE2    
160c0 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33    18  /* sqlite3
160d0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
160e0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
160f0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
16100 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73  ACHE2   19  /* s
16110 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
16120 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
16130 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16140 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
16150 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20  SCAN 20  /* int 
16160 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16170 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20  E_CONFIG_SQLLOG 
16180 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71        21  /* xSq
16190 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  llog, void* */.#
161a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
161b0 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  NFIG_MMAP_SIZE  
161c0 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33    22  /* sqlite3
161d0 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f  _int64, sqlite3_
161e0 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65  int64 */.#define
161f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
16200 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20 20  IN32_HEAPSIZE   
16210 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42     23  /* int nB
16220 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  yte */.#define S
16230 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16240 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20 20 20  CHE_HDRSZ       
16250 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a   24  /* int *psz
16260 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16270 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20  TE_CONFIG_PMASZ 
16280 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
16290 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e    /* unsigned in
162a0 74 20 73 7a 50 6d 61 20 2a 2f 0a 0a 2f 2a 0a 2a  t szPma */../*.*
162b0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
162c0 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
162d0 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
162e0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
162f0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
16300 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
16310 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
16320 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
16330 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
16340 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
16350 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
16360 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
16370 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
16380 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
16390 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
163a0 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
163b0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
163c0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
163d0 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
163e0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
163f0 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
16400 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
16410 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
16420 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
16430 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
16440 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
16450 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
16460 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
16470 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
16480 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
16490 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
164a0 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
164b0 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
164c0 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
164d0 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
164e0 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
164f0 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
16500 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
16510 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
16520 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
16530 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
16540 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
16550 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
16560 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
16570 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
16580 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
16590 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
165a0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
165b0 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
165c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
165d0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
165e0 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
165f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
16600 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
16610 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
16620 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62  er to a memory b
16630 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
16640 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
16650 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
16660 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
16670 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
16680 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
16690 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
166a0 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
166b0 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
166c0 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
166d0 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
166e0 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
166f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
16700 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
16710 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
16720 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
16730 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
16740 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
16750 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
16760 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
16770 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
16780 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
16790 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
167a0 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
167b0 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
167c0 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
167d0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
167e0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
167f0 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
16800 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
16810 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
16820 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
16830 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
16840 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
16850 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
16860 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
16870 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
16880 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
16890 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
168a0 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75   next smaller mu
168b0 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28  ltiple of 8.  ^(
168c0 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  The lookaside me
168d0 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  mory.** configur
168e0 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61  ation for a data
168f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
16900 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e  can only be chan
16910 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a  ged when that.**
16920 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e   connection is n
16930 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  ot currently usi
16940 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  ng lookaside mem
16950 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72  ory, or in other
16960 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74   words.** when t
16970 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75  he "current valu
16980 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  e" returned by.*
16990 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  * [sqlite3_db_st
169a0 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  atus](D,[SQLITE_
169b0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
169c0 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a  ],...) is zero..
169d0 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
169e0 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
169f0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
16a00 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e  nfiguration when
16a10 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65   lookaside.** me
16a20 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c  mory is in use l
16a30 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67  eaves the config
16a40 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65  uration unchange
16a50 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a  d and returns .*
16a60 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
16a70 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  )^</dd>.**.** <d
16a80 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
16a90 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64  G_ENABLE_FKEY</d
16aa0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
16ab0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
16ac0 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
16ad0 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65  able the enforce
16ae0 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65  ment of.** [fore
16af0 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
16b00 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f  nts].  There sho
16b10 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
16b20 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
16b30 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
16b40 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
16b50 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
16b60 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e  to disable FK en
16b70 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f  forcement,.** po
16b80 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
16b90 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
16ba0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
16bb0 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  eave FK enforcem
16bc0 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ent.** unchanged
16bd0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
16be0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
16bf0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
16c00 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
16c10 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
16c20 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
16c30 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63  hether FK enforc
16c40 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20  ement is off or 
16c50 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  on.** following 
16c60 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
16c70 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16c80 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
16c90 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
16ca0 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20  ich case the FK 
16cb0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74  enforcement sett
16cc0 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
16cd0 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
16ce0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
16cf0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
16d00 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a  _TRIGGER</dt>.**
16d10 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
16d20 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
16d30 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
16d40 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
16d50 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20  | triggers]..** 
16d60 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
16d70 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
16d80 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
16d90 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16da0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
16db0 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
16dc0 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a  ble triggers,.**
16dd0 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
16de0 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20  ble triggers or 
16df0 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
16e00 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e  e the setting un
16e10 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
16e20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16e30 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
16e40 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
16e50 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
16e60 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
16e70 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
16e80 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73  triggers are dis
16e90 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
16ea0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
16eb0 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
16ec0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
16ed0 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
16ee0 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
16ef0 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67  h case the trigg
16f00 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  er setting is no
16f10 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
16f20 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64   </dd>.**.** </d
16f30 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
16f40 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
16f50 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30  OKASIDE       10
16f60 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  01  /* void* int
16f70 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
16f80 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16f90 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20  ENABLE_FKEY     
16fa0 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74  1002  /* int int
16fb0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
16fc0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
16fd0 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30  BLE_TRIGGER  100
16fe0 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  3  /* int int* *
16ff0 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
17000 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
17010 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
17020 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a  esult Codes.**.*
17030 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
17040 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
17050 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
17060 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
17070 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
17080 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
17090 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
170a0 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64  ite. ^The extend
170b0 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
170c0 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
170d0 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
170e0 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
170f0 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20  ibility..*/.int 
17100 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
17110 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
17120 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
17130 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
17140 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
17150 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61   Rowid.**.** ^Ea
17160 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74  ch entry in most
17170 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28   SQLite tables (
17180 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48  except for [WITH
17190 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
171a0 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71  s).** has a uniq
171b0 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
171c0 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
171d0 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
171e0 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
171f0 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
17200 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
17210 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
17220 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
17230 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
17240 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
17250 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
17260 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
17270 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
17280 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
17290 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
172a0 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
172b0 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
172c0 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
172d0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
172e0 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
172f0 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
17300 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
17310 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
17320 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61  rowid(D) interfa
17330 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
17340 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a  rowid] of the .*
17350 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75  * most recent su
17360 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
17370 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74  ] into a rowid t
17380 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c  able or [virtual
17390 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61   table].** on da
173a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
173b0 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73  n D..** ^Inserts
173c0 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52   into [WITHOUT R
173d0 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65  OWID] tables are
173e0 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a   not recorded..*
173f0 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  * ^If no success
17400 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e  ful [INSERT]s in
17410 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a  to rowid tables.
17420 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
17430 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74  urred on the dat
17440 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17450 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c   D, .** then sql
17460 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
17470 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e  _rowid(D) return
17480 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s zero..**.** ^(
17490 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
174a0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
174b0 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e  rigger or within
174c0 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
174d0 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68  e].** method, th
174e0 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
174f0 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  will return the 
17500 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
17510 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61  nserted.** row a
17520 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
17530 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
17540 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73   table method is
17550 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
17560 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
17570 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
17580 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20  le method ends, 
17590 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
175a0 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72  ed .** by this r
175b0 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74  outine reverts t
175c0 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65  o what it was be
175d0 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
175e0 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74   or virtual.** t
175f0 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61  able method bega
17600 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b  n.)^.**.** ^An [
17610 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69  INSERT] that fai
17620 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
17630 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
17640 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
17650 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
17660 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
17670 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
17680 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
17690 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68  ** routine.  ^Th
176a0 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
176b0 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
176c0 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
176d0 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
176e0 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
176f0 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
17700 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
17710 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
17720 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
17730 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
17740 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52  s.  ^(When INSER
17750 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20  T OR REPLACE.** 
17760 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
17770 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
17780 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
17790 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
177a0 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
177b0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
177c0 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
177d0 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
177e0 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
177f0 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
17800 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
17810 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
17820 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
17830 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
17840 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  ace.)^.**.** ^Fo
17850 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
17860 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
17870 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
17880 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
17890 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
178a0 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
178b0 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
178c0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  back..**.** This
178d0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63   function is acc
178e0 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73  essible to SQL s
178f0 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68  tatements via th
17900 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72  e.** [last_inser
17910 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75  t_rowid() SQL fu
17920 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
17930 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
17940 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
17950 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74  ew [INSERT] on t
17960 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62  he same.** datab
17970 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
17980 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
17990 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
179a0 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  wid()].** functi
179b0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
179c0 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
179d0 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  he last insert [
179e0 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20  rowid],.** then 
179f0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
17a00 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
17a10 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
17a20 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64  ()] is.** unpred
17a30 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
17a40 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
17a50 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
17a60 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e  e new.** last in
17a70 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f  sert [rowid]..*/
17a80 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
17a90 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
17aa0 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
17ab0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
17ac0 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
17ad0 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
17ae0 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
17af0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
17b00 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
17b10 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c  f rows modified,
17b20 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20   inserted or.** 
17b30 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d  deleted by the m
17b40 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
17b50 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
17b60 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a  PDATE or DELETE.
17b70 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20  ** statement on 
17b80 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
17b90 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65  nection specifie
17ba0 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61  d by the only pa
17bb0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65  rameter..** ^Exe
17bc0 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72  cuting any other
17bd0 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61   type of SQL sta
17be0 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
17bf0 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75 65  modify the value
17c00 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
17c10 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  this function..*
17c20 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67  *.** ^Only chang
17c30 65 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79  es made directly
17c40 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20   by the INSERT, 
17c50 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
17c60 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a   statement are.*
17c70 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61  * considered - a
17c80 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73  uxiliary changes
17c90 20 63 61 75 73 65 64 20 62 79 20 5b 43 52 45 41   caused by [CREA
17ca0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
17cb0 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72  ggers], .** [for
17cc0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
17cd0 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63  ] or [REPLACE] c
17ce0 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
17cf0 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75  tion are not cou
17d00 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61  nted..** .** Cha
17d10 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
17d20 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70  hat are intercep
17d30 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54  ted by .** [INST
17d40 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c  EAD OF trigger |
17d50 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67   INSTEAD OF trig
17d60 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f  gers] are not co
17d70 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75  unted. ^The valu
17d80 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  e .** returned b
17d90 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  y sqlite3_change
17da0 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  s() immediately 
17db0 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c  after an INSERT,
17dc0 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44   UPDATE or .** D
17dd0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
17de0 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73  run on a view is
17df0 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e   always zero. On
17e00 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  ly changes made 
17e10 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c  to real .** tabl
17e20 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
17e30 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65  **.** Things are
17e40 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65   more complicate
17e50 64 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33  d if the sqlite3
17e60 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
17e70 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74  ion is.** execut
17e80 65 64 20 77 68 69 6c 65 20 61 20 74 72 69 67 67  ed while a trigg
17e90 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75  er program is ru
17ea0 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20  nning. This may 
17eb0 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a  happen if the.**
17ec0 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68   program uses th
17ed0 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
17ee0 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69   function], or i
17ef0 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c  f some other cal
17f00 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
17f10 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65  n invokes sqlite
17f20 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72 65  3_changes() dire
17f30 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c  ctly. Essentiall
17f40 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a  y:.** .** <ul>.*
17f50 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72  *   <li> ^(Befor
17f60 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69  e entering a tri
17f70 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65  gger program the
17f80 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
17f90 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c  by.**        sql
17fa0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66  ite3_changes() f
17fb0 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64  unction is saved
17fc0 2e 20 41 66 74 65 72 20 74 68 65 20 74 72 69 67  . After the trig
17fd0 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20  ger program .** 
17fe0 20 20 20 20 20 20 20 68 61 73 20 66 69 6e 69 73         has finis
17ff0 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61  hed, the origina
18000 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f  l value is resto
18010 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20  red.)^.** .**   
18020 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20  <li> ^(Within a 
18030 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
18040 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44  each INSERT, UPD
18050 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a  ATE and DELETE .
18060 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74 65 6d  **        statem
18070 65 6e 74 20 73 65 74 73 20 74 68 65 20 76 61 6c  ent sets the val
18080 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
18090 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
180a0 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e   .**        upon
180b0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e   completion as n
180c0 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65  ormal. Of course
180d0 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c  , this value wil
180e0 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a  l not include .*
180f0 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63 68 61  *        any cha
18100 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62  nges performed b
18110 79 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20  y sub-triggers, 
18120 61 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  as the sqlite3_c
18130 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20  hanges() .**    
18140 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62      value will b
18150 65 20 73 61 76 65 64 20 61 6e 64 20 72 65 73 74  e saved and rest
18160 6f 72 65 64 20 61 66 74 65 72 20 65 61 63 68 20  ored after each 
18170 73 75 62 2d 74 72 69 67 67 65 72 20 68 61 73 20  sub-trigger has 
18180 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  run.)^.** </ul>.
18190 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61  ** .** ^This mea
181a0 6e 73 20 74 68 61 74 20 69 66 20 74 68 65 20 63  ns that if the c
181b0 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
181c0 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61  ction (or simila
181d0 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79  r) is used.** by
181e0 20 74 68 65 20 66 69 72 73 74 20 49 4e 53 45 52   the first INSER
181f0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
18200 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
18210 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
18220 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74  it .** returns t
18230 68 65 20 76 61 6c 75 65 20 61 73 20 73 65 74 20  he value as set 
18240 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67  when the calling
18250 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e   statement began
18260 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
18270 49 66 20 69 74 20 69 73 20 75 73 65 64 20 62 79  If it is used by
18280 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73   the second or s
18290 75 62 73 65 71 75 65 6e 74 20 73 75 63 68 20 73  ubsequent such s
182a0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
182b0 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72  a trigger .** pr
182c0 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65  ogram, the value
182d0 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63   returned reflec
182e0 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ts the number of
182f0 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62   rows modified b
18300 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f  y the .** previo
18310 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  us INSERT, UPDAT
18320 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
18330 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
18340 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a   same trigger..*
18350 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
18360 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
18370 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
18380 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
18390 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
183a0 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63  gma], and the [c
183b0 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
183c0 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
183d0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
183e0 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
183f0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
18400 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18410 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
18420 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  e3_changes()] is
18430 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
18440 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
18450 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74  .** is unpredict
18460 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
18470 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
18480 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
18490 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
184a0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
184b0 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
184c0 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20   Modified.**.** 
184d0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
184e0 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c  eturns the total
184f0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
18500 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69  inserted, modifi
18510 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
18520 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d   by all [INSERT]
18530 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44  , [UPDATE] or [D
18540 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
18550 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73  s completed.** s
18560 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73  ince the databas
18570 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73  e connection was
18580 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69   opened, includi
18590 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75 74 65  ng those execute
185a0 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20  d as.** part of 
185b0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73  trigger programs
185c0 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  . ^Executing any
185d0 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
185e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
185f0 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20  does not affect 
18600 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
18610 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
18620 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a  tal_changes()..*
18630 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d  * .** ^Changes m
18640 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ade as part of [
18650 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
18660 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65  ons] are include
18670 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e  d in the.** coun
18680 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64  t, but those mad
18690 65 20 61 73 20 70 61 72 74 20 6f 66 20 52 45 50  e as part of REP
186a0 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20  LACE constraint 
186b0 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a  resolution are.*
186c0 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20  * not. ^Changes 
186d0 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
186e0 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62  re intercepted b
186f0 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  y INSTEAD OF tri
18700 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f  ggers .** are no
18710 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a  t counted..** .*
18720 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
18730 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
18740 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
18750 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
18760 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
18770 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e   the [total_chan
18780 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
18790 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
187a0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
187b0 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
187c0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
187d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
187e0 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
187f0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
18800 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
18810 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
18820 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64  turned is unpred
18830 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
18840 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
18850 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  nt sqlite3_total
18860 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
18870 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
18880 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
18890 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
188a0 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ery.**.** ^This 
188b0 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
188c0 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
188d0 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
188e0 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
188f0 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
18900 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
18910 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
18920 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
18930 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
18940 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
18950 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
18960 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
18970 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
18980 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
18990 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
189a0 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
189b0 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
189c0 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
189d0 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
189e0 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
189f0 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
18a00 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
18a10 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
18a20 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
18a30 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
18a40 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
18a50 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
18a60 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
18a70 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
18a80 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
18a90 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
18aa0 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
18ab0 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
18ac0 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
18ad0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
18ae0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
18af0 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
18b00 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
18b10 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
18b20 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
18b30 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
18b40 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
18b50 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
18b60 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
18b70 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
18b80 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
18b90 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
18ba0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
18bb0 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
18bc0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
18bd0 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
18be0 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
18bf0 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
18c00 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
18c10 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
18c20 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
18c30 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
18c40 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
18c50 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
18c60 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
18c70 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
18c80 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
18c90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
18ca0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
18cb0 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
18cc0 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
18cd0 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
18ce0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
18cf0 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
18d00 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
18d10 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
18d20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
18d30 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
18d40 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
18d50 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
18d60 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
18d70 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
18d80 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
18d90 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
18da0 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
18db0 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
18dc0 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
18dd0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
18de0 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
18df0 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
18e00 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
18e10 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
18e20 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
18e30 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
18e40 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
18e50 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
18e60 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
18e70 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
18e80 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
18e90 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
18ea0 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
18eb0 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
18ec0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
18ed0 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
18ee0 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
18ef0 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
18f00 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
18f10 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
18f20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
18f30 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
18f40 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ..**.** If the d
18f50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18f60 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
18f70 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
18f80 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
18f90 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
18fa0 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
18fb0 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20  happen..*/.void 
18fc0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
18fd0 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
18fe0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
18ff0 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
19000 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43  L Statement Is C
19010 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68  omplete.**.** Th
19020 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
19030 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63   useful during c
19040 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75  ommand-line inpu
19050 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69  t to determine i
19060 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  f the.** current
19070 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20  ly entered text 
19080 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20  seems to form a 
19090 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
190a0 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20  tement or.** if 
190b0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74  additional input
190c0 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72   is needed befor
190d0 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65  e sending the te
190e0 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74  xt into.** SQLit
190f0 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20  e for parsing.  
19100 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
19110 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20  return 1 if the 
19120 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
19130 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
19140 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
19150 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74  tement.  ^A stat
19160 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20  ement is judged 
19170 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  to be.** complet
19180 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74  e if it ends wit
19190 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f  h a semicolon to
191a0 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ken and is not a
191b0 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20   prefix of a.** 
191c0 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41  well-formed CREA
191d0 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
191e0 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f  ment.  ^Semicolo
191f0 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65  ns that are embe
19200 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73  dded within.** s
19210 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f  tring literals o
19220 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66  r quoted identif
19230 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d  ier names or com
19240 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ments are not.**
19250 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b   independent tok
19260 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61  ens (they are pa
19270 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20  rt of the token 
19280 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72  in which they ar
19290 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61  e.** embedded) a
192a0 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63  nd thus do not c
192b0 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d  ount as a statem
192c0 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ent terminator. 
192d0 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20   ^Whitespace.** 
192e0 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61  and comments tha
192f0 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e  t follow the fin
19300 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65  al semicolon are
19310 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
19320 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
19330 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20  return 0 if the 
19340 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63  statement is inc
19350 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a  omplete.  ^If a.
19360 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
19370 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e  tion fails, then
19380 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73   SQLITE_NOMEM is
19390 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
193a0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
193b0 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68   do not parse th
193c0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
193d0 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f   thus.** will no
193e0 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74  t detect syntact
193f0 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74  ically incorrect
19400 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66   SQL..**.** ^(If
19410 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20   SQLite has not 
19420 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64  been initialized
19430 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
19440 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72  initialize()] pr
19450 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b  ior .** to invok
19460 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ing sqlite3_comp
19470 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71  lete16() then sq
19480 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
19490 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
194a0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
194b0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  y sqlite3_comple
194c0 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74  te16().  If that
194d0 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
194e0 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  fails,.** then t
194f0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
19500 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d  from sqlite3_com
19510 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62  plete16() will b
19520 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65  e non-zero.** re
19530 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
19540 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69  her or not the i
19550 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70  nput SQL is comp
19560 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  lete.)^.**.** Th
19570 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
19580 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20  te3_complete()] 
19590 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
195a0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
195b0 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
195c0 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
195d0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
195e0 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  6()] must be a z
195f0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
19600 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  * UTF-16 string 
19610 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
19620 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rder..*/.int sql
19630 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
19640 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
19650 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
19660 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
19670 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
19680 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
19690 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
196a0 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
196b0 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45  USY Errors.** KE
196c0 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61  YWORDS: {busy-ha
196d0 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20  ndler callback} 
196e0 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a  {busy handler}.*
196f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
19700 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44  3_busy_handler(D
19710 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65  ,X,P) routine se
19720 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
19730 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74  nction X.** that
19740 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
19750 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  d with argument 
19760 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  P whenever.** an
19770 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
19780 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61 74   to access a dat
19790 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f  abase table asso
197a0 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b  ciated with.** [
197b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
197c0 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74  ion] D when anot
197d0 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
197e0 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68 65   process has the
197f0 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a   table locked..*
19800 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75  * The sqlite3_bu
19810 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74  sy_handler() int
19820 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
19830 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b  o implement.** [
19840 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
19850 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41  eout()] and [PRA
19860 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
19870 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
19880 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
19890 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51  s NULL, then [SQ
198a0 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73  LITE_BUSY].** is
198b0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
198c0 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
198d0 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
198e0 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
198f0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
19900 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
19910 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
19920 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
19930 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
19940 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
19950 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
19960 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
19970 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
19980 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
19990 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
199a0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
199b0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
199c0 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
199d0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
199e0 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
199f0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
19a00 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
19a10 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
19a20 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
19a30 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72   been invoked pr
19a40 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65  eviously for the
19a50 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76   same locking ev
19a60 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
19a70 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72   busy callback r
19a80 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e  eturns 0, then n
19a90 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74  o additional att
19aa0 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74  empts are made t
19ab0 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20  o.** access the 
19ac0 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51  database and [SQ
19ad0 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65  LITE_BUSY] is re
19ae0 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65  turned.** to the
19af0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a   application..**
19b00 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
19b10 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
19b20 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
19b30 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d   attempt.** is m
19b40 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74 68  ade to access th
19b50 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74  e database and t
19b60 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
19b70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
19b80 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
19b90 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
19ba0 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
19bb0 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
19bc0 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
19bd0 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
19be0 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64  on. ^If SQLite d
19bf0 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
19c00 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
19c10 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  .** handler coul
19c20 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65  d result in a de
19c30 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
19c40 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
19c50 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
19c60 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c  ].** to the appl
19c70 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20  ication instead 
19c80 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  of invoking the 
19c90 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72  .** busy handler
19ca0 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
19cb0 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
19cc0 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
19cd0 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
19ce0 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
19cf0 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
19d00 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
19d10 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
19d20 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
19d30 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
19d40 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
19d50 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
19d60 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
19d70 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
19d80 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
19d90 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
19da0 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
19db0 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
19dc0 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
19dd0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
19de0 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
19df0 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
19e00 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
19e10 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
19e20 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
19e30 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
19e40 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
19e50 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
19e60 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
19e70 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
19e80 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
19e90 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
19ea0 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
19eb0 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
19ec0 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
19ed0 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
19ee0 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
19ef0 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
19f00 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
19f10 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
19f20 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
19f30 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
19f40 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s NULL..**.** ^(
19f50 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
19f60 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
19f70 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
19f80 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
19f90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19fa0 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
19fb0 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
19fc0 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
19fd0 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
19fe0 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68  ler.)^  ^Note th
19ff0 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
1a000 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1a010 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61  ()].** or evalua
1a020 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73  ting [PRAGMA bus
1a030 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c  y_timeout=N] wil
1a040 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  l change the.** 
1a050 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64  busy handler and
1a060 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20   thus clear any 
1a070 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62  previously set b
1a080 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
1a090 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
1a0a0 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
1a0b0 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
1a0c0 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
1a0d0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
1a0e0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
1a0f0 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
1a100 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65  andler.  In othe
1a110 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20  r words,.** the 
1a120 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1a130 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20  not reentrant.  
1a140 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73  Any such actions
1a150 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  .** result in un
1a160 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
1a170 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20  ..** .** A busy 
1a180 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74  handler must not
1a190 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
1a1a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1a1b0 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73  * or [prepared s
1a1c0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
1a1d0 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
1a1e0 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20  handler..*/.int 
1a1f0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1a200 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
1a210 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29  nt(*)(void*,int)
1a220 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1a230 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41   CAPI3REF: Set A
1a240 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a   Busy Timeout.**
1a250 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
1a260 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65  e sets a [sqlite
1a270 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c  3_busy_handler |
1a280 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74   busy handler] t
1a290 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f  hat sleeps.** fo
1a2a0 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d  r a specified am
1a2b0 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65  ount of time whe
1a2c0 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63  n a table is loc
1a2d0 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ked.  ^The handl
1a2e0 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70  er.** will sleep
1a2f0 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
1a300 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22  until at least "
1a310 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
1a320 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20   of sleeping.** 
1a330 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64  have accumulated
1a340 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61  .  ^After at lea
1a350 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
1a360 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
1a370 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  ,.** the handler
1a380 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68   returns 0 which
1a390 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33   causes [sqlite3
1a3a0 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75  _step()] to retu
1a3b0 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  rn.** [SQLITE_BU
1a3c0 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  SY]..**.** ^Call
1a3d0 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
1a3e0 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
1a3f0 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
1a400 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
1a410 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
1a420 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
1a430 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
1a440 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
1a450 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
1a460 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
1a470 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1a480 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69  ction] at any gi
1a490 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
1a4a0 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
1a4b0 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
1a4c0 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
1a4d0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1a4e0 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
1a4f0 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
1a500 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
1a510 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
1a520 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a  is cleared.)^.**
1a530 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
1a540 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
1a550 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  out].*/.int sqli
1a560 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1a570 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
1a580 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
1a590 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
1a5a0 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
1a5b0 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a  nning Queries.**
1a5c0 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65  .** This is a le
1a5d0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74  gacy interface t
1a5e0 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64  hat is preserved
1a5f0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
1a600 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1a610 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74   Use of this int
1a620 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
1a630 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
1a640 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c   Definition: A <
1a650 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f  b>result table</
1a660 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74  b> is memory dat
1a670 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61  a structure crea
1a680 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73  ted by the.** [s
1a690 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1a6a0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
1a6b0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72  A result table r
1a6c0 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f  ecords the.** co
1a6d0 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73  mplete query res
1a6e0 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72  ults from one or
1a6f0 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a   more queries..*
1a700 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63  *.** The table c
1a710 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20  onceptually has 
1a720 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  a number of rows
1a730 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42   and columns.  B
1a740 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62  ut.** these numb
1a750 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74  ers are not part
1a760 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
1a770 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68  able itself.  Th
1a780 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61  ese.** numbers a
1a790 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61  re obtained sepa
1a7a0 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62  rately.  Let N b
1a7b0 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1a7c0 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65  rows.** and M be
1a7d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1a7e0 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  olumns..**.** A 
1a7f0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
1a800 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
1a810 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
1a820 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
1a830 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20  rings..** There 
1a840 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d  are (N+1)*M elem
1a850 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61  ents in the arra
1a860 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20  y.  The first M 
1a870 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a  pointers point.*
1a880 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  * to zero-termin
1a890 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
1a8a0 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e  t  contain the n
1a8b0 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ames of the colu
1a8c0 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61  mns..** The rema
1a8d0 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c  ining entries al
1a8e0 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79  l point to query
1a8f0 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20   results.  NULL 
1a900 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a  values result.**
1a910 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   in NULL pointer
1a920 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  s.  All other va
1a930 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69  lues are in thei
1a940 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  r UTF-8 zero-ter
1a950 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
1a960 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  g representation
1a970 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   as returned by 
1a980 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1a990 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  text()]..**.** A
1a9a0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69   result table mi
1a9b0 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f  ght consist of o
1a9c0 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
1a9d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
1a9e0 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
1a9f0 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
1aa00 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
1aa10 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1aa20 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
1aa30 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
1aa40 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
1aa50 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
1aa60 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
1aa70 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c  * ^(As an exampl
1aa80 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  e of the result 
1aa90 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75  table format, su
1aaa0 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65  ppose a query re
1aab0 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f  sult.** is as fo
1aac0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1aad0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1aae0 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  *        Name   
1aaf0 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20       | Age.**   
1ab00 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d       -----------
1ab10 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20  ------------.** 
1ab20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20         Alice    
1ab30 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20     | 43.**      
1ab40 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20    Bob         | 
1ab50 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e  28.**        Cin
1ab60 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a  dy       | 21.**
1ab70 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1ab80 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ote>.**.** There
1ab90 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20   are two column 
1aba0 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65  (M==2) and three
1abb0 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54   rows (N==3).  T
1abc0 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  hus the.** resul
1abd0 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e  t table has 8 en
1abe0 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20  tries.  Suppose 
1abf0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1ac00 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e   is stored.** in
1ac10 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20   an array names 
1ac20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20  azResult.  Then 
1ac30 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74  azResult holds t
1ac40 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a  his content:.**.
1ac50 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1ac60 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61  pre>.**        a
1ac70 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d  zResult&#91;0] =
1ac80 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
1ac90 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1aca0 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
1acb0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1acc0 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  91;2] = "Alice";
1acd0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1ace0 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33  ult&#91;3] = "43
1acf0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1ad00 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22  esult&#91;4] = "
1ad10 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
1ad20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20  azResult&#91;5] 
1ad30 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
1ad40 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36    azResult&#91;6
1ad50 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
1ad60 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1ad70 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a  #91;7] = "21";.*
1ad80 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1ad90 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
1ada0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1adb0 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  able() function 
1adc0 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72  evaluates one or
1add0 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c   more.** semicol
1ade0 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c  on-separated SQL
1adf0 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
1ae00 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
1ae10 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69  ed UTF-8.** stri
1ae20 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
1ae30 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
1ae40 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  rns a result tab
1ae50 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69  le to the.** poi
1ae60 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74  nter given in it
1ae70 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e  s 3rd parameter.
1ae80 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65  .**.** After the
1ae90 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73   application has
1aea0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74   finished with t
1aeb0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73  he result from s
1aec0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1aed0 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70  (),.** it must p
1aee0 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74  ass the result t
1aef0 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20  able pointer to 
1af00 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1af10 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
1af20 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
1af30 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
1af40 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
1af50 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
1af60 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
1af70 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
1af80 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
1af90 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
1afa0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
1afb0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
1afc0 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
1afd0 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
1afe0 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
1aff0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1b000 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
1b010 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1b020 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
1b030 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
1b040 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1b050 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
1b060 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
1b070 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
1b080 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
1b090 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
1b0a0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1b0b0 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
1b0c0 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
1b0d0 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
1b0e0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
1b0f0 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
1b100 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
1b110 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
1b120 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
1b130 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
1b140 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
1b150 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
1b160 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
1b170 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
1b180 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
1b190 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
1b1a0 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
1b1b0 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
1b1c0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
1b1d0 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20  rrcode()] or.** 
1b1e0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1b1f0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
1b200 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
1b210 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1b220 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
1b230 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
1b240 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
1b250 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
1b260 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
1b270 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
1b280 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
1b290 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
1b2a0 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
1b2b0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
1b2c0 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
1b2d0 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
1b2e0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
1b2f0 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
1b300 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
1b310 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
1b320 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
1b330 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
1b340 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
1b350 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
1b360 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1b370 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
1b380 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
1b390 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
1b3a0 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
1b3b0 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1b3c0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1b3d0 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73   are work-alikes
1b3e0 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
1b3f0 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
1b400 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
1b410 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1b420 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20  brary..** These 
1b430 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74  routines underst
1b440 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20  and most of the 
1b450 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61  common K&R forma
1b460 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a  tting options,.*
1b470 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69  * plus some addi
1b480 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64  tional non-stand
1b490 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74  ard formats, det
1b4a0 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20  ailed below..** 
1b4b0 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f  Note that some o
1b4c0 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75  f the more obscu
1b4d0 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  re formatting op
1b4e0 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e  tions from recen
1b4f0 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73  t.** C-library s
1b500 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69  tandards are omi
1b510 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69  tted from this i
1b520 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a  mplementation..*
1b530 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1b540 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
1b550 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1b560 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
1b570 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
1b580 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
1b590 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
1b5a0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
1b5b0 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
1b5c0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1b5d0 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
1b5e0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
1b5f0 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
1b600 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
1b610 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1b620 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
1b630 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
1b640 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
1b650 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
1b660 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
1b670 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
1b680 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
1b690 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1b6a0 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
1b6b0 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
1b6c0 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
1b6d0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
1b6e0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
1b6f0 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
1b700 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
1b710 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
1b720 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1b730 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
1b740 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
1b750 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
1b760 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
1b770 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
1b780 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
1b790 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
1b7a0 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
1b7b0 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
1b7c0 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
1b7d0 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
1b7e0 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
1b7f0 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
1b800 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
1b810 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1b820 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
1b830 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
1b840 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
1b850 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
1b860 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
1b870 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
1b880 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
1b890 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
1b8a0 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
1b8b0 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
1b8c0 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
1b8d0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
1b8e0 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
1b8f0 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
1b900 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
1b910 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
1b920 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
1b930 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
1b940 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
1b950 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
1b960 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
1b970 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
1b980 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
1b990 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
1b9a0 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
1b9b0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1b9c0 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
1b9d0 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
1b9e0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
1b9f0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
1ba00 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
1ba10 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
1ba20 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
1ba30 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
1ba40 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
1ba50 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1ba60 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
1ba70 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
1ba80 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
1ba90 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
1baa0 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
1bab0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1bac0 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
1bad0 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
1bae0 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
1baf0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1bb00 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
1bb10 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
1bb20 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
1bb30 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
1bb40 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
1bb50 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
1bb60 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
1bb70 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1bb80 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
1bb90 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
1bba0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
1bbb0 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
1bbc0 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
1bbd0 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
1bbe0 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70  "%w" and "%z" op
1bbf0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
1bc00 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
1bc10 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
1bc20 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
1bc30 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  s a nul-terminat
1bc40 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
1bc50 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
1bc60 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
1bc70 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
1bc80 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
1bc90 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
1bca0 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
1bcb0 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1bcc0 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
1bcd0 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
1bce0 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
1bcf0 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
1bd00 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
1bd10 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
1bd20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
1bd30 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
1bd40 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
1bd50 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
1bd60 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
1bd70 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
1bd80 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1bd90 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1bda0 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
1bdb0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
1bdc0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1bdd0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
1bde0 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
1bdf0 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
1be00 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
1be10 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1be20 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1be30 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1be40 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1be50 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1be60 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
1be70 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1be80 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1be90 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1bea0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1beb0 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1bec0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1bed0 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
1bee0 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
1bef0 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
1bf00 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
1bf10 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
1bf20 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
1bf30 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
1bf40 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1bf50 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1bf60 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1bf70 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1bf80 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1bf90 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
1bfa0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1bfb0 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
1bfc0 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
1bfd0 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
1bfe0 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
1bff0 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
1c000 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
1c010 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1c020 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1c030 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1c040 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
1c050 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
1c060 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1c070 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
1c080 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
1c090 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
1c0a0 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
1c0b0 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
1c0c0 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
1c0d0 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
1c0e0 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
1c0f0 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
1c100 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
1c110 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
1c120 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1c130 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
1c140 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
1c150 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
1c160 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
1c170 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
1c180 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
1c190 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
1c1a0 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
1c1b0 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
1c1c0 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
1c1d0 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
1c1e0 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
1c1f0 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
1c200 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
1c210 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
1c220 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
1c230 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1c240 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1c250 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1c260 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1c270 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
1c280 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1c290 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1c2a0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1c2b0 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1c2c0 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1c2d0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1c2e0 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
1c2f0 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
1c300 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
1c310 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
1c320 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
1c330 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
1c340 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
1c350 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1c360 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72  * ^(The "%w" for
1c370 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69  matting option i
1c380 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65  s like "%q" exce
1c390 70 74 20 74 68 61 74 20 69 74 20 65 78 70 65 63  pt that it expec
1c3a0 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74  ts to.** be cont
1c3b0 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75  ained within dou
1c3c0 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65  ble-quotes inste
1c3d0 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f  ad of single quo
1c3e0 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65  tes, and it.** e
1c3f0 73 63 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c  scapes the doubl
1c400 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74 65  e-quote characte
1c410 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
1c420 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a   single-quote.**
1c430 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54   character.)^  T
1c440 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69  he "%w" formatti
1c450 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74  ng option is int
1c460 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79  ended for safely
1c470 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61   inserting.** ta
1c480 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e  ble and column n
1c490 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73  ames into a cons
1c4a0 74 72 75 63 74 65 64 20 53 51 4c 20 73 74 61 74  tructed SQL stat
1c4b0 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ement..**.** ^(T
1c4c0 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
1c4d0 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
1c4e0 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
1c4f0 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
1c500 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
1c510 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
1c520 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
1c530 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
1c540 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
1c550 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
1c560 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
1c570 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20  ring.)^.*/.char 
1c580 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
1c590 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
1c5a0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1c5b0 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
1c5c0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1c5d0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
1c5e0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1c5f0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
1c600 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1c610 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
1c620 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1c630 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
1c640 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1c650 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
1c660 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
1c670 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
1c680 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
1c690 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
1c6a0 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
1c6b0 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
1c6c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
1c6d0 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
1c6e0 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
1c6f0 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
1c700 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
1c710 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
1c720 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1c730 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
1c740 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
1c750 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
1c760 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
1c770 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
1c780 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1c790 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
1c7a0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1c7b0 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
1c7c0 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
1c7d0 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1c7e0 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
1c7f0 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
1c800 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1c810 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
1c820 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
1c830 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
1c840 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
1c850 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1c860 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
1c870 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
1c880 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1c890 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
1c8a0 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
1c8b0 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
1c8c0 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1c8d0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
1c8e0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
1c8f0 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b  (N) routine work
1c900 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73  s just like.** s
1c910 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1c920 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
1c930 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34  s an unsigned 64
1c940 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73  -bit integer ins
1c950 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67  tead.** of a sig
1c960 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67  ned 32-bit integ
1c970 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
1c980 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
1c990 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
1c9a0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
1c9b0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1c9c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1c9d0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c9e0 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
1c9f0 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
1ca00 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
1ca10 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
1ca20 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
1ca30 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
1ca40 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
1ca50 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
1ca60 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
1ca70 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
1ca80 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1ca90 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
1caa0 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
1cab0 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
1cac0 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
1cad0 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
1cae0 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
1caf0 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
1cb00 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
1cb10 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
1cb20 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
1cb30 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1cb40 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
1cb50 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
1cb60 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
1cb70 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1cb80 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
1cb90 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
1cba0 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
1cbb0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
1cbc0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
1cbd0 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
1cbe0 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1cbf0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1cc00 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1cc10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1cc20 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e  _realloc(X,N) in
1cc30 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
1cc40 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
1cc50 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
1cc60 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  ocation X to be 
1cc70 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1cc80 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70  ..** ^If the X p
1cc90 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1cca0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1ccb0 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
1ccc0 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
1ccd0 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
1cce0 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
1ccf0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1cd00 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  c(N)..** ^If the
1cd10 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   N parameter to 
1cd20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1cd30 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  X,N) is zero or.
1cd40 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
1cd50 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1cd60 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
1cd70 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
1cd80 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e  sqlite3_free(X).
1cd90 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
1cda0 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1cdb0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1cdc0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1cdd0 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
1cde0 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
1cdf0 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73  e or NULL if ins
1ce00 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
1ce10 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
1ce20 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73  * ^If M is the s
1ce30 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
1ce40 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
1ce50 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
1ce60 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
1ce70 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
1ce80 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
1ce90 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
1cea0 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
1ceb0 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
1cec0 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20  oc(X,N) and the 
1ced0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1cee0 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
1cef0 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
1cf00 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e  c(X,N) returns N
1cf10 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73  ULL and N is pos
1cf20 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a  itive, then the.
1cf30 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  ** prior allocat
1cf40 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64  ion is not freed
1cf50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1cf60 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58  ite3_realloc64(X
1cf70 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77  ,N) interfaces w
1cf80 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73  orks the same as
1cf90 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  .** sqlite3_real
1cfa0 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20  loc(X,N) except 
1cfb0 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62  that N is a 64-b
1cfc0 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
1cfd0 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ger instead.** o
1cfe0 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65  f a 32-bit signe
1cff0 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  d integer..**.**
1d000 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f   ^If X is a memo
1d010 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72  ry allocation pr
1d020 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
1d030 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1d040 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
1d050 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
1d060 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1d070 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ), or sqlite3_re
1d080 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a  alloc64(), then.
1d090 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
1d0a0 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (X) returns the 
1d0b0 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d  size of that mem
1d0c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ory allocation i
1d0d0 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65  n bytes..** ^The
1d0e0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1d0f0 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  by sqlite3_msize
1d100 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72  (X) might be lar
1d110 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d  ger than the num
1d120 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20  ber.** of bytes 
1d130 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58  requested when X
1d140 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20   was allocated. 
1d150 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c   ^If X is a NULL
1d160 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a   pointer then.**
1d170 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1d180 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20  ) returns zero. 
1d190 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20   If X points to 
1d1a0 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69  something that i
1d1b0 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67  s not.** the beg
1d1c0 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79  inning of memory
1d1d0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20   allocation, or 
1d1e0 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20  if it points to 
1d1f0 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61  a formerly.** va
1d200 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  lid memory alloc
1d210 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e  ation that has n
1d220 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74  ow been freed, t
1d230 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1d240 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d  .** of sqlite3_m
1d250 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66  size(X) is undef
1d260 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c  ined and possibl
1d270 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
1d280 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
1d290 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1d2a0 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74  _malloc(), sqlit
1d2b0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a  e3_realloc(),.**
1d2c0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1d2d0 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  4(), and sqlite3
1d2e0 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20  _realloc64().** 
1d2f0 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
1d300 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
1d310 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
1d320 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62  , or to a.** 4 b
1d330 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20  yte boundary if 
1d340 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59  the [SQLITE_4_BY
1d350 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f  TE_ALIGNED_MALLO
1d360 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  C] compile-time.
1d370 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ** option is use
1d380 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69  d..**.** In SQLi
1d390 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
1d3a0 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77   and 3.5.1, it w
1d3b0 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64  as possible to d
1d3c0 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c  efine.** the SQL
1d3d0 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f  ITE_OMIT_MEMORY_
1d3e0 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68  ALLOCATION which
1d3f0 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65   would cause the
1d400 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70   built-in.** imp
1d410 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
1d420 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  hese routines to
1d430 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68   be omitted.  Th
1d440 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  at capability.**
1d450 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72   is no longer pr
1d460 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75  ovided.  Only bu
1d470 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1d480 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20  locators can be 
1d490 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  used..**.** Prio
1d4a0 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
1d4b0 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20  ion 3.7.10, the 
1d4c0 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  Windows OS inter
1d4d0 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65  face layer calle
1d4e0 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  d.** the system 
1d4f0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1d500 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
1d510 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
1d520 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
1d530 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
1d540 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
1d550 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
1d560 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
1d570 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
1d580 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1d590 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
1d5a0 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
1d5b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
1d5c0 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64  rs were detected
1d5d0 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65  , but.** they we
1d5e0 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
1d5f0 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
1d600 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
1d610 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
1d620 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
1d630 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  OMEM]..**.** The
1d640 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
1d650 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
1d660 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
1d670 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
1d680 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
1d690 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
1d6a0 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
1d6b0 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
1d6c0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
1d6d0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1d6e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1d6f0 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
1d700 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
1d710 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
1d720 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1d730 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
1d740 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
1d750 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
1d760 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
1d770 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
1d780 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
1d790 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
1d7a0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1d7b0 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  oc()]..*/.void *
1d7c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
1d7d0 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
1d7e0 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69  e3_malloc64(sqli
1d7f0 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69  te3_uint64);.voi
1d800 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
1d810 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
1d820 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
1d830 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73  alloc64(void*, s
1d840 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
1d850 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
1d860 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65  e(void*);.sqlite
1d870 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  3_uint64 sqlite3
1d880 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a  _msize(void*);..
1d890 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d8a0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
1d8b0 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
1d8c0 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
1d8d0 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
1d8e0 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
1d8f0 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
1d900 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
1d910 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1d920 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1d930 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
1d940 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
1d950 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
1d960 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
1d970 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1d980 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
1d990 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1d9a0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1d9b0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1d9c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1d9d0 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
1d9e0 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
1d9f0 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
1da00 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
1da10 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1da20 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1da30 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
1da40 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
1da50 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
1da60 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1da70 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
1da80 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1da90 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
1daa0 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
1dab0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1dac0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1dad0 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
1dae0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1daf0 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
1db00 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
1db10 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
1db20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
1db30 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1db40 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
1db50 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
1db60 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
1db70 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
1db80 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
1db90 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
1dba0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1dbb0 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
1dbc0 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
1dbd0 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
1dbe0 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
1dbf0 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
1dc00 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1dc10 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
1dc20 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
1dc30 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
1dc40 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1dc50 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
1dc60 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
1dc70 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
1dc80 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1dc90 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
1dca0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1dcb0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
1dcc0 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74   reset..*/.sqlit
1dcd0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1dce0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
1dcf0 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  d);.sqlite3_int6
1dd00 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1dd10 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
1dd20 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
1dd30 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
1dd40 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
1dd50 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
1dd60 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
1dd70 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
1dd80 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
1dd90 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
1dda0 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
1ddb0 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
1ddc0 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
1ddd0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
1dde0 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
1ddf0 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
1de00 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
1de10 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
1de20 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
1de30 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
1de40 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
1de50 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
1de60 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
1de70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
1de80 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
1de90 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
1dea0 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
1deb0 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
1dec0 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
1ded0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
1dee0 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
1def0 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
1df00 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
1df10 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e  o buffer P..** ^
1df20 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20  The P parameter 
1df30 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  can be a NULL po
1df40 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  inter..**.** ^If
1df50 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
1df60 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69  s not been previ
1df70 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20  ously called or 
1df80 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a  if the previous.
1df90 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65  ** call had N le
1dfa0 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61  ss than one or a
1dfb0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
1dfc0 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52  r P, then the PR
1dfd0 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20  NG is.** seeded 
1dfe0 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
1dff0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74   obtained from t
1e000 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
1e010 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20  ethod of.** the 
1e020 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1e030 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
1e040 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75   ^If the previou
1e050 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  s call to this r
1e060 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20  outine had an N 
1e070 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64  of 1 or more and
1e080 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50   a.** non-NULL P
1e090 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f   then the pseudo
1e0a0 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
1e0b0 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
1e0c0 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
1e0d0 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
1e0e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
1e0f0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
1e100 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20  method..*/.void 
1e110 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
1e120 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
1e130 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
1e140 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
1e150 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
1e160 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
1e170 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
1e180 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f  gisters an autho
1e190 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
1e1a0 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
1e1b0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1e1c0 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
1e1d0 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
1e1e0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
1e1f0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1e200 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1e210 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
1e220 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
1e230 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
1e240 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1e250 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1e260 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e270 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
1e280 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1e290 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
1e2a0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
1e2b0 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20   ^At various.** 
1e2c0 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
1e2d0 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
1e2e0 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
1e2f0 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
1e300 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
1e310 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
1e320 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1e330 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1e340 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
1e350 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
1e360 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65  e allowed.  ^The
1e370 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1e380 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
1e390 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
1e3a0 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  ] to allow the a
1e3b0 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
1e3c0 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
1e3d0 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
1e3e0 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
1e3f0 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
1e400 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
1e410 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
1e420 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
1e430 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
1e440 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
1e450 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
1e460 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
1e470 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68  n error.  ^If th
1e480 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1e490 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
1e4a0 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
1e4b0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
1e4c0 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
1e4d0 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
1e4e0 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
1e4f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e500 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
1e510 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
1e520 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
1e530 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
1e540 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
1e550 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
1e560 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
1e570 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1e580 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
1e590 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
1e5a0 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
1e5b0 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68  is ok.  ^When th
1e5c0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1e5d0 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
1e5e0 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
1e5f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1e600 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
1e610 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
1e620 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
1e630 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
1e640 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
1e650 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
1e660 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
1e670 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20   denied. .**.** 
1e680 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
1e690 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1e6a0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1e6b0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
1e6c0 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
1e6d0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
1e6e0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1e6f0 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e  r() interface. ^
1e700 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1e710 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63  eter.** to the c
1e720 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1e730 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f  teger [SQLITE_CO
1e740 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65  PY | action code
1e750 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
1e760 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c  .** the particul
1e770 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  ar action to be 
1e780 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65  authorized. ^The
1e790 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
1e7a0 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
1e7b0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1e7c0 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
1e7d0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1e7e0 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
1e7f0 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
1e800 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
1e810 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
1e820 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  zed..**.** ^If t
1e830 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
1e840 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a  s [SQLITE_READ].
1e850 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  ** and the callb
1e860 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1e870 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
1e880 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
1e890 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61  d statement] sta
1e8a0 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
1e8b0 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74  ucted to substit
1e8c0 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61  ute.** a NULL va
1e8d0 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
1e8e0 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
1e8f0 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
1e900 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66  .** been read if
1e910 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
1e920 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20   been returned. 
1e930 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   The [SQLITE_IGN
1e940 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63  ORE].** return c
1e950 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
1e960 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  ny an untrusted 
1e970 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69  user access to i
1e980 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c  ndividual.** col
1e990 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e  umns of a table.
1e9a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
1e9b0 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
1e9c0 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
1e9d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1e9e0 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
1e9f0 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
1ea00 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
1ea10 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
1ea20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
1ea30 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
1ea40 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
1ea50 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
1ea60 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
1ea70 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
1ea80 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
1ea90 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
1eaa0 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
1eab0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1eac0 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
1ead0 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
1eae0 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
1eaf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1eb00 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
1eb10 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
1eb20 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
1eb30 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
1eb40 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
1eb50 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
1eb60 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
1eb70 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
1eb80 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
1eb90 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
1eba0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
1ebb0 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
1ebc0 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
1ebd0 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
1ebe0 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
1ebf0 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
1ec00 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
1ec10 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
1ec20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
1ec30 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
1ec40 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
1ec50 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
1ec60 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
1ec70 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
1ec80 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
1ec90 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
1eca0 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
1ecb0 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
1ecc0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
1ecd0 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
1ece0 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
1ecf0 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
1ed00 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
1ed10 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
1ed20 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
1ed30 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
1ed40 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
1ed50 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
1ed60 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
1ed70 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
1ed80 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1ed90 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
1eda0 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
1edb0 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
1edc0 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
1edd0 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
1ede0 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
1edf0 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
1ee00 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61  ..**.** ^(Only a
1ee10 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
1ee20 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
1ee30 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
1ee40 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
1ee50 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
1ee60 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
1ee70 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
1ee80 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
1ee90 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e  previous call.)^
1eea0 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61    ^Disable the a
1eeb0 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
1eec0 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
1eed0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
1eee0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
1eef0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
1ef00 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
1ef10 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ef20 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
1ef30 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
1ef40 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
1ef50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ef60 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1ef70 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1ef80 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
1ef90 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
1efa0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1efb0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1efc0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
1efd0 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
1efe0 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
1eff0 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
1f000 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
1f010 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
1f020 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ^When [sqlite3_p
1f030 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
1f040 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
1f050 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
1f060 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
1f070 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72  ght be re-prepar
1f080 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
1f090 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
1f0a0 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
1f0b0 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
1f0c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
1f0d0 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
1f0e0 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
1f0f0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1f100 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
1f110 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
1f120 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1f130 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  ]..**.** ^Note t
1f140 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
1f150 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1f160 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
1f170 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
1f180 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
1f190 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
1f1a0 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
1f1b0 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
1f1c0 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
1f1d0 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
1f1e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75  lite3_step()], u
1f1f0 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74  nless.** as stat
1f200 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ed in the previo
1f210 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71  us paragraph, sq
1f220 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76  lite3_step() inv
1f230 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  okes.** sqlite3_
1f240 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20  prepare_v2() to 
1f250 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74  reprepare a stat
1f260 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63  ement after a sc
1f270 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  hema change..*/.
1f280 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
1f290 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
1f2a0 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
1f2b0 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
1f2c0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1f2d0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1f2e0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1f2f0 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
1f300 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
1f310 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
1f320 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
1f330 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
1f340 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1f350 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
1f360 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1f370 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
1f380 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
1f390 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
1f3a0 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
1f3b0 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
1f3c0 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
1f3d0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1f3e0 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
1f3f0 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
1f400 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
1f410 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
1f420 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
1f430 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
1f440 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
1f450 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ation..**.** Not
1f460 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47  e that SQLITE_IG
1f470 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65  NORE is also use
1f480 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74  d as a [conflict
1f490 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65   resolution mode
1f4a0 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72  ].** returned fr
1f4b0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
1f4c0 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74  vtab_on_conflict
1f4d0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
1f4e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f4f0 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
1f500 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
1f510 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
1f520 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
1f530 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
1f540 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
1f550 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
1f560 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
1f570 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
1f580 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
1f590 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
1f5a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
1f5b0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1f5c0 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
1f5d0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
1f5e0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
1f5f0 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
1f600 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
1f610 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
1f620 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
1f630 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
1f640 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
1f650 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
1f660 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
1f670 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
1f680 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
1f690 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
1f6a0 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
1f6b0 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
1f6c0 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
1f6d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1f6e0 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
1f6f0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
1f700 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
1f710 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
1f720 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
1f730 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
1f740 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
1f750 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
1f760 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1f770 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
1f780 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
1f790 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
1f7a0 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
1f7b0 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
1f7c0 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
1f7d0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1f7e0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54   parameter.  ^(T
1f7f0 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
1f800 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
1f810 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1f820 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1f830 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
1f840 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
1f850 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
1f860 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20  le.)^  ^The 6th 
1f870 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1f880 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1f890 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
1f8a0 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
1f8b0 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
1f8c0 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
1f8d0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
1f8e0 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
1f8f0 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
1f900 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
1f910 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
1f920 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
1f930 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
1f940 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f950 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f960 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
1f970 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
1f980 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
1f990 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1f9a0 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
1f9b0 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
1f9c0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1f9d0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1f9e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1f9f0 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
1fa00 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
1fa10 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1fa20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1fa30 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1fa40 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
1fa50 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
1fa60 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1fa70 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1fa80 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1fa90 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
1faa0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1fab0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1fac0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1fad0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1fae0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
1faf0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1fb00 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1fb10 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1fb20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1fb30 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
1fb40 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1fb50 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1fb60 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1fb70 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
1fb80 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
1fb90 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1fba0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1fbb0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1fbc0 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
1fbd0 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
1fbe0 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1fbf0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1fc00 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1fc10 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
1fc20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
1fc30 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1fc40 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1fc50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1fc60 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
1fc70 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
1fc80 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1fc90 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1fca0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1fcb0 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
1fcc0 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
1fcd0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1fce0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1fcf0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1fd00 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
1fd10 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
1fd20 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1fd30 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1fd40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1fd50 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
1fd60 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
1fd70 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1fd80 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1fd90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1fda0 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
1fdb0 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
1fdc0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1fdd0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1fde0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1fdf0 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
1fe00 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
1fe10 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1fe20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1fe30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1fe40 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
1fe50 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
1fe60 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1fe70 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1fe80 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1fe90 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
1fea0 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
1feb0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1fec0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1fed0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
1fee0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
1fef0 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
1ff00 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1ff10 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1ff20 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
1ff30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
1ff40 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
1ff50 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
1ff60 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
1ff70 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
1ff80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
1ff90 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1ffa0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
1ffb0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1ffc0 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
1ffd0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
1ffe0 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
1fff0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20000 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20010 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
20020 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
20030 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
20040 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
20050 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20060 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
20070 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
20080 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
20090 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
200a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
200b0 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
200c0 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
200d0 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
200e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
200f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20100 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
20110 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
20120 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
20130 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20140 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20150 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
20160 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
20170 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
20180 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20190 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
201a0 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
201b0 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
201c0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
201d0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
201e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
201f0 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
20200 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
20210 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
20220 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20230 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20240 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
20250 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
20260 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
20270 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
20280 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
20290 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
202a0 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
202b0 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
202c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
202d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
202e0 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
202f0 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
20300 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
20310 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
20320 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
20330 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
20340 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
20350 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
20360 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
20370 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
20380 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20390 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
203a0 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69  er used */.#defi
203b0 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53  ne SQLITE_RECURS
203c0 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33  IVE            3
203d0 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  3   /* NULL     
203e0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
203f0 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a         */../*.**
20400 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
20410 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
20420 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
20430 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
20440 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
20450 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  k functions that
20460 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72   can be used for
20470 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20  .** tracing and 
20480 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78  profiling the ex
20490 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73  ecution of SQL s
204a0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
204b0 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
204c0 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
204d0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
204e0 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
204f0 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74   at.** various t
20500 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c  imes when an SQL
20510 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65   statement is be
20520 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69  ing run by [sqli
20530 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
20540 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61  ^The sqlite3_tra
20550 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ce() callback is
20560 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
20570 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20  UTF-8 rendering 
20580 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74  of the.** SQL st
20590 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20  atement text as 
205a0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
205b0 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75  rst begins execu
205c0 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74  ting..** ^(Addit
205d0 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72  ional sqlite3_tr
205e0 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20  ace() callbacks 
205f0 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61  might occur.** a
20600 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64  s each triggered
20610 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65   subprogram is e
20620 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c  ntered.  The cal
20630 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67  lbacks for trigg
20640 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61  ers.** contain a
20650 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65   UTF-8 SQL comme
20660 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  nt that identifi
20670 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29  es the trigger.)
20680 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ^.**.** The [SQL
20690 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c  ITE_TRACE_SIZE_L
206a0 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  IMIT] compile-ti
206b0 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  me option can be
206c0 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a   used to limit.*
206d0 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  * the length of 
206e0 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  [bound parameter
206f0 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74  ] expansion in t
20700 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c  he output of sql
20710 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a  ite3_trace()..**
20720 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
20730 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
20740 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
20750 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
20760 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
20770 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
20780 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70  inishes.  ^The p
20790 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
207a0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
207b0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
207c0 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
207d0 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
207e0 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
207f0 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
20800 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
20810 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66   run.  ^The prof
20820 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ile callback.** 
20830 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73  time is in units
20840 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c   of nanoseconds,
20850 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72   however the cur
20860 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
20870 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63  ion.** is only c
20880 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73  apable of millis
20890 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e  econd resolution
208a0 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73   so the six leas
208b0 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a  t significant.**
208c0 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74   digits in the t
208d0 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c  ime are meaningl
208e0 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72  ess.  Future ver
208f0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a  sions of SQLite.
20900 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65  ** might provide
20910 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74   greater resolut
20920 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69  ion on the profi
20930 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54  ler callback.  T
20940 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  he.** sqlite3_pr
20950 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  ofile() function
20960 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65   is considered e
20970 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
20980 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f  is.** subject to
20990 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
209a0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
209b0 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  Lite..*/.void *s
209c0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
209d0 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
209e0 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
209f0 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
20a00 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
20a10 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74  NTAL void *sqlit
20a20 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
20a30 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
20a40 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
20a50 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
20a60 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
20a70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20a80 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
20a90 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  ss Callbacks.**.
20aa0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
20ab0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
20ac0 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,N,X,P) interf
20ad0 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63  ace causes the c
20ae0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
20af0 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f  ion X to be invo
20b00 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
20b10 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
20b20 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
20b30 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
20b40 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
20b50 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
20b60 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f  _get_table()] fo
20b70 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
20b80 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20  nnection D.  An 
20b90 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
20ba0 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
20bb0 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
20bc0 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
20bd0 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
20be0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61  .**.** ^The para
20bf0 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65  meter P is passe
20c00 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
20c10 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
20c20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62  to the .** callb
20c30 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20  ack function X. 
20c40 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
20c50 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69  N is the approxi
20c60 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a  mate number of .
20c70 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68  ** [virtual mach
20c80 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73  ine instructions
20c90 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75  ] that are evalu
20ca0 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63  ated between suc
20cb0 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63  cessive.** invoc
20cc0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61  ations of the ca
20cd0 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e  llback X.  ^If N
20ce0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e   is less than on
20cf0 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72  e then the progr
20d00 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69  ess.** handler i
20d10 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  s disabled..**.*
20d20 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  * ^Only a single
20d30 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
20d40 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64  r may be defined
20d50 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72   at one time per
20d60 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
20d70 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69  nnection]; setti
20d80 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73  ng a new progres
20d90 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c  s handler cancel
20da0 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65  s the.** old one
20db0 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61  .  ^Setting para
20dc0 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20  meter X to NULL 
20dd0 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f  disables the pro
20de0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
20df0 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20  * ^The progress 
20e00 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20  handler is also 
20e10 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74  disabled by sett
20e20 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65  ing N to a value
20e30 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e   less.** than 1.
20e40 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  .**.** ^If the p
20e50 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
20e60 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
20e70 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  o, the operation
20e80 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
20e90 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
20ea0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
20eb0 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
20ec0 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
20ed0 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73  on a GUI progres
20ee0 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  s dialog box..**
20ef0 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
20f00 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
20f10 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
20f20 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
20f30 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
20f40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20f50 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
20f60 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
20f70 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
20f80 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
20f90 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
20fa0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
20fb0 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
20fc0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
20fd0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
20fe0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
20ff0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
21000 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f  agraph..**.*/.vo
21010 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
21020 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
21030 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
21040 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
21050 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
21060 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
21070 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
21080 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  tion.**.** ^Thes
21090 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
210a0 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
210b0 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69  se file as speci
210c0 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
210d0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
210e0 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
210f0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
21100 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
21110 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
21120 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
21130 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
21140 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
21150 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
21160 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
21170 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
21180 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
21190 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
211a0 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
211b0 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
211c0 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
211d0 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
211e0 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
211f0 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
21200 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
21210 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
21220 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
21230 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
21240 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
21250 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
21260 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
21270 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
21280 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
21290 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
212a0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
212b0 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
212c0 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
212d0 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
212e0 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
212f0 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
21300 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
21310 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
21320 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
21330 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
21340 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
21350 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
21360 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
21370 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
21380 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
21390 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
213a0 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
213b0 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
213c0 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
213d0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
213e0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
213f0 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55  coding will be U
21400 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73  TF-8 for databas
21410 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  es created using
21420 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
21430 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
21440 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64  en_v2().  ^The d
21450 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
21460 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a  for databases.**
21470 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 73   created using s
21480 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
21490 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69  will be UTF-16 i
214a0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
214b0 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57  e order..**.** W
214c0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
214d0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
214e0 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
214f0 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
21500 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
21510 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
21520 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
21530 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
21540 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
21550 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
21560 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
21570 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
21580 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
21590 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
215a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
215b0 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
215c0 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
215d0 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
215e0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
215f0 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
21600 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
21610 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
21620 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
21630 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c  ction.  ^(The fl
21640 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
21650 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
21660 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f  _v2() can take o
21670 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  ne of.** the fol
21680 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c  lowing three val
21690 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  ues, optionally 
216a0 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68  combined with th
216b0 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  e .** [SQLITE_OP
216c0 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51  EN_NOMUTEX], [SQ
216d0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
216e0 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
216f0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c  EN_SHAREDCACHE],
21700 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
21710 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20  _PRIVATECACHE], 
21720 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  and/or [SQLITE_O
21730 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29  PEN_URI] flags:)
21740 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ^.**.** <dl>.** 
21750 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
21760 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
21770 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
21780 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
21790 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
217a0 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
217b0 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
217c0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
217d0 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
217e0 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
217f0 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
21800 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c  OPEN_READWRITE]<
21810 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
21820 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
21830 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
21840 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
21850 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69  ssible, or readi
21860 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68  ng.** only if th
21870 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20  e file is write 
21880 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
21890 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
218a0 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a  m.  In either.**
218b0 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
218c0 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20  se must already 
218d0 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65  exist, otherwise
218e0 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
218f0 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
21900 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
21910 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
21920 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
21930 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
21940 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
21950 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
21960 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
21970 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
21980 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65  ted if.** it doe
21990 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78  s not already ex
219a0 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65  ist. This is the
219b0 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69   behavior that i
219c0 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f  s always used fo
219d0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
219e0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
219f0 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e  open16().</dd>)^
21a00 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
21a10 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
21a20 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
21a30 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
21a40 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
21a50 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
21a60 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c  n above optional
21a70 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
21a80 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54   other.** [SQLIT
21a90 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
21aa0 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20  | SQLITE_OPEN_* 
21ab0 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  bits].** then th
21ac0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
21ad0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
21ae0 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  If the [SQLITE_O
21af0 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
21b00 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74  g is set, then t
21b10 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
21b20 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20  ection.** opens 
21b30 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72  in the multi-thr
21b40 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
21b50 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20  ode] as long as 
21b60 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  the single-threa
21b70 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f  d.** mode has no
21b80 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f  t been set at co
21b90 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
21ba0 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74  art-time.  ^If t
21bb0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
21bc0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
21bd0 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74  ag is set then t
21be0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
21bf0 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20  ection opens.** 
21c00 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  in the serialize
21c10 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
21c20 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65  e] unless single
21c30 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70  -thread was.** p
21c40 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74  reviously select
21c50 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ed at compile-ti
21c60 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
21c70 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
21c80 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
21c90 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
21ca0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
21cb0 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  nection to be.**
21cc0 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65   eligible to use
21cd0 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
21ce0 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73  ode], regardless
21cf0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
21d00 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  ot shared.** cac
21d10 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73  he is enabled us
21d20 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  ing [sqlite3_ena
21d30 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
21d40 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53  ()].  ^The.** [S
21d50 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
21d60 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  TECACHE] flag ca
21d70 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
21d80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
21d90 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61  not.** participa
21da0 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61  te in [shared ca
21db0 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69  che mode] even i
21dc0 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e  f it is enabled.
21dd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
21de0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
21df0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21e00 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ) is the name of
21e10 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
21e20 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  _vfs] object tha
21e30 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70  t defines the op
21e40 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
21e50 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a  nterface that.**
21e60 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
21e70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
21e80 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68  uld use.  ^If th
21e90 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
21ea0 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  er is.** a NULL 
21eb0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
21ec0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
21ed0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
21ee0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   used..**.** ^If
21ef0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
21f00 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
21f10 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
21f20 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
21f30 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
21f40 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
21f50 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68  connection.  ^Th
21f60 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  is in-memory dat
21f70 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73  abase will vanis
21f80 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61  h when.** the da
21f90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21fa0 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75  n is closed.  Fu
21fb0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
21fc0 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a   SQLite might.**
21fd0 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64   make use of add
21fe0 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20  itional special 
21ff0 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62  filenames that b
22000 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
22010 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  " character..** 
22020 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  It is recommende
22030 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61  d that when a da
22040 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
22050 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65  actually does be
22060 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a  gin with.** a ":
22070 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20  " character you 
22080 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68  should prefix th
22090 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20  e filename with 
220a0 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20  a pathname such 
220b0 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76  as.** "./" to av
220c0 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a  oid ambiguity..*
220d0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
220e0 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
220f0 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
22100 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
22110 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
22120 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
22130 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20  created.  ^This 
22140 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
22150 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
22160 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
22170 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
22180 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
22190 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
221a0 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
221b0 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33  names in sqlite3
221c0 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52  _open()]] <h3>UR
221d0 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e  I Filenames</h3>
221e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20  .**.** ^If [URI 
221f0 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70  filename] interp
22200 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
22210 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c  led, and the fil
22220 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
22230 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66  * begins with "f
22240 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20  ile:", then the 
22250 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65  filename is inte
22260 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49  rpreted as a URI
22270 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61  . ^URI.** filena
22280 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
22290 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  n is enabled if 
222a0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
222b0 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a  _URI] flag is.**
222c0 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72   set in the four
222d0 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
222e0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
222f0 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a  , or if it has.*
22300 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67  * been enabled g
22310 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68  lobally using th
22320 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
22330 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74  _URI] option wit
22340 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  h the.** [sqlite
22350 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68  3_config()] meth
22360 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51  od or by the [SQ
22370 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f  LITE_USE_URI] co
22380 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
22390 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69  n..** As of SQLi
223a0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37  te version 3.7.7
223b0 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69  , URI filename i
223c0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
223d0 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62   turned off.** b
223e0 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66  y default, but f
223f0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
22400 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65  f SQLite might e
22410 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61  nable URI filena
22420 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61  me.** interpreta
22430 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  tion by default.
22440 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65    See "[URI file
22450 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69  names]" for addi
22460 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
22470 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49  ation..**.** URI
22480 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70   filenames are p
22490 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20  arsed according 
224a0 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66  to RFC 3986. ^If
224b0 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e   the URI contain
224c0 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74  s an.** authorit
224d0 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20  y, then it must 
224e0 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70  be either an emp
224f0 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65  ty string or the
22500 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63   string .** "loc
22510 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65  alhost". ^If the
22520 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f   authority is no
22530 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  t an empty strin
22540 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22  g or "localhost"
22550 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69  , an .** error i
22560 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68  s returned to th
22570 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66  e caller. ^The f
22580 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e  ragment componen
22590 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a  t of a URI, if .
225a0 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69  ** present, is i
225b0 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  gnored..**.** ^S
225c0 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70  QLite uses the p
225d0 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ath component of
225e0 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20   the URI as the 
225f0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b  name of the disk
22600 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63   file.** which c
22610 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61  ontains the data
22620 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61  base. ^If the pa
22630 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  th begins with a
22640 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20   '/' character, 
22650 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69  .** then it is i
22660 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e  nterpreted as an
22670 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20   absolute path. 
22680 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65  ^If the path doe
22690 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20  s not begin .** 
226a0 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e  with a '/' (mean
226b0 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74  ing that the aut
226c0 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69  hority section i
226d0 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
226e0 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20  he URI).** then 
226f0 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65  the path is inte
22700 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c  rpreted as a rel
22710 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20  ative path. .** 
22720 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68  ^(On windows, th
22730 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e  e first componen
22740 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65  t of an absolute
22750 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64   path .** is a d
22760 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69  rive specificati
22770 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29  on (e.g. "C:").)
22780 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55  ^.**.** [[core U
22790 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  RI query paramet
227a0 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65  ers]].** The que
227b0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
227c0 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69  a URI may contai
227d0 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
227e0 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  t are interprete
227f0 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53  d.** either by S
22800 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72  QLite itself, or
22810 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73   by a [VFS | cus
22820 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  tom VFS implemen
22830 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69  tation]..** SQLi
22840 74 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74  te and its built
22850 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65  -in [VFSes] inte
22860 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c  rpret the.** fol
22870 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72  lowing query par
22880 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ameters:.**.** <
22890 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  ul>.**   <li> <b
228a0 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22  >vfs</b>: ^The "
228b0 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d  vfs" parameter m
228c0 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70  ay be used to sp
228d0 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f  ecify the name o
228e0 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f  f.**     a VFS o
228f0 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69  bject that provi
22900 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  des the operatin
22910 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
22920 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a  ce that should.*
22930 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f  *     be used to
22940 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
22950 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73  base file on dis
22960 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69  k. ^If this opti
22970 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20  on is set to.** 
22980 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72      an empty str
22990 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20  ing the default 
229a0 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73  VFS object is us
229b0 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20  ed. ^Specifying 
229c0 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20  an unknown.**   
229d0 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f    VFS is an erro
229e0 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f  r. ^If sqlite3_o
229f0 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
22a00 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74   and the vfs opt
22a10 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72  ion is.**     pr
22a20 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20  esent, then the 
22a30 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79  VFS specified by
22a40 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65   the option take
22a50 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65  s precedence ove
22a60 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c  r.**     the val
22a70 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
22a80 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
22a90 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
22aa0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
22ab0 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e  <li> <b>mode</b>
22ac0 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72  : ^(The mode par
22ad0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
22ae0 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22  t to either "ro"
22af0 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22  , "rw",.**     "
22b00 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79  rwc", or "memory
22b10 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f  ". Attempting to
22b20 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f   set it to any o
22b30 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a  ther value is.**
22b40 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e       an error)^.
22b50 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f   .**     ^If "ro
22b60 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20  " is specified, 
22b70 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
22b80 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
22b90 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20  read-only .**   
22ba0 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61    access, just a
22bb0 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  s if the [SQLITE
22bc0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20  _OPEN_READONLY] 
22bd0 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65  flag had been se
22be0 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20  t in the .**    
22bf0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
22c00 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
22c10 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f  v2(). ^If the mo
22c20 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  de option is set
22c30 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22   to .**     "rw"
22c40 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
22c50 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
22c60 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75  r read-write (bu
22c70 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a  t not create) .*
22c80 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73  *     access, as
22c90 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   if SQLITE_OPEN_
22ca0 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e  READWRITE (but n
22cb0 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ot SQLITE_OPEN_C
22cc0 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20  REATE) had .**  
22cd0 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61     been set. ^Va
22ce0 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75  lue "rwc" is equ
22cf0 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
22d00 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20  ng both .**     
22d10 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
22d20 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45  WRITE and SQLITE
22d30 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e  _OPEN_CREATE.  ^
22d40 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
22d50 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74  on is.**     set
22d60 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65   to "memory" the
22d70 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d  n a pure [in-mem
22d80 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68  ory database] th
22d90 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a  at never reads.*
22da0 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20  *     or writes 
22db0 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65  from disk is use
22dc0 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72  d. ^It is an err
22dd0 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20  or to specify a 
22de0 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20  value for.**    
22df0 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65   the mode parame
22e00 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73  ter that is less
22e10 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61   restrictive tha
22e20 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64  n that specified
22e30 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66   by.**     the f
22e40 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74  lags passed in t
22e50 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
22e60 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
22e70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
22e80 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f   <li> <b>cache</
22e90 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70  b>: ^The cache p
22ea0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
22eb0 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73  set to either "s
22ec0 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20  hared" or.**    
22ed0 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74   "private". ^Set
22ee0 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72  ting it to "shar
22ef0 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ed" is equivalen
22f00 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
22f10 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
22f20 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
22f30 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73  bit in the flags
22f40 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
22f50 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74   to.**     sqlit
22f60 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53  e3_open_v2(). ^S
22f70 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65  etting the cache
22f80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70   parameter to "p
22f90 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20  rivate" is .**  
22fa0 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f     equivalent to
22fb0 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c   setting the SQL
22fc0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
22fd0 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20  CACHE bit..**   
22fe0 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70    ^If sqlite3_op
22ff0 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
23000 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20  and the "cache" 
23010 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65  parameter is pre
23020 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61  sent in.**     a
23030 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69   URI filename, i
23040 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64  ts value overrid
23050 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20  es any behavior 
23060 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74  requested by set
23070 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49  ting.**     SQLI
23080 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
23090 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f  ACHE or SQLITE_O
230a0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
230b0 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  flag..**.**  <li
230c0 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e  > <b>psow</b>: ^
230d0 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74  The psow paramet
230e0 65 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65  er indicates whe
230f0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a  ther or not the.
23100 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66  **     [powersaf
23110 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f  e overwrite] pro
23120 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f  perty does or do
23130 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20  es not apply to 
23140 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61  the.**     stora
23150 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63  ge media on whic
23160 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  h the database f
23170 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a  ile resides..**.
23180 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f  **  <li> <b>nolo
23190 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c  ck</b>: ^The nol
231a0 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ock parameter is
231b0 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
231c0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
231d0 20 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64    which if set d
231e0 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63  isables file loc
231f0 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b  king in rollback
23200 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20   journal modes. 
23210 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20   This.**     is 
23220 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73  useful for acces
23230 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20  sing a database 
23240 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20  on a filesystem 
23250 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  that does not.**
23260 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63       support loc
23270 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20  king.  Caution: 
23280 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   Database corrup
23290 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c  tion might resul
232a0 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20  t if two.**     
232b0 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65  or more processe
232c0 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73  s write to the s
232d0 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  ame database and
232e0 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73   any one of thos
232f0 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73  e.**     process
23300 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31  es uses nolock=1
23310 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
23320 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20  >immutable</b>: 
23330 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70  ^The immutable p
23340 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f  arameter is a bo
23350 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20  olean query.**  
23360 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61     parameter tha
23370 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  t indicates that
23380 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
23390 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a  le is stored on.
233a0 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79  **     read-only
233b0 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69   media.  ^When i
233c0 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c  mmutable is set,
233d0 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
233e0 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20  that the.**     
233f0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61  database file ca
23400 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c  nnot be changed,
23410 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65   even by a proce
23420 73 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a  ss with higher.*
23430 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c  *     privilege,
23440 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61   and so the data
23450 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72  base is opened r
23460 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c  ead-only and all
23470 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20   locking.**     
23480 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63  and change detec
23490 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64  tion is disabled
234a0 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74  .  Caution: Sett
234b0 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c  ing the immutabl
234c0 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74  e.**     propert
234d0 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  y on a database 
234e0 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69  file that does i
234f0 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61  n fact change ca
23500 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20  n result.**     
23510 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65  in incorrect que
23520 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f  ry results and/o
23530 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  r [SQLITE_CORRUP
23540 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20  T] errors..**   
23550 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c    See also: [SQL
23560 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
23570 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a  BLE]..**       .
23580 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
23590 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
235a0 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20  known parameter 
235b0 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d  in the query com
235c0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
235d0 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72  is not an.** err
235e0 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  or.  Future vers
235f0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
23600 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20  ight understand 
23610 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79  additional query
23620 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
23630 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72   See "[query par
23640 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65  ameters with spe
23650 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20  cial meaning to 
23660 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20  SQLite]" for.** 
23670 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
23680 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  mation..**.** [[
23690 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
236a0 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20  mples]] <h3>URI 
236b0 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
236c0 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61  s</h3>.**.** <ta
236d0 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61  ble border="1" a
236e0 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c  lign=center cell
236f0 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74  padding=5>.** <t
23700 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e  r><th> URI filen
23710 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74  ames <th> Result
23720 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  s.** <tr><td> fi
23730 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  le:data.db <td> 
23740 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
23750 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
23760 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
23770 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ent directory..*
23780 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
23790 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
237a0 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20  db<br>.**       
237b0 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f     file:///home/
237c0 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
237d0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
237e0 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f  ile://localhost/
237f0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
23800 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20  b <br> <td> .** 
23810 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
23820 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
23830 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
23840 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  .db"..** <tr><td
23850 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61  > file://darksta
23860 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  r/home/fred/data
23870 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
23880 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
23890 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f  "darkstar" is no
238a0 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61  t a recognized a
238b0 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72  uthority..** <tr
238c0 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74  ><td style="whit
238d0 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e  e-space:nowrap">
238e0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
238f0 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e  le:///C:/Documen
23900 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69  ts%20and%20Setti
23910 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70  ngs/fred/Desktop
23920 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20  /data.db.**     
23930 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c  <td> Windows onl
23940 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65  y: Open the file
23950 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72   "data.db" on fr
23960 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20  ed's desktop on 
23970 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  drive.**        
23980 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20    C:. Note that 
23990 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67  the %20 escaping
239a0 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65   in this example
239b0 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79   is not strictly
239c0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65   .**          ne
239d0 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20  cessary - space 
239e0 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62  characters can b
239f0 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79  e used literally
23a00 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
23a10 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a  URI filenames..*
23a20 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
23a30 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26  data.db?mode=ro&
23a40 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74  cache=private <t
23a50 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
23a60 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e  Open file "data.
23a70 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
23a80 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72  nt directory for
23a90 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73   read-only acces
23aa0 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52  s..**          R
23ab0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
23ac0 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
23ad0 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73  ed-cache mode is
23ae0 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20   enabled by.**  
23af0 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c          default,
23b00 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63   use a private c
23b10 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ache..** <tr><td
23b20 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
23b30 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e  d/data.db?vfs=un
23b40 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a  ix-dotfile <td>.
23b50 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
23b60 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
23b70 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20  d/data.db". Use 
23b80 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
23b90 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a  "unix-dotfile".*
23ba0 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
23bb0 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69  uses dot-files i
23bc0 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78  n place of posix
23bd0 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e   advisory lockin
23be0 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  g..** <tr><td> f
23bf0 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
23c00 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a  =readonly <td> .
23c10 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
23c20 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22  rror. "readonly"
23c30 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20   is not a valid 
23c40 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22  option for the "
23c50 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e  mode" parameter.
23c60 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a  .** </table>.**.
23c70 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69  ** ^URI hexadeci
23c80 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
23c90 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73  nces (%HH) are s
23ca0 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20  upported within 
23cb0 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20  the path and.** 
23cc0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
23cd0 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78   of a URI. A hex
23ce0 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
23cf0 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74  sequence consist
23d00 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e  s of a.** percen
23d10 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66  t sign - "%" - f
23d20 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74  ollowed by exact
23d30 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d  ly two hexadecim
23d40 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70  al digits .** sp
23d50 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65  ecifying an octe
23d60 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65  t value. ^Before
23d70 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65   the path or que
23d80 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
23d90 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61   a.** URI filena
23da0 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  me are interpret
23db0 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63  ed, they are enc
23dc0 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
23dd0 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78   and all .** hex
23de0 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
23df0 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63  sequences replac
23e00 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62  ed by a single b
23e10 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  yte containing t
23e20 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64  he.** correspond
23e30 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68  ing octet. If th
23e40 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72  is process gener
23e50 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20  ates an invalid 
23e60 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a  UTF-8 encoding,.
23e70 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ** the results a
23e80 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
23e90 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
23ea0 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
23eb0 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
23ec0 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
23ed0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
23ee0 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
23ef0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
23f00 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
23f10 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
23f20 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
23f30 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
23f40 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
23f50 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
23f60 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
23f70 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
23f80 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
23f90 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
23fa0 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
23fb0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
23fc0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
23fd0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62  n_v2()..**.** <b
23fe0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
23ff0 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c   Runtime users:<
24000 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61  /b>  The tempora
24010 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73  ry directory mus
24020 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f  t be set.** prio
24030 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c  r to calling sql
24040 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
24050 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
24060 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61  .  Otherwise, va
24070 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65  rious.** feature
24080 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74  s that require t
24090 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72  he use of tempor
240a0 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61  ary files may fa
240b0 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  il..**.** See al
240c0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d  so: [sqlite3_tem
240d0 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a  p_directory].*/.
240e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
240f0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
24100 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
24110 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
24120 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
24130 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
24140 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
24150 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
24160 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
24170 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
24180 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
24190 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
241a0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
241b0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
241c0 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
241d0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
241e0 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
241f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
24200 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
24210 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
24220 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
24230 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
24240 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
24250 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
24260 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
24270 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
24280 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
24290 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
242a0 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
242b0 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
242c0 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
242d0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
242e0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
242f0 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
24300 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  meters.**.** The
24310 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72  se are utility r
24320 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20  outines, useful 
24330 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
24340 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
24350 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ck.** to see if 
24360 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
24370 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
24380 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
24390 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
243a0 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
243b0 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
243c0 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65  alue of that que
243d0 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
243e0 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20  .** If F is the 
243f0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
24400 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  e pointer passed
24410 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28   into the xOpen(
24420 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20  ) method of .** 
24430 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  a VFS implementa
24440 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c  tion when the fl
24450 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
24460 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65   xOpen() has one
24470 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20   or .** more of 
24480 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
24490 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _URI] or [SQLITE
244a0 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62  _OPEN_MAIN_DB] b
244b0 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50  its set and.** P
244c0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
244d0 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  the query parame
244e0 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  ter, then.** sql
244f0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
24500 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
24510 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
24520 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20   P.** parameter 
24530 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20  if it exists or 
24540 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
24550 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  f P does not app
24560 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65  ear as a .** que
24570 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ry parameter on 
24580 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75  F.  If P is a qu
24590 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  ery parameter of
245a0 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70   F.** has no exp
245b0 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65  licit value, the
245c0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
245d0 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
245e0 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  urns.** a pointe
245f0 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  r to an empty st
24600 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
24610 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
24620 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
24630 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ne assumes that 
24640 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a  P is a boolean.*
24650 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  * parameter and 
24660 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
24670 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63   or false (0) ac
24680 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76  cording to the v
24690 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54  alue.** of P.  T
246a0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
246b0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
246c0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72  utine returns tr
246d0 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a  ue (1) if the.**
246e0 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20   value of query 
246f0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
24700 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72  ne of "yes", "tr
24710 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20  ue", or "on" in 
24720 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69  any.** case or i
24730 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
24740 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  ns with a non-ze
24750 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  ro number.  The 
24760 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
24770 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
24780 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
24790 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65  false (0) if the
247a0 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65   value of.** que
247b0 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
247c0 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22  s one of "no", "
247d0 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22  false", or "off"
247e0 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a   in any case or.
247f0 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ** if the value 
24800 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75  begins with a nu
24810 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20  meric zero.  If 
24820 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79  P is not a query
24830 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  .** parameter on
24840 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c   F or if the val
24850 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20  ue of P is does 
24860 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66  not match any of
24870 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74   the.** above, t
24880 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
24890 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
248a0 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a  eturns (B!=0)..*
248b0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
248c0 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44  _uri_int64(F,P,D
248d0 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72  ) routine conver
248e0 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ts the value of 
248f0 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62  P into a.** 64-b
24900 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
24910 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68  r and returns th
24920 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44  at integer, or D
24930 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a   if P does not.*
24940 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65  * exist.  If the
24950 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73   value of P is s
24960 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
24970 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20  han an integer, 
24980 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20  then.** zero is 
24990 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  returned..** .**
249a0 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20   If F is a NULL 
249b0 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71  pointer, then sq
249c0 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
249d0 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
249e0 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c   NULL and.** sql
249f0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
24a00 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
24a10 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20  B.  If F is not 
24a20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
24a30 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64  nd.** is not a d
24a40 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74  atabase file pat
24a50 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68  hname pointer th
24a60 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64  at SQLite passed
24a70 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a   into the xOpen.
24a80 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74  ** VFS method, t
24a90 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
24aa0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
24ab0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
24ac0 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e  d probably.** un
24ad0 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f  desirable..*/.co
24ae0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
24af0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
24b00 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
24b10 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61  ename, const cha
24b20 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20  r *zParam);.int 
24b30 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
24b40 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ean(const char *
24b50 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61  zFile, const cha
24b60 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62  r *zParam, int b
24b70 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65  Default);.sqlite
24b80 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
24b90 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20  uri_int64(const 
24ba0 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61  char*, const cha
24bb0 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
24bc0 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  4);.../*.** CAPI
24bd0 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
24be0 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
24bf0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
24c00 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33  t recent sqlite3
24c10 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f  _* API call asso
24c20 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20  ciated with .** 
24c30 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
24c40 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20  tion] D failed, 
24c50 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
24c60 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65  _errcode(D) inte
24c70 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73  rface.** returns
24c80 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65   the numeric [re
24c90 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65  sult code] or [e
24ca0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
24cb0 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a  ode] for that.**
24cc0 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66   API call..** If
24cd0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
24ce0 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20 73 75   API call was su
24cf0 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 65  ccessful,.** the
24d00 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
24d10 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
24d20 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64  errcode() is und
24d30 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  efined..** ^The 
24d40 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
24d50 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
24d60 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
24d70 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
24d80 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
24d90 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
24da0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
24db0 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
24dc0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
24dd0 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
24de0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
24df0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
24e00 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
24e10 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
24e20 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
24e30 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
24e40 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
24e50 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
24e60 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
24e70 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  ively..** ^(Memo
24e80 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
24e90 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
24ea0 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
24eb0 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
24ec0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
24ed0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
24ee0 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
24ef0 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
24f00 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
24f10 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
24f20 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
24f30 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
24f40 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
24f50 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
24f60 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
24f70 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a   functions.)^.**
24f80 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
24f90 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66  _errstr() interf
24fa0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
24fb0 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
24fc0 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65   text.** that de
24fd0 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73  scribes the [res
24fe0 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54  ult code], as UT
24ff0 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  F-8..** ^(Memory
25000 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
25010 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
25020 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
25030 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d  ernally.** and m
25040 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64  ust not be freed
25050 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
25060 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ion)^..**.** Whe
25070 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
25080 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
25090 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20  ] is in use, it 
250a0 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20  might be the.** 
250b0 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f  case that a seco
250c0 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  nd error occurs 
250d0 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68  on a separate th
250e0 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a  read in between.
250f0 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74  ** the time of t
25100 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61  he first error a
25110 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  nd the call to t
25120 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e  hese interfaces.
25130 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61  .** When that ha
25140 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e  ppens, the secon
25150 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  d error will be 
25160 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74  reported since t
25170 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hese.** interfac
25180 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74  es always report
25190 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
251a0 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f   result.  To avo
251b0 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68  id.** this, each
251c0 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61   thread can obta
251d0 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65  in exclusive use
251e0 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
251f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
25200 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b  ** by invoking [
25210 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
25220 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ter]([sqlite3_db
25230 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f  _mutex](D)) befo
25240 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  re beginning.** 
25250 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76  to use D and inv
25260 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
25270 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c  utex_leave]([sql
25280 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
25290 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20  )) after.** all 
252a0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74  calls to the int
252b0 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68  erfaces listed h
252c0 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65  ere are complete
252d0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  d..**.** If an i
252e0 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
252f0 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
25300 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
25310 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
25320 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
25330 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
25340 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
25350 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
25360 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
25370 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
25380 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
25390 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
253a0 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
253b0 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  b);.int sqlite3_
253c0 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
253d0 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63  (sqlite3 *db);.c
253e0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
253f0 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
25400 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  3*);.const void 
25410 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
25420 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  6(sqlite3*);.con
25430 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
25440 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f  _errstr(int);../
25450 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
25460 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
25470 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
25480 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
25490 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
254a0 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
254b0 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
254c0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
254d0 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
254e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
254f0 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
25500 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
25510 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
25520 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
25530 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
25540 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
25550 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
25560 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
25570 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
25580 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
25590 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
255a0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
255b0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
255c0 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
255d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
255e0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
255f0 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
25600 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
25610 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
25620 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
25630 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
25640 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
25650 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
25660 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
25670 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
25680 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
25690 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
256a0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
256b0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
256c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
256d0 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
256e0 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
256f0 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
25700 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
25710 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
25720 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
25730 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
25740 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
25750 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
25760 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
25770 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
25780 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
25790 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
257a0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
257b0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
257c0 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
257d0 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
257e0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
257f0 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a  ime Limits.**.**
25800 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
25810 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
25820 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
25830 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
25840 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
25850 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
25860 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
25870 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
25880 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
25890 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
258a0 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
258b0 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
258c0 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
258d0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
258e0 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
258f0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
25900 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
25910 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
25920 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
25930 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
25940 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
25950 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
25960 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
25970 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
25980 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
25990 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
259a0 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
259b0 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
259c0 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
259d0 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
259e0 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
259f0 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
25a00 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
25a10 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
25a20 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
25a30 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
25a40 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
25a50 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
25a60 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
25a70 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
25a80 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
25a90 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
25aa0 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
25ab0 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
25ac0 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
25ad0 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
25ae0 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
25af0 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
25b00 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
25b10 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
25b20 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
25b30 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
25b40 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
25b50 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
25b60 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
25b70 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
25b80 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
25b90 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
25ba0 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
25bb0 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
25bc0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
25bd0 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
25be0 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
25bf0 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
25c00 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
25c10 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
25c20 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
25c30 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
25c40 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
25c50 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
25c60 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
25c70 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
25c80 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
25c90 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
25ca0 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
25cb0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
25cc0 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
25cd0 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
25ce0 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
25cf0 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
25d00 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
25d10 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
25d20 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
25d30 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
25d40 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
25d50 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
25d60 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
25d70 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
25d80 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
25d90 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
25da0 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
25db0 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
25dc0 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
25dd0 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
25de0 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
25df0 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
25e00 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
25e10 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
25e20 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
25e30 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
25e40 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
25e50 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
25e60 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
25e70 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
25e80 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
25e90 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
25ea0 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
25eb0 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
25ec0 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
25ed0 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
25ee0 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
25ef0 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
25f00 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
25f10 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
25f20 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
25f30 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
25f40 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
25f50 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
25f60 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
25f70 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
25f80 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
25f90 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ses..*/.int sqli
25fa0 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
25fb0 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
25fc0 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
25fd0 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
25fe0 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
25ff0 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ies.** KEYWORDS:
26000 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79   {limit category
26010 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f  } {*limit catego
26020 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
26030 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
26040 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f  ne various perfo
26050 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a  rmance limits.**
26060 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77   that can be low
26070 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  ered at run-time
26080 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
26090 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
260a0 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65   synopsis of the
260b0 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
260c0 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
260d0 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  is shown below..
260e0 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** Additional in
260f0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61  formation is ava
26100 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74  ilable at [limit
26110 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51  s | Limits in SQ
26120 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  Lite]..**.** <dl
26130 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  >.** [[SQLITE_LI
26140 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  MIT_LENGTH]] ^(<
26150 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26160 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
26170 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
26180 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
26190 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
261a0 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73  le row, in bytes
261b0 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  .<dd>)^.**.** [[
261c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
261d0 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
261e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
261f0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
26200 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
26210 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
26220 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
26230 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
26240 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
26250 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74  T_COLUMN]] ^(<dt
26260 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
26270 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
26280 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
26290 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
262a0 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
262b0 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
262c0 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
262d0 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
262e0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
262f0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
26300 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
26310 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
26320 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
26330 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
26340 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
26350 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
26360 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
26370 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
26380 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
26390 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
263a0 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
263b0 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29  xpression.</dd>)
263c0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
263d0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
263e0 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53  SELECT]] ^(<dt>S
263f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
26400 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
26410 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26420 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
26430 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
26440 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
26450 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
26460 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
26470 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e  VDBE_OP]] ^(<dt>
26480 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
26490 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
264a0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
264b0 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
264c0 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
264d0 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
264e0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
264f0 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
26500 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69  tement.  This li
26510 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65  mit is not curre
26520 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64  ntly.** enforced
26530 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69  , though that mi
26540 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20  ght be added in 
26550 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
26560 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
26570 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
26580 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
26590 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c  NCTION_ARG]] ^(<
265a0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
265b0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74  FUNCTION_ARG</dt
265c0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
265d0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
265e0 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75  rguments on a fu
265f0 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  nction.</dd>)^.*
26600 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
26610 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e  MIT_ATTACHED]] ^
26620 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
26630 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
26640 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
26650 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54  um number of [AT
26660 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20  TACH | attached 
26670 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64  databases].)^</d
26680 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
26690 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
266a0 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a  TERN_LENGTH]].**
266b0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
266c0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
266d0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
266e0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
266f0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
26700 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
26710 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a  o the [LIKE] or.
26720 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  ** [GLOB] operat
26730 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ors.</dd>)^.**.*
26740 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
26750 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
26760 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
26770 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
26780 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
26790 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
267a0 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66   index number of
267b0 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d   any [parameter]
267c0 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
267d0 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ment.)^.**.** [[
267e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
267f0 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  GGER_DEPTH]] ^(<
26800 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26810 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64  TRIGGER_DEPTH</d
26820 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
26830 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72  ximum depth of r
26840 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69  ecursion for tri
26850 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ggers.</dd>)^.**
26860 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
26870 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
26880 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  S]] ^(<dt>SQLITE
26890 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
268a0 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  READS</dt>.** <d
268b0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
268c0 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72  mber of auxiliar
268d0 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73  y worker threads
268e0 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a   that a single.*
268f0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
26900 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74  ement] may start
26910 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
26920 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
26930 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
26940 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
26950 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
26960 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
26970 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
26980 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
26990 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
269a0 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
269b0 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
269c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
269d0 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
269e0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
269f0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
26a00 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
26a10 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
26a20 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
26a30 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
26a40 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
26a50 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
26a60 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
26a70 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
26a80 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
26a90 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
26aa0 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
26ab0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
26ac0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
26ad0 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
26ae0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
26af0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
26b00 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
26b10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
26b20 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
26b30 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
26b40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
26b50 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
26b60 41 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31  ADS           11
26b70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26b80 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
26b90 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
26ba0 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
26bb0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
26bc0 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
26bd0 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
26be0 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
26bf0 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
26c00 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
26c10 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
26c20 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
26c30 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
26c40 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
26c50 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
26c60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
26c70 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
26c80 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
26c90 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
26ca0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
26cb0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
26cc0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
26cd0 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
26ce0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
26cf0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
26d00 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
26d10 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
26d20 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
26d30 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
26d40 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
26d50 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
26d60 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
26d70 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
26d80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
26d90 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
26da0 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
26db0 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
26dc0 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
26dd0 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
26de0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
26df0 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
26e00 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
26e10 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
26e20 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  t is negative, t
26e30 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
26e40 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69   up to the.** fi
26e50 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
26e60 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69  tor. ^If nByte i
26e70 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e  s positive, then
26e80 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75   it is the.** nu
26e90 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65  mber of bytes re
26ea0 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e  ad from zSql.  ^
26eb0 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f  If nByte is zero
26ec0 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72  , then no prepar
26ed0 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
26ee0 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a  is generated..**
26ef0 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b   If the caller k
26f00 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75  nows that the su
26f10 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
26f20 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
26f30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69   then.** there i
26f40 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72  s a small perfor
26f50 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
26f60 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42  to passing an nB
26f70 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  yte parameter th
26f80 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  at.** is the num
26f90 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
26fa0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
26fb0 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
26fc0 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
26fd0 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  minator..**.** ^
26fe0 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  If pzTail is not
26ff0 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61   NULL then *pzTa
27000 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
27010 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
27020 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68   byte.** past th
27030 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
27040 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
27050 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
27060 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a   routines only.*
27070 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  * compile the fi
27080 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  rst statement in
27090 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
270a0 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
270b0 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65  ng to.** what re
270c0 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64  mains uncompiled
270d0 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74  ..**.** ^*ppStmt
270e0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
270f0 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
27100 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27110 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
27120 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
27130 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
27140 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20  ()].  ^If there 
27150 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
27160 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
27170 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65  o NULL.  ^If the
27180 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
27190 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
271a0 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20  the input is an 
271b0 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20  empty.** string 
271c0 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
271d0 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
271e0 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68  t to NULL..** Th
271f0 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64  e calling proced
27200 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
27210 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
27220 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  the compiled.** 
27230 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73  SQL statement us
27240 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
27250 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
27260 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
27270 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d  ith it..** ppStm
27280 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c  t may not be NUL
27290 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63  L..**.** ^On suc
272a0 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65  cess, the sqlite
272b0 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69  3_prepare() fami
272c0 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72  ly of routines r
272d0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
272e0 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  ];.** otherwise 
272f0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
27300 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
27310 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
27320 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
27330 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
27340 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
27350 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
27360 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
27370 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
27380 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
27390 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
273a0 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
273b0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
273c0 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
273d0 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
273e0 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69  * ^In the "v2" i
273f0 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
27400 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27410 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
27420 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
27430 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
27440 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
27450 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67  y of the.** orig
27460 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54  inal SQL text. T
27470 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
27480 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
27490 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
274a0 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74  behave different
274b0 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73  ly in three ways
274c0 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
274d0 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
274e0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
274f0 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
27500 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
27510 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
27520 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
27530 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
27540 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
27550 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
27560 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
27570 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
27580 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
27590 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73  gain. As many as
275a0 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48   [SQLITE_MAX_SCH
275b0 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65  EMA_RETRY].** re
275c0 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72  tries will occur
275d0 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
275e0 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20  step() gives up 
275f0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65  and returns an e
27600 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  rror..** </li>.*
27610 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68  *.** <li>.** ^Wh
27620 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
27630 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
27640 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
27650 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
27660 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
27670 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
27680 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
27690 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65    ^The legacy be
276a0 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a  havior was that.
276b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
276c0 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
276d0 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20  eturn a generic 
276e0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
276f0 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e  esult code.** an
27700 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
27710 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  n would have to 
27720 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
27730 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
27740 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72  eset()].** in or
27750 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20  der to find the 
27760 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
27770 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
27780 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
27790 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66  repare.** interf
277a0 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
277b0 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
277c0 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74  the error is ret
277d0 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
277e0 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  y..** </li>.**.*
277f0 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
27800 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
27810 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d   bound to [param
27820 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61  eter | host para
27830 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a  meter] in the .*
27840 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d  * WHERE clause m
27850 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
27860 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  he choice of que
27870 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74  ry plan for a st
27880 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e  atement,.** then
27890 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
278a0 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
278b0 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c  ally recompiled,
278c0 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64   as if there had
278d0 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65   been .** a sche
278e0 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68  ma change, on th
278f0 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65  e first  [sqlite
27900 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66  3_step()] call f
27910 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61  ollowing any cha
27920 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  nge.** to the [s
27930 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
27940 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20   | bindings] of 
27950 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d  that [parameter]
27960 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69  . .** ^The speci
27970 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45  fic value of WHE
27980 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d  RE-clause [param
27990 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c  eter] might infl
279a0 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68  uence the .** ch
279b0 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
279c0 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  an if the parame
279d0 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d  ter is the left-
279e0 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b  hand side of a [
279f0 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f  LIKE].** or [GLO
27a00 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69  B] operator or i
27a10 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
27a20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61  is compared to a
27a30 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e  n indexed column
27a40 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c  .** and the [SQL
27a50 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33  ITE_ENABLE_STAT3
27a60 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
27a70 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
27a80 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  ..** </li>.** </
27a90 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ol>.*/.int sqlit
27aa0 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
27ab0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
27ac0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
27ad0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
27ae0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
27af0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
27b00 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
27b10 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
27b20 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
27b30 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
27b40 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
27b50 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
27b60 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
27b70 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
27b80 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
27b90 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
27ba0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
27bb0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
27bc0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
27bd0 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
27be0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
27bf0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
27c00 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
27c10 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
27c20 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
27c30 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
27c40 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
27c50 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
27c60 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
27c70 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
27c80 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
27c90 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
27ca0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
27cb0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
27cc0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
27cd0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
27ce0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
27cf0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
27d00 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
27d10 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
27d20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
27d30 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
27d40 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
27d50 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
27d60 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
27d70 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
27d80 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
27d90 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
27da0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
27db0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
27dc0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
27dd0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
27de0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
27df0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
27e00 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
27e10 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
27e20 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
27e30 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
27e40 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
27e50 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
27e60 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
27e70 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
27e80 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
27e90 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
27ea0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
27eb0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
27ec0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
27ed0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
27ee0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
27ef0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
27f00 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
27f10 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
27f20 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
27f30 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
27f40 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
27f50 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
27f60 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
27f70 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
27f80 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
27f90 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
27fa0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
27fb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27fc0 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
27fd0 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e  ment SQL.**.** ^
27fe0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
27ff0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
28000 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63  trieve a saved c
28010 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69  opy of the origi
28020 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  nal.** SQL text 
28030 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61  used to create a
28040 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28050 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74  ment] if that st
28060 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63  atement was.** c
28070 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
28080 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
28090 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
280a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
280b0 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  6_v2()]..*/.cons
280c0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
280d0 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
280e0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
280f0 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
28100 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
28110 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20  tatement Writes 
28120 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a  The Database.**.
28130 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28140 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29  stmt_readonly(X)
28150 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
28160 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
28170 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  o) if.** and onl
28180 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72  y if the [prepar
28190 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20  ed statement] X 
281a0 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20  makes no direct 
281b0 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68  changes to.** th
281c0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
281d0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
281e0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
281f0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
28200 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
28210 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75  ns] or.** [virtu
28220 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74  al tables] might
28230 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
28240 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20  base indirectly 
28250 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74  as a side effect
28260 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .  .** ^(For exa
28270 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c  mple, if an appl
28280 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20  ication defines 
28290 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c  a function "eval
282a0 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c  ()" that .** cal
282b0 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ls [sqlite3_exec
282c0 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  ()], then the fo
282d0 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74  llowing SQL stat
282e0 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63  ement would.** c
282f0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
28300 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20  se file through 
28310 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a  side-effects:.**
28320 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
28330 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45  <pre>.**    SELE
28340 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20  CT eval('DELETE 
28350 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74  FROM t1') FROM t
28360 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  2;.** </pre></bl
28370 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
28380 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20  But because the 
28390 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
283a0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nt does not chan
283b0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
283c0 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79  file.** directly
283d0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  , sqlite3_stmt_r
283e0 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20  eadonly() would 
283f0 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75  still return tru
28400 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e  e.)^.**.** ^Tran
28410 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20  saction control 
28420 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20  statements such 
28430 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d  as [BEGIN], [COM
28440 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d  MIT], [ROLLBACK]
28450 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d  ,.** [SAVEPOINT]
28460 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20  , and [RELEASE] 
28470 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74  cause sqlite3_st
28480 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
28490 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a   return true,.**
284a0 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65   since the state
284b0 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73  ments themselves
284c0 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   do not actually
284d0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
284e0 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68  base but.** rath
284f0 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20  er they control 
28500 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68  the timing of wh
28510 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65  en other stateme
28520 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a  nts modify the .
28530 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54  ** database.  ^T
28540 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20  he [ATTACH] and 
28550 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65  [DETACH] stateme
28560 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a  nts also cause.*
28570 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
28580 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
28590 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20  urn true since, 
285a0 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74  while those stat
285b0 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65  ements.** change
285c0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
285d0 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  on of a database
285e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65   connection, the
285f0 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a  y do not make .*
28600 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  * changes to the
28610 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
28620 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f  database files o
28630 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73  n disk..*/.int s
28640 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
28650 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  only(sqlite3_stm
28660 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
28670 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
28680 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61  rmine If A Prepa
28690 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61  red Statement Ha
286a0 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a  s Been Reset.**.
286b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
286c0 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74  stmt_busy(S) int
286d0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
286e0 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
286f0 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
28700 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
28710 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64  has been stepped
28720 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75   at least once u
28730 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
28740 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68  3_step(S)] but h
28750 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f  as not run to co
28760 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20  mpletion and/or 
28770 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e  has not .** been
28780 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71   reset using [sq
28790 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e  lite3_reset(S)].
287a0 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
287b0 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69  tmt_busy(S).** i
287c0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
287d0 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61   false if S is a
287e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
287f0 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a  If S is not a .*
28800 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  * NULL pointer a
28810 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e  nd is not a poin
28820 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b  ter to a valid [
28830 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28840 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74  nt].** object, t
28850 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
28860 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
28870 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
28880 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  irable..**.** Th
28890 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
288a0 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62   be used in comb
288b0 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33  ination [sqlite3
288c0 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a  _next_stmt()].**
288d0 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70   to locate all p
288e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
288f0 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ts associated wi
28900 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a  th a database .*
28910 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  * connection tha
28920 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66  t are in need of
28930 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54   being reset.  T
28940 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c  his can be used,
28950 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  .** for example,
28960 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72   in diagnostic r
28970 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63  outines to searc
28980 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a  h for prepared .
28990 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  ** statements th
289a0 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61  at are holding a
289b0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65   transaction ope
289c0 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
289d0 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69  3_stmt_busy(sqli
289e0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
289f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
28a00 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
28a10 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
28a20 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
28a30 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
28a40 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
28a50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
28a60 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
28a70 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
28a80 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
28a90 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
28aa0 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
28ab0 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
28ac0 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
28ad0 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
28ae0 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
28af0 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
28b00 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
28b10 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
28b20 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
28b30 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
28b40 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
28b50 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
28b60 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
28b70 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
28b80 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
28b90 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
28ba0 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
28bb0 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
28bc0 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
28bd0 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
28be0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
28bf0 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
28c00 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
28c10 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
28c20 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
28c30 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
28c40 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
28c50 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
28c60 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
28c70 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
28c80 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
28c90 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
28ca0 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
28cb0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
28cc0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
28cd0 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
28ce0 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
28cf0 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
28d00 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
28d10 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20  ex is held.  An 
28d20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
28d30 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
28d40 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
28d50 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
28d60 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
28d70 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
28d80 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
28d90 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
28da0 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
28db0 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
28dc0 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
28dd0 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
28de0 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
28df0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
28e00 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
28e10 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
28e20 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
28e30 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
28e40 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
28e50 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
28e60 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
28e70 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
28e80 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
28e90 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
28ea0 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
28eb0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
28ec0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
28ed0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
28ee0 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
28ef0 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
28f00 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
28f10 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
28f20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
28f30 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
28f40 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
28f50 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
28f60 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
28f70 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
28f80 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
28f90 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
28fa0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
28fb0 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
28fc0 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
28fd0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
28fe0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
28ff0 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
29000 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
29010 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
29020 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
29030 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
29040 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
29050 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
29060 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
29070 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
29080 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
29090 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
290a0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
290b0 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
290c0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
290d0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
290e0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
290f0 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
29100 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
29110 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
29120 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
29130 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
29140 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
29150 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
29160 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
29170 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
29180 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
29190 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
291a0 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
291b0 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
291c0 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
291d0 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
291e0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
291f0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
29200 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
29210 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
29220 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
29230 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
29240 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
29250 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
29260 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
29270 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
29280 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
29290 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
292a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
292b0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
292c0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
292d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
292e0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
292f0 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
29300 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
29310 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
29320 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
29330 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
29340 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
29350 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
29360 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
29370 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
29380 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
29390 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
293a0 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
293b0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
293c0 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
293d0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
293e0 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
293f0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
29400 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
29410 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
29420 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
29430 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
29440 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
29450 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
29460 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
29470 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
29480 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
29490 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
294a0 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
294b0 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
294c0 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
294d0 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a  r binding}.**.**
294e0 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
294f0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
29500 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
29510 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
29520 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
29530 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
29540 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
29550 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
29560 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
29570 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
29580 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
29590 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
295a0 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
295b0 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
295c0 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
295d0 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
295e0 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
295f0 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
29600 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
29610 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
29620 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
29630 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
29640 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72  meric identifier
29650 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  .)^  ^The values
29660 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72   of these.** par
29670 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
29680 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
29690 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22  eter names" or "
296a0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29  SQL parameters")
296b0 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75  .** can be set u
296c0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
296d0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
296e0 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  es defined here.
296f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
29700 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
29710 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
29720 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
29730 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
29740 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
29750 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
29760 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
29770 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
29780 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
29790 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ariants..**.** ^
297a0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
297b0 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
297c0 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
297d0 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
297e0 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  .** ^The leftmos
297f0 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
29800 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
29810 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61  1.  ^When the sa
29820 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20  me named.** SQL 
29830 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
29840 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
29850 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
29860 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
29870 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
29880 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
29890 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
298a0 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65  ce..** ^The inde
298b0 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
298c0 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
298d0 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
298e0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
298f0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
29900 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
29910 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65  ired.  ^The inde
29920 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
29930 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
29940 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
29950 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75  ** ^The NNN valu
29960 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
29970 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
29980 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
29990 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
299a0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
299b0 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
299c0 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
299d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
299e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
299f0 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
29a00 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
29a10 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
29a20 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
29a30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
29a40 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
29a50 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f  nd_text16().** o
29a60 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  r sqlite3_bind_b
29a70 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  lob() is a NULL 
29a80 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
29a90 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
29aa0 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20  r.** is ignored 
29ab0 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75  and the end resu
29ac0 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  lt is the same a
29ad0 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  s sqlite3_bind_n
29ae0 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ull()..**.** ^(I
29af0 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73  n those routines
29b00 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75   that have a fou
29b10 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74  rth argument, it
29b20 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  s value is the.*
29b30 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
29b40 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  s in the paramet
29b50 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72  er.  To be clear
29b60 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74  : the value is t
29b70 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
29b80 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20  <u>bytes</u> in 
29b90 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74  the value, not t
29ba0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
29bb0 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49  racters.)^.** ^I
29bc0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
29bd0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
29be0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
29bf0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
29c00 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67  xt16().** is neg
29c10 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
29c20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
29c30 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e  ring is.** the n
29c40 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
29c50 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
29c60 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
29c70 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  ** If the fourth
29c80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
29c90 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
29ca0 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  ) is negative, t
29cb0 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76  hen.** the behav
29cc0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
29cd0 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65  ..** If a non-ne
29ce0 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61  gative fourth pa
29cf0 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69  rameter is provi
29d00 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ded to sqlite3_b
29d10 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72  ind_text().** or
29d20 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
29d30 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65  xt16() or sqlite
29d40 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
29d50 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72  then.** that par
29d60 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74  ameter must be t
29d70 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a  he byte offset.*
29d80 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  * where the NUL 
29d90 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
29da0 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20   occur assuming 
29db0 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20  the string were 
29dc0 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65  NUL.** terminate
29dd0 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
29de0 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20  haracters occur 
29df0 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20  at byte offsets 
29e00 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68  less than .** th
29e10 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66  e value of the f
29e20 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
29e30 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69  then the resulti
29e40 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20  ng string value 
29e50 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  will.** contain 
29e60 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20  embedded NULs.  
29e70 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78  The result of ex
29e80 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76  pressions involv
29e90 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77  ing strings.** w
29ea0 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
29eb0 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
29ec0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
29ed0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
29ee0 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67   BLOB and string
29ef0 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61   binding interfa
29f00 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74  ces.** is a dest
29f10 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
29f20 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
29f30 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
29f40 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
29f50 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
29f60 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63  t.  ^The destruc
29f70 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a  tor is called.**
29f80 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
29f90 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
29fa0 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61  g even if the ca
29fb0 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66  ll to bind API f
29fc0 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ails..** ^If the
29fd0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
29fe0 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61  is.** the specia
29ff0 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  l value [SQLITE_
2a000 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51  STATIC], then SQ
2a010 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
2a020 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  t the.** informa
2a030 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69  tion is in stati
2a040 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  c, unmanaged spa
2a050 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  ce and does not 
2a060 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64  need to be freed
2a070 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66  ..** ^If the fif
2a080 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  th argument has 
2a090 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  the value [SQLIT
2a0a0 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
2a0b0 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  en.** SQLite mak
2a0c0 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  es its own priva
2a0d0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64  te copy of the d
2a0e0 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  ata immediately,
2a0f0 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73   before.** the s
2a100 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2a110 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e  routine returns.
2a120 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74  .**.** ^The sixt
2a130 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
2a140 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2a150 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20  4() must be one 
2a160 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  of.** [SQLITE_UT
2a170 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
2a180 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  16], [SQLITE_UTF
2a190 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  16BE], or [SQLIT
2a1a0 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f  E_UTF16LE].** to
2a1b0 20 73 70 65 63 69 66 79 20 74 68 65 20 65 6e 63   specify the enc
2a1c0 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78  oding of the tex
2a1d0 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70  t in the third p
2a1e0 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a  arameter.  If.**
2a1f0 20 74 68 65 20 73 69 78 74 68 20 61 72 67 75 6d   the sixth argum
2a200 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
2a210 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73 20  ind_text64() is 
2a220 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
2a230 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73  * allowed values
2a240 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72   shown above, or
2a250 20 69 66 20 74 68 65 20 74 65 78 74 20 65 6e 63   if the text enc
2a260 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
2a270 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65  nt.** from the e
2a280 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65  ncoding specifie
2a290 64 20 62 79 20 74 68 65 20 73 69 78 74 68 20 70  d by the sixth p
2a2a0 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74  arameter, then t
2a2b0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69  he behavior.** i
2a2c0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2a2d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2a2e0 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
2a2f0 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
2a300 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e  BLOB of length N
2a310 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
2a320 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20  ed with zeroes. 
2a330 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65   ^A zeroblob use
2a340 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
2a350 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
2a360 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
2a370 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29  o hold its size)
2a380 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
2a390 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a  ng processed..**
2a3a0 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69   Zeroblobs are i
2a3b0 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65  ntended to serve
2a3c0 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73   as placeholders
2a3d0 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
2a3e0 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
2a3f0 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
2a400 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ng.** [sqlite3_b
2a410 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
2a420 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
2a430 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41   routines..** ^A
2a440 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
2a450 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
2a460 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
2a470 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
2a480 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66  **.** ^If any of
2a490 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2a4a0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61  d_*() routines a
2a4b0 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  re called with a
2a4c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
2a4d0 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
2a4e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72  ed statement] or
2a4f0 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64   with a prepared
2a500 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77   statement for w
2a510 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hich.** [sqlite3
2a520 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65  _step()] has bee
2a530 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65  n called more re
2a540 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c  cently than [sql
2a550 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a  ite3_reset()],.*
2a560 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20  * then the call 
2a570 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
2a580 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66  ITE_MISUSE].  If
2a590 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e   any sqlite3_bin
2a5a0 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  d_().** routine 
2a5b0 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65  is passed a [pre
2a5c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a5d0 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66   that has been f
2a5e0 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a  inalized, the.**
2a5f0 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
2a600 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
2a610 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
2a620 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e   ^Bindings are n
2a630 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
2a640 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
2a650 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
2a660 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  ^Unbound paramet
2a670 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  ers are interpre
2a680 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ted as NULL..**.
2a690 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2a6a0 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20  bind_* routines 
2a6b0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
2a6c0 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
2a6d0 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f   an.** [error co
2a6e0 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20  de] if anything 
2a6f0 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e  goes wrong..** ^
2a700 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20  [SQLITE_TOOBIG] 
2a710 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
2a720 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66  d if the size of
2a730 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
2a740 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d  B.** exceeds lim
2a750 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b  its imposed by [
2a760 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
2a770 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
2a780 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c  GTH]) or.** [SQL
2a790 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e  ITE_MAX_LENGTH].
2a7a0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e  .** ^[SQLITE_RAN
2a7b0 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
2a7c0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
2a7d0 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
2a7e0 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51   of range.  ^[SQ
2a7f0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72  LITE_NOMEM] is r
2a800 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f  eturned if mallo
2a810 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  c() fails..**.**
2a820 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2a830 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2a840 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20  er_count()],.** 
2a850 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2a860 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
2a870 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
2a880 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2a890 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
2a8a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
2a8b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a8c0 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
2a8d0 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
2a8e0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
2a8f0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34  ite3_bind_blob64
2a900 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a910 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2a920 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
2a930 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2a940 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a            void(*
2a950 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
2a960 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
2a970 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
2a980 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
2a990 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2a9a0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
2a9b0 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
2a9c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2a9d0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
2a9e0 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
2a9f0 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
2aa00 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
2aa10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2aa20 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
2aa30 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
2aa40 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e  e3_stmt*,int,con
2aa50 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69  st char*,int,voi
2aa60 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
2aa70 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
2aa80 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
2aa90 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2aaa0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
2aab0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2aac0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2aad0 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt64(sqlite3_stm
2aae0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
2aaf0 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  har*, sqlite3_ui
2ab00 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
2ab10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
2ab20 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75  oid(*)(void*), u
2ab30 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63  nsigned char enc
2ab40 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69  oding);.int sqli
2ab50 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
2ab60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2ab70 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
2ab80 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2ab90 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
2aba0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2abb0 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
2abc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2abd0 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50   Number Of SQL P
2abe0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
2abf0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61  ^This routine ca
2ac00 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e  n be used to fin
2ac10 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
2ac20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d  [SQL parameters]
2ac30 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72  .** in a [prepar
2ac40 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
2ac50 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61  SQL parameters a
2ac60 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65  re tokens of the
2ac70 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f  .** form "?", "?
2ac80 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24  NNN", ":AAA", "$
2ac90 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20  AAA", or "@AAA" 
2aca0 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a  that serve as.**
2acb0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
2acc0 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72  r values that ar
2acd0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2ace0 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a  blob | bound].**
2acf0 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
2ad00 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69  rs at a later ti
2ad10 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  me..**.** ^(This
2ad20 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c   routine actuall
2ad30 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e  y returns the in
2ad40 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65  dex of the large
2ad50 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a  st (rightmost).*
2ad60 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72  * parameter. For
2ad70 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70   all forms excep
2ad80 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c  t ?NNN, this wil
2ad90 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20  l correspond to 
2ada0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2adb0 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65   unique paramete
2adc0 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65  rs.  If paramete
2add0 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66  rs of the ?NNN f
2ade0 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a  orm are used,.**
2adf0 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61   there may be ga
2ae00 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29  ps in the list.)
2ae10 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
2ae20 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2ae30 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2ae40 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
2ae50 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2ae60 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
2ae70 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2ae80 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2ae90 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
2aea0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2aeb0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2aec0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2aed0 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
2aee0 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72  A Host Parameter
2aef0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2af00 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2af10 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74  er_name(P,N) int
2af20 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
2af30 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * the name of th
2af40 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61  e N-th [SQL para
2af50 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70  meter] in the [p
2af60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2af70 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70  t] P..** ^(SQL p
2af80 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
2af90 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
2afa0 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
2afb0 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
2afc0 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
2afd0 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
2afe0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
2aff0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
2b000 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
2b010 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
2b020 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
2b030 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
2b040 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
2b050 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
2b060 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29  rt of the name.)
2b070 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73  ^.** ^Parameters
2b080 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
2b090 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f   without a follo
2b0a0 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76  wing integer hav
2b0b0 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64  e no name.** and
2b0c0 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f   are referred to
2b0d0 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f   as "nameless" o
2b0e0 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  r "anonymous par
2b0f0 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20  ameters"..**.** 
2b100 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20  ^The first host 
2b110 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
2b120 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74   index of 1, not
2b130 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   0..**.** ^If th
2b140 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74  e value N is out
2b150 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
2b160 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74  the N-th paramet
2b170 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
2b180 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
2b190 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20  returned.  ^The 
2b1a0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2b1b0 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20  is.** always in 
2b1c0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65  UTF-8 encoding e
2b1d0 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64  ven if the named
2b1e0 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a   parameter was.*
2b1f0 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65  * originally spe
2b200 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36  cified as UTF-16
2b210 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   in [sqlite3_pre
2b220 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  pare16()] or.** 
2b230 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b240 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
2b250 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2b260 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2b270 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
2b280 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2b290 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
2b2a0 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2b2b0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2b2c0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63  r_index()]..*/.c
2b2d0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2b2e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2b2f0 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
2b300 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
2b310 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
2b320 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
2b330 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
2b340 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  ame.**.** ^Retur
2b350 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  n the index of a
2b360 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
2b370 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
2b380 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76   ^The.** index v
2b390 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
2b3a0 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73   suitable for us
2b3b0 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  e as the second.
2b3c0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
2b3d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2b3e0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2b3f0 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20  )].  ^A zero.** 
2b400 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
2b410 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
2b420 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
2b430 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a  ^The parameter.*
2b440 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67  * name must be g
2b450 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76  iven in UTF-8 ev
2b460 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e  en if the origin
2b470 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  al statement.** 
2b480 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f  was prepared fro
2b490 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73  m UTF-16 text us
2b4a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
2b4b0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
2b4c0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2b4d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2b4e0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2b4f0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2b500 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2b510 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
2b520 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2b530 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2b540 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
2b550 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2b560 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
2b570 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
2b580 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
2b590 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
2b5a0 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
2b5b0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2b5c0 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61  nt.**.** ^Contra
2b5d0 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
2b5e0 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
2b5f0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
2b600 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
2b610 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
2b620 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
2b630 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
2b640 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2b650 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74  * ^Use this rout
2b660 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
2b670 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
2b680 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
2b690 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
2b6a0 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
2b6b0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2b6c0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
2b6d0 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
2b6e0 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
2b6f0 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d   ^Return the num
2b700 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2b710 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
2b720 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2b730 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2b740 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20  atement]. ^This 
2b750 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2b760 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e  0 if pStmt is an
2b770 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
2b780 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  t that does not 
2b790 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72  return data (for
2b7a0 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44   example an [UPD
2b7b0 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ATE])..**.** See
2b7c0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2b7d0 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  data_count()].*/
2b7e0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2b7f0 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
2b800 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2b810 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b820 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
2b830 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
2b840 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2b850 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
2b860 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
2b870 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
2b880 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
2b890 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
2b8a0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2b8b0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2b8c0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a  column_name().**
2b8d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2b8e0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2b8f0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2b900 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  d UTF-8 string.*
2b910 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
2b920 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65  lumn_name16() re
2b930 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2b940 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2b950 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
2b960 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72  tring.  ^The fir
2b970 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2b980 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2b990 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
2b9a0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
2b9b0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2b9c0 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  nt. ^The second 
2b9d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2b9e0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
2b9f0 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  r.  ^The leftmos
2ba00 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
2ba10 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er 0..**.** ^The
2ba20 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2ba30 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
2ba40 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
2ba50 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2ba60 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
2ba70 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
2ba80 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2ba90 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
2baa0 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
2bab0 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
2bac0 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
2bad0 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
2bae0 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
2baf0 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
2bb00 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
2bb10 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
2bb20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bb30 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
2bb40 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2bb50 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
2bb60 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lumn..**.** ^If 
2bb70 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2bb80 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
2bb90 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
2bba0 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
2bbb0 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
2bbc0 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
2bbd0 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
2bbe0 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
2bbf0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
2bc00 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2bc10 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2bc20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
2bc30 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
2bc40 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
2bc50 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
2bc60 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
2bc70 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
2bc80 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
2bc90 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
2bca0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2bcb0 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
2bcc0 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
2bcd0 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
2bce0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
2bcf0 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
2bd00 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2bd10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2bd20 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2bd30 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20  , int N);.const 
2bd40 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2bd50 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
2bd60 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
2bd70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2bd80 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
2bd90 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
2bda0 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  sult.**.** ^Thes
2bdb0 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
2bdc0 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
2bdd0 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61  termine the data
2bde0 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
2bdf0 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  .** table column
2be00 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69   that is the ori
2be10 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75  gin of a particu
2be20 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  lar result colum
2be30 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d  n in.** [SELECT]
2be40 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
2be50 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
2be60 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
2be70 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
2be80 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
2be90 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
2bea0 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
2beb0 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61  g.  ^The _databa
2bec0 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
2bed0 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
2bee0 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
2bef0 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
2bf00 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
2bf10 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
2bf20 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
2bf30 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
2bf40 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68  umn name..** ^Th
2bf50 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2bf60 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
2bf70 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2bf80 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
2bf90 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
2bfa0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2bfb0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
2bfc0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2bfd0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
2bfe0 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
2bff0 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
2c000 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2c010 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
2c020 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
2c030 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
2c040 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
2c050 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
2c060 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
2c070 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ding..**.** ^The
2c080 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
2c090 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
2c0a0 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
2c0b0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
2c0c0 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
2c0d0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
2c0e0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2c0f0 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  nt to these inte
2c100 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65  rfaces is a [pre
2c110 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c120 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  ..** ^These func
2c130 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
2c140 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
2c150 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
2c160 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
2c170 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
2c180 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
2c190 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
2c1a0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  n argument..** ^
2c1b0 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
2c1c0 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30  lumn is column 0
2c1d0 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
2c1e0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  nes..**.** ^If t
2c1f0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
2c200 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
2c210 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
2c220 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73  pression or.** s
2c230 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
2c240 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
2c250 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
2c260 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
2c270 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20  eturn.** NULL.  
2c280 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d  ^These routine m
2c290 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e  ight also return
2c2a0 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72   NULL if a memor
2c2b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
2c2c0 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e  or.** occurs.  ^
2c2d0 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
2c2e0 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
2c2f0 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
2c300 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2c310 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68  .** or column th
2c320 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
2c330 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
2c340 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
2c350 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74   ^As with all ot
2c360 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
2c370 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d   those whose nam
2c380 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22  es end with "16"
2c390 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
2c3a0 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
2c3b0 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  s and the other 
2c3c0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2c3d0 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54   UTF-8..**.** ^T
2c3e0 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
2c3f0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
2c400 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
2c410 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
2c420 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
2c430 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
2c440 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
2c450 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a  sor symbol..**.*
2c460 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
2c470 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
2c480 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
2c490 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
2c4a0 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
2c4b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c4c0 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
2c4d0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
2c4e0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2c4f0 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
2c500 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
2c510 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
2c520 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
2c530 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2c540 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2c550 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
2c560 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
2c570 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b  * for the same [
2c580 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c590 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
2c5a0 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20  olumn.** at the 
2c5b0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
2c5c0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
2c5d0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e  ndefined..*/.con
2c5e0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2c5f0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
2c600 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2c610 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2c620 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2c630 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2c640 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2c650 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
2c660 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2c670 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
2c680 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2c690 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2c6a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
2c6b0 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
2c6c0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
2c6d0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2c6e0 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
2c6f0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2c700 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2c710 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2c720 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
2c730 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2c740 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
2c750 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
2c760 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
2c770 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
2c780 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61  * ^(The first pa
2c790 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
2c7a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c7b0 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
2c7c0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
2c7d0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
2c7e0 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
2c7f0 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
2c800 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
2c810 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
2c820 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
2c830 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
2c840 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
2c850 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
2c860 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
2c870 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
2c880 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
2c890 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68  .)^  ^If the Nth
2c8a0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2c8b0 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
2c8c0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
2c8d0 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
2c8e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
2c8f0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
2c900 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2c910 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
2c920 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a  F-8 encoded..**.
2c930 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
2c940 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
2c950 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
2c960 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
2c970 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
2c980 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
2c990 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
2c9a0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
2c9b0 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
2c9c0 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
2c9d0 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
2c9e0 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
2c9f0 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
2ca00 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
2ca10 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
2ca20 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
2ca30 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
2ca40 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
2ca50 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
2ca60 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  i==0).)^.**.** ^
2ca70 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
2ca80 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
2ca90 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62  ing.  ^So just b
2caa0 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
2cab0 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
2cac0 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
2cad0 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
2cae0 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
2caf0 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
2cb00 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
2cb10 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
2cb20 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
2cb30 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
2cb40 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
2cb50 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
2cb60 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e  c not static.  ^
2cb70 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
2cb80 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
2cb90 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
2cba0 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
2cbb0 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
2cbc0 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
2cbd0 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  es..*/.const cha
2cbe0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2cbf0 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
2cc00 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
2cc10 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2cc20 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
2cc30 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
2cc40 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
2cc50 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
2cc60 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
2cc70 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  ent.**.** After 
2cc80 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2cc90 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
2cca0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65  prepared using e
2ccb0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
2ccc0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2ccd0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2cce0 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f  are16_v2()] or o
2ccf0 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ne of the legacy
2cd00 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
2cd10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2cd20 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
2cd30 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69  repare16()], thi
2cd40 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75  s function.** mu
2cd50 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
2cd60 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
2cd70 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73  o evaluate the s
2cd80 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
2cd90 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74  The details of t
2cda0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
2cdb0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
2cdc0 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65  ) interface depe
2cdd0 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  nd.** on whether
2cde0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
2cdf0 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  as prepared usin
2ce00 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22  g the newer "v2"
2ce10 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73   interface.** [s
2ce20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2ce30 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
2ce40 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2ce50 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c  ] or the older l
2ce60 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
2ce70 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ce [sqlite3_prep
2ce80 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
2ce90 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2cea0 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
2ceb0 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e  e.** new "v2" in
2cec0 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
2ced0 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61  mended for new a
2cee0 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20  pplications but 
2cef0 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
2cf00 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e  terface will con
2cf10 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70  tinue to be supp
2cf20 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  orted..**.** ^In
2cf30 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2cf40 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72  rface, the retur
2cf50 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20  n value will be 
2cf60 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42  either [SQLITE_B
2cf70 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  USY],.** [SQLITE
2cf80 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
2cf90 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52  ROW], [SQLITE_ER
2cfa0 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROR], or [SQLITE
2cfb0 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69  _MISUSE]..** ^Wi
2cfc0 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
2cfd0 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68  rface, any of th
2cfe0 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20  e other [result 
2cff0 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78  codes] or.** [ex
2d000 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
2d010 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65  des] might be re
2d020 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a  turned as well..
2d030 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42  **.** ^[SQLITE_B
2d040 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USY] means that 
2d050 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
2d060 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74  ine was unable t
2d070 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a  o acquire the.**
2d080 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20   database locks 
2d090 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69  it needs to do i
2d0a0 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65  ts job.  ^If the
2d0b0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
2d0c0 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f  [COMMIT].** or o
2d0d0 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66  ccurs outside of
2d0e0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
2d0f0 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79  nsaction, then y
2d100 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65  ou can retry the
2d110 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  .** statement.  
2d120 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
2d130 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49   is not a [COMMI
2d140 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69  T] and occurs wi
2d150 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69  thin an.** expli
2d160 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
2d170 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
2d180 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
2d190 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
2d1a0 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
2d1b0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f  *.** ^[SQLITE_DO
2d1c0 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
2d1d0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
2d1e0 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
2d1f0 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
2d200 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
2d210 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
2d220 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
2d230 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
2d240 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
2d250 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
2d260 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2d270 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
2d280 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
2d290 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
2d2a0 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
2d2b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20  .** ^If the SQL 
2d2c0 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20  statement being 
2d2d0 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73  executed returns
2d2e0 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20   any data, then 
2d2f0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20  [SQLITE_ROW].** 
2d300 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68  is returned each
2d310 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20   time a new row 
2d320 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79  of data is ready
2d330 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
2d340 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72  by the.** caller
2d350 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79  . The values may
2d360 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69   be accessed usi
2d370 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61  ng the [column a
2d380 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
2d390 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ..** sqlite3_ste
2d3a0 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67  p() is called ag
2d3b0 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20  ain to retrieve 
2d3c0 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20  the next row of 
2d3d0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  data..**.** ^[SQ
2d3e0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e  LITE_ERROR] mean
2d3f0 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d  s that a run-tim
2d400 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73  e error (such as
2d410 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a   a constraint.**
2d420 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20   violation) has 
2d430 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74  occurred.  sqlit
2d440 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
2d450 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
2d460 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56  gain on.** the V
2d470 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74  M. More informat
2d480 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64  ion may be found
2d490 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
2d4a0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
2d4b0 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67  ** ^With the leg
2d4c0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61  acy interface, a
2d4d0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
2d4e0 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65  rror code (for e
2d4f0 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49  xample,.** [SQLI
2d500 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
2d510 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
2d520 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
2d530 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
2d540 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
2d550 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
2d560 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2d570 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
2d580 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2d590 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
2d5a0 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
2d5b0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
2d5c0 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
2d5d0 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
2d5e0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2d5f0 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
2d600 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
2d610 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
2d620 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
2d630 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
2d640 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
2d650 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72   called on a [pr
2d660 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d670 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
2d680 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
2d690 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
2d6a0 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
2d6b0 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20  one that had.** 
2d6c0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
2d6d0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
2d6e0 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
2d6f0 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
2d700 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
2d710 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
2d720 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d730 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
2d740 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
2d750 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
2d760 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
2d770 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72   time..**.** For
2d780 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66   all versions of
2d790 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e   SQLite up to an
2d7a0 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e  d including 3.6.
2d7b0 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a  23.1, a call to.
2d7c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2d7d0 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65  t()] was require
2d7e0 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
2d7f0 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20  step() returned 
2d800 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65  anything.** othe
2d810 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
2d820 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73  OW] before any s
2d830 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
2d840 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  tion of.** sqlit
2d850 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c  e3_step().  Fail
2d860 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65  ure to reset the
2d870 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2d880 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  ent using .** [s
2d890 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2d8a0 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  would result in 
2d8b0 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  an [SQLITE_MISUS
2d8c0 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a  E] return from.*
2d8d0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2d8e0 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72  .  But after ver
2d8f0 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73  sion 3.6.23.1, s
2d900 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65  qlite3_step() be
2d910 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b  gan.** calling [
2d920 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2d930 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
2d940 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61  n this circumsta
2d950 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68  nce rather.** th
2d960 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  an returning [SQ
2d970 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54  LITE_MISUSE].  T
2d980 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69  his is not consi
2d990 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62  dered a compatib
2d9a0 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62  ility.** break b
2d9b0 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69  ecause any appli
2d9c0 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72  cation that ever
2d9d0 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c   receives an SQL
2d9e0 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72  ITE_MISUSE error
2d9f0 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79  .** is broken by
2da00 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
2da10 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
2da20 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c  UTORESET] compil
2da30 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a  e-time option.**
2da40 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2da50 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61  restore the lega
2da60 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  cy behavior..**.
2da70 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
2da80 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
2da90 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
2daa0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71  nterface, the sq
2dab0 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20  lite3_step().** 
2dac0 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72  API always retur
2dad0 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72  ns a generic err
2dae0 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45  or code, [SQLITE
2daf0 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69  _ERROR], followi
2db00 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20  ng any.** error 
2db10 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2db20 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51  TE_BUSY] and [SQ
2db30 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59  LITE_MISUSE].  Y
2db40 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20  ou must call.** 
2db50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2db60 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
2db70 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64  nalize()] in ord
2db80 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f  er to find one o
2db90 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  f the.** specifi
2dba0 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
2dbb0 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63  that better desc
2dbc0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e  ribes the error.
2dbd0 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61  .** We admit tha
2dbe0 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66  t this is a goof
2dbf0 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70  y design.  The p
2dc00 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20  roblem has been 
2dc10 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  fixed.** with th
2dc20 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2dc30 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72  .  If you prepar
2dc40 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51  e all of your SQ
2dc50 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
2dc60 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
2dc70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2dc80 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2dc90 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2dca0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68  instead.** of th
2dcb0 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
2dcc0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
2dcd0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2dce0 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  e16()] interface
2dcf0 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d  s,.** then the m
2dd00 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
2dd10 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
2dd20 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
2dd30 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
2dd40 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
2dd50 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  of the "v2" inte
2dd60 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
2dd70 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nded..*/.int sql
2dd80 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
2dd90 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2dda0 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
2ddb0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2ddc0 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a  a result set.**.
2ddd0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2dde0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e  data_count(P) in
2ddf0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2de00 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
2de10 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20  lumns in the.** 
2de20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
2de30 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
2de40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2de50 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20  ment] P..** ^If 
2de60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2de70 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61  nt P does not ha
2de80 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79  ve results ready
2de90 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76   to return.** (v
2dea0 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ia calls to the 
2deb0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2dec0 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f  int | sqlite3_co
2ded0 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20  lumn_*()] of.** 
2dee0 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e  interfaces) then
2def0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2df00 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30  unt(P) returns 0
2df10 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2df20 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2df30 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74  routine also ret
2df40 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61  urns 0 if P is a
2df50 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2df60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2df70 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
2df80 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
2df90 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  f the previous c
2dfa0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2dfb0 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
2dfc0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  rned [SQLITE_DON
2dfd0 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  E].  ^The sqlite
2dfe0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a  3_data_count(P).
2dff0 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e  ** will return n
2e000 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69  on-zero if previ
2e010 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ous call to [sql
2e020 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
2e030 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54  turned.** [SQLIT
2e040 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69  E_ROW], except i
2e050 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68  n the case of th
2e060 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d  e [PRAGMA increm
2e070 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a  ental_vacuum].**
2e080 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73   where it always
2e090 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69   returns zero si
2e0a0 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66  nce each step of
2e0b0 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70   that multi-step
2e0c0 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72  .** pragma retur
2e0d0 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  ns 0 columns of 
2e0e0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  data..**.** See 
2e0f0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63  also: [sqlite3_c
2e100 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a  olumn_count()].*
2e110 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61  /.int sqlite3_da
2e120 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  ta_count(sqlite3
2e130 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2e140 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e150 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61  Fundamental Data
2e160 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  types.** KEYWORD
2e170 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
2e180 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c  *.** ^(Every val
2e190 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
2e1a0 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
2e1b0 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
2e1c0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
2e1d0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
2e1e0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
2e1f0 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
2e200 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2e210 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
2e220 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
2e230 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
2e240 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
2e250 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
2e260 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65   are codes for e
2e270 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70  ach of those typ
2e280 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  es..**.** Note t
2e290 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hat the SQLITE_T
2e2a0 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73  EXT constant was
2e2b0 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51   also used in SQ
2e2c0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a  Lite version 2.*
2e2d0 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65  * for a complete
2e2e0 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61  ly different mea
2e2f0 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20  ning.  Software 
2e300 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
2e310 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74  st both.** SQLit
2e320 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  e version 2 and 
2e330 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
2e340 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49   should use SQLI
2e350 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a  TE3_TEXT, not.**
2e360 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
2e370 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2e380 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
2e390 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
2e3a0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2e3b0 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
2e3c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
2e3d0 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
2e3e0 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
2e3f0 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
2e400 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
2e410 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
2e420 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
2e430 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
2e440 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
2e450 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65  EF: Result Value
2e460 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a  s From A Query.*
2e470 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c  * KEYWORDS: {col
2e480 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
2e490 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ions}.**.** Thes
2e4a0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20  e routines form 
2e4b0 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22  the "result set"
2e4c0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
2e4d0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2e4e0 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
2e4f0 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e  tion about a sin
2e500 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
2e510 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73  e current.** res
2e520 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65  ult row of a que
2e530 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63  ry.  ^In every c
2e540 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72  ase the first ar
2e550 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
2e560 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70  ter.** to the [p
2e570 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e580 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67  t] that is being
2e590 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20   evaluated (the 
2e5a0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a  [sqlite3_stmt*].
2e5b0 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75  ** that was retu
2e5c0 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  rned from [sqlit
2e5d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2e5e0 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76   or one of its v
2e5f0 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20  ariants).** and 
2e600 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
2e610 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
2e620 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66   of the column f
2e630 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61  or which informa
2e640 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
2e650 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65  e returned. ^The
2e660 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
2e670 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2e680 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78  et has the index
2e690 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62   0..** ^The numb
2e6a0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2e6b0 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20   the result can 
2e6c0 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
2e6d0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2e6e0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e  column_count()].
2e6f0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
2e700 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
2e710 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70   not currently p
2e720 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20  oint to a valid 
2e730 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a  row, or if the.*
2e740 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69  * column index i
2e750 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
2e760 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e  the result is un
2e770 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73  defined..** Thes
2e780 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f  e routines may o
2e790 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
2e7a0 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  en the most rece
2e7b0 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
2e7c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
2e7d0 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  as returned [SQL
2e7e0 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69  ITE_ROW] and nei
2e7f0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
2e800 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73  _reset()] nor [s
2e810 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2e820 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  )] have been cal
2e830 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79  led subsequently
2e840 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74  ..** If any of t
2e850 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
2e860 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  e called after [
2e870 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2e880 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2e890 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  finalize()] or a
2e8a0 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
2e8b0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
2e8c0 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20  ed.** something 
2e8d0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2e8e0 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73  TE_ROW], the res
2e8f0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2e900 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  ed..** If [sqlit
2e910 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
2e920 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2e930 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2e940 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63  lize()].** are c
2e950 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66  alled from a dif
2e960 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68  ferent thread wh
2e970 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  ile any of these
2e980 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
2e990 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74   pending, then t
2e9a0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
2e9b0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2e9c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
2e9d0 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
2e9e0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ne returns the.*
2e9f0 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
2ea00 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
2ea10 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
2ea20 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
2ea30 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
2ea40 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75  lumn.  ^The retu
2ea50 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
2ea60 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
2ea70 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
2ea80 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
2ea90 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
2eaa0 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
2eab0 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76  TE_NULL].  The v
2eac0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
2ead0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2eae0 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
2eaf0 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
2eb00 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65  no type.** conve
2eb10 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
2eb20 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65  rred as describe
2eb30 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20  d below.  After 
2eb40 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
2eb50 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n,.** the value 
2eb60 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2eb70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2eb80 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
2eb90 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
2eba0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
2ebb0 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
2ebc0 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
2ebd0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
2ebe0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
2ebf0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
2ec00 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
2ec10 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
2ec20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
2ec30 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
2ec40 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
2ec50 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2ec60 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2ec70 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
2ec80 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
2ec90 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2eca0 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
2ecb0 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
2ecc0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63  column_bytes() c
2ecd0 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
2ece0 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61  tring to UTF-8 a
2ecf0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
2ed00 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2ed10 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
2ed20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
2ed30 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
2ed40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2ed50 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  tes() uses.** [s
2ed60 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2ed70 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
2ed80 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
2ed90 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72  F-8 string and r
2eda0 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
2edb0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2edc0 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2edd0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2ede0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
2edf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ee00 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  es() returns zer
2ee10 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  o..**.** ^If the
2ee20 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
2ee30 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  B or UTF-16 stri
2ee40 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
2ee50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2ee60 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  16().** routine 
2ee70 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2ee80 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2ee90 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
2eea0 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2eeb0 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38  esult is a UTF-8
2eec0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
2eed0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2eee0 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a  es16() converts.
2eef0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
2ef00 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e   UTF-16 and then
2ef10 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2ef20 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
2ef30 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2ef40 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
2ef50 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
2ef60 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2ef70 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
2ef80 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
2ef90 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
2efa0 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20  lue to a UTF-16 
2efb0 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2efc0 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
2efd0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2efe0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
2eff0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
2f000 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
2f010 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2f020 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
2f030 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  .**.** ^The valu
2f040 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
2f050 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f060 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20  ytes()] and .** 
2f070 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2f080 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f  bytes16()] do no
2f090 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65  t include the ze
2f0a0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61  ro terminators a
2f0b0 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20  t the end.** of 
2f0c0 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f  the string.  ^Fo
2f0d0 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76  r clarity: the v
2f0e0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
2f0f0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
2f100 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
2f110 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d [sqlite3_colum
2f120 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65  n_bytes16()] are
2f130 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
2f140 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  * bytes in the s
2f150 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e  tring, not the n
2f160 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
2f170 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69  ers..**.** ^Stri
2f180 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
2f190 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f1a0 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ext() and sqlite
2f1b0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2f1c0 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79  ),.** even empty
2f1d0 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c   strings, are al
2f1e0 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
2f1f0 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  ated.  ^The retu
2f200 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d  rn.** value from
2f210 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f220 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72  blob() for a zer
2f230 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73  o-length BLOB is
2f240 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2f250 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65  .**.** ^The obje
2f260 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ct returned by [
2f270 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2f280 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a  alue()] is an.**
2f290 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2f2a0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2f2b0 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65  ect.  An unprote
2f2c0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2f2d0 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79  ue object.** may
2f2e0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
2f2f0 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  th [sqlite3_bind
2f300 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
2f310 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2f320 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
2f330 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
2f340 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2f350 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2f360 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2f370 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
2f380 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
2f390 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
2f3a0 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
2f3b0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
2f3c0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
2f3d0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
2f3e0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
2f3f0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2f400 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68  ytes()], then th
2f410 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2f420 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
2f430 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74  hese routines at
2f440 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74  tempt to convert
2f450 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65   the value where
2f460 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e   appropriate.  ^
2f470 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
2f480 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  if the internal 
2f490 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69  representation i
2f4a0 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65  s FLOAT and a te
2f4b0 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  xt result.** is 
2f4c0 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69  requested, [sqli
2f4d0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2f4e0 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
2f4f0 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68  ly to perform th
2f500 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e.** conversion 
2f510 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
2f520 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  ^(The following 
2f530 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68  table details th
2f540 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a  e conversions.**
2f550 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65   that are applie
2f560 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d:.**.** <blockq
2f570 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
2f580 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
2f590 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c  tr><th> Internal
2f5a0 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65  <br>Type <th> Re
2f5b0 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20  quested<br>Type 
2f5c0 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e  <th>  Conversion
2f5d0 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
2f5e0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e   NULL    <td> IN
2f5f0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73  TEGER   <td> Res
2f600 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e  ult is 0.** <tr>
2f610 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2f620 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2f630 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a  > Result is 0.0.
2f640 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2f650 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  L    <td>   TEXT
2f660 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
2f670 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2f680 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
2f690 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
2f6a0 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
2f6b0 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
2f6c0 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
2f6d0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46  INTEGER  <td>  F
2f6e0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
2f6f0 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65  vert from intege
2f700 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74  r to float.** <t
2f710 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2f720 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2f730 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
2f740 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67  ing of the integ
2f750 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
2f760 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42  NTEGER  <td>   B
2f770 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
2f780 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58   as INTEGER->TEX
2f790 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  T.** <tr><td>  F
2f7a0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOAT   <td> INTE
2f7b0 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
2f7c0 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
2f7d0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2f7e0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2f7f0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
2f800 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
2f810 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
2f820 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
2f830 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  LOB    <td> [CAS
2f840 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74  T] to BLOB.** <t
2f850 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2f860 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2f870 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
2f880 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
2f890 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
2f8a0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b   FLOAT    <td> [
2f8b0 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a  CAST] to REAL.**
2f8c0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
2f8d0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2f8e0 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
2f8f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2f900 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
2f910 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
2f920 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
2f930 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2f940 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2f950 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52  <td> [CAST] to R
2f960 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EAL.** <tr><td> 
2f970 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
2f980 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
2f990 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
2f9a0 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
2f9b0 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
2f9c0 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
2f9d0 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76  * The table abov
2f9e0 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63  e makes referenc
2f9f0 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20  e to standard C 
2fa00 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e  library function
2fa10 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20  s atoi().** and 
2fa20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20  atof().  SQLite 
2fa30 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20  does not really 
2fa40 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69  use these functi
2fa50 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73  ons.  It has its
2fa60 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65  .** own equivale
2fa70 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74  nt internal rout
2fa80 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28  ines.  The atoi(
2fa90 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d  ) and atof() nam
2faa0 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69  es are.** used i
2fab0 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20  n the table for 
2fac0 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61  brevity and beca
2fad0 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d  use they are fam
2fae0 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a  iliar to most.**
2faf0 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a   C programmers..
2fb00 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2fb10 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
2fb20 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
2fb30 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
2fb40 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
2fb50 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2fb60 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
2fb70 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2fb80 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
2fb90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2fba0 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
2fbb0 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
2fbc0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
2fbd0 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
2fbe0 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
2fbf0 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
2fc00 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
2fc10 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
2fc20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2fc30 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
2fc40 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2fc50 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
2fc60 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
2fc70 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
2fc80 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
2fc90 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
2fca0 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
2fcb0 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
2fcc0 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
2fcd0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2fce0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
2fcf0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
2fd00 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2fd10 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
2fd20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2fd30 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
2fd40 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
2fd50 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
2fd60 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
2fd70 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
2fd80 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2fd90 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
2fda0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
2fdb0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
2fdc0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
2fdd0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
2fde0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
2fdf0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
2fe00 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
2fe10 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
2fe20 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
2fe30 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
2fe40 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
2fe50 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
2fe60 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
2fe70 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
2fe80 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
2fe90 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
2fea0 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
2feb0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2fec0 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
2fed0 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
2fee0 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c  r references wil
2fef0 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
2ff00 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
2ff10 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
2ff20 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
2ff30 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
2ff40 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
2ff50 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a  ometimes they.**
2ff60 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c   are not possibl
2ff70 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
2ff80 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
2ff90 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
2ffa0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ted..**.** The s
2ffb0 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73  afest and easies
2ffc0 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f  t to remember po
2ffd0 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b  licy is to invok
2ffe0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
2fff0 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  .** in one of th
30000 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73  e following ways
30010 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
30020 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
30030 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f  umn_text() follo
30040 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
30050 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
30060 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
30070 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
30080 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
30090 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
300a0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
300b0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
300c0 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65  text16() followe
300d0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
300e0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c  umn_bytes16()</l
300f0 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
30100 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
30110 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
30120 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
30130 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69  _text(),.** sqli
30140 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
30150 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ), or sqlite3_co
30160 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
30170 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
30180 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20   result.** into 
30190 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d  the desired form
301a0 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
301b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
301c0 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  ytes() or.** sql
301d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
301e0 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68  s16() to find th
301f0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
30200 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
30210 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71  x calls.** to sq
30220 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30230 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  t() or sqlite3_c
30240 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
30250 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  h calls to.** sq
30260 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
30270 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e  es16(), and do n
30280 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ot mix calls to 
30290 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
302a0 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20  ext16().** with 
302b0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
302c0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
302d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e  .**.** ^The poin
302e0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
302f0 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
30300 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
30310 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
30320 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
30330 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
30340 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
30350 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
30360 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
30370 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
30380 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  d.  ^The memory 
30390 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
303a0 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
303b0 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
303c0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
303d0 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70   Do <b>not</b> p
303e0 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
303f0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
30400 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
30410 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
30420 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
30430 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a  )], etc. into.**
30440 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
30450 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20  ]..**.** ^(If a 
30460 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
30470 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
30480 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61  uring the evalua
30490 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  tion of any.** o
304a0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
304b0 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75  , a default valu
304c0 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  e is returned.  
304d0 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
304e0 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74  e.** is either t
304f0 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68  he integer 0, th
30500 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  e floating point
30510 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20   number 0.0, or 
30520 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
30530 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63  r.  Subsequent c
30540 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
30550 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c  _errcode()] will
30560 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
30570 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a  TE_NOMEM].)^.*/.
30580 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
30590 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
305a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
305b0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
305c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
305d0 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  es(sqlite3_stmt*
305e0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
305f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30600 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
30610 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
30620 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
30630 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73  _column_double(s
30640 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
30650 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
30660 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28  ite3_column_int(
30670 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30680 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
30690 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
306a0 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c  column_int64(sql
306b0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
306c0 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  iCol);.const uns
306d0 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
306e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
306f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30700 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
30710 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
30720 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69  lumn_text16(sqli
30730 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
30740 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
30750 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
30760 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30770 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
30780 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63  value *sqlite3_c
30790 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69  olumn_value(sqli
307a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
307b0 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Col);../*.** CAP
307c0 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41  I3REF: Destroy A
307d0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
307e0 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
307f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
30800 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  nalize() functio
30810 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64  n is called to d
30820 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65  elete a [prepare
30830 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
30840 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
30850 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
30860 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
30870 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20   encountered no 
30880 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20  errors.** or if 
30890 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
308a0 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c   never been eval
308b0 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69  uated, then sqli
308c0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72  te3_finalize() r
308d0 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45  eturns.** SQLITE
308e0 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  _OK.  ^If the mo
308f0 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
30900 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e  tion of statemen
30910 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  t S failed, then
30920 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  .** sqlite3_fina
30930 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20  lize(S) returns 
30940 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  the appropriate 
30950 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a  [error code] or.
30960 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  ** [extended err
30970 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
30980 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
30990 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65  alize(S) routine
309a0 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
309b0 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
309c0 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63  ng.** the life c
309d0 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65  ycle of [prepare
309e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a  d statement] S:.
309f0 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d  ** before statem
30a00 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76  ent S is ever ev
30a10 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a  aluated, after.*
30a20 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61  * one or more ca
30a30 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
30a40 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74  reset()], or aft
30a50 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74  er any call.** t
30a60 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
30a70 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  )] regardless of
30a80 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
30a90 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
30aa0 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65  s.** completed e
30ab0 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  xecution..**.** 
30ac0 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65  ^Invoking sqlite
30ad0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20  3_finalize() on 
30ae0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
30af0 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
30b00 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  op..**.** The ap
30b10 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66  plication must f
30b20 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70  inalize every [p
30b30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30b40 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61  t] in order to a
30b50 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65  void.** resource
30b60 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61   leaks.  It is a
30b70 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20   grievous error 
30b80 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
30b90 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73  ion to try to us
30ba0 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20  e.** a prepared 
30bb0 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
30bc0 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
30bd0 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20  lized.  Any use 
30be0 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a  of a prepared.**
30bf0 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
30c00 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
30c10 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c  alized can resul
30c20 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  t in undefined a
30c30 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  nd.** undesirabl
30c40 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20  e behavior such 
30c50 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64  as segfaults and
30c60 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e   heap corruption
30c70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
30c80 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
30c90 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
30ca0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30cb0 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
30cc0 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
30cd0 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ct.**.** The sql
30ce0 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
30cf0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
30d00 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
30d10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
30d20 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
30d30 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
30d40 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
30d50 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
30d60 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d   ^Any SQL statem
30d70 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68  ent variables th
30d80 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f  at had values bo
30d90 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e  und to them usin
30da0 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
30db0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
30dc0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41  lite3_bind_*() A
30dd0 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72  PI] retain their
30de0 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20   values..** Use 
30df0 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
30e00 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65  indings()] to re
30e10 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73  set the bindings
30e20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
30e30 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
30e40 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
30e50 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
30e60 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62  tatement] S.** b
30e70 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
30e80 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
30e90 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ram..**.** ^If t
30ea0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
30eb0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
30ec0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
30ed0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
30ee0 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
30ef0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
30f00 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
30f10 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c  ],.** or if [sql
30f20 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
30f30 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
30f40 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
30f50 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  .** then [sqlite
30f60 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
30f70 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
30f80 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
30f90 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
30fa0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
30fb0 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
30fc0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30fd0 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
30fe0 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
30ff0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
31000 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
31010 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
31020 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
31030 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
31040 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
31050 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
31060 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
31070 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33   of any [sqlite3
31080 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69  _bind_blob|bindi
31090 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65  ngs] on the [pre
310a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
310b0 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74   S..*/.int sqlit
310c0 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33  e3_reset(sqlite3
310d0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
310e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
310f0 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69  Create Or Redefi
31100 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73  ne SQL Functions
31110 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
31120 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
31130 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45   routines}.** KE
31140 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
31150 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
31160 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45   function}.** KE
31170 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
31180 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
31190 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
311a0 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
311b0 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79  ns (collectively
311c0 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74   known as "funct
311d0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
311e0 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75  tines").** are u
311f0 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66  sed to add SQL f
31200 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
31210 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64  egates or to red
31220 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69  efine the behavi
31230 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e  or.** of existin
31240 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  g SQL functions 
31250 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  or aggregates.  
31260 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65  The only differe
31270 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20  nces between.** 
31280 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
31290 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f  re the text enco
312a0 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f  ding expected fo
312b0 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  r.** the second 
312c0 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e  parameter (the n
312d0 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ame of the funct
312e0 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65  ion being create
312f0 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72  d).** and the pr
31300 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63  esence or absenc
31310 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f  e of a destructo
31320 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a  r callback for.*
31330 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
31340 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a  n data pointer..
31350 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
31360 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
31370 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
31380 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68  ection] to which
31390 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63   the SQL.** func
313a0 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64  tion is to be ad
313b0 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70  ded.  ^If an app
313c0 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f  lication uses mo
313d0 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61  re than one data
313e0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
313f0 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74  on then applicat
31400 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
31410 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62  functions must b
31420 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61  e added.** to ea
31430 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
31440 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c  ection separatel
31450 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  y..**.** ^The se
31460 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
31470 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
31480 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
31490 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a  o be created or.
314a0 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e  ** redefined.  ^
314b0 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  The length of th
314c0 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65  e name is limite
314d0 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69  d to 255 bytes i
314e0 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70  n a UTF-8.** rep
314f0 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63  resentation, exc
31500 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65  lusive of the ze
31510 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro-terminator.  
31520 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e  ^Note that the n
31530 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69  ame.** length li
31540 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20  mit is in UTF-8 
31550 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61  bytes, not chara
31560 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36  cters nor UTF-16
31570 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e   bytes.  .** ^An
31580 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65  y attempt to cre
31590 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  ate a function w
315a0 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d  ith a longer nam
315b0 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74  e.** will result
315c0 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   in [SQLITE_MISU
315d0 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e  SE] being return
315e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  ed..**.** ^The t
315f0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28  hird parameter (
31600 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20  nArg).** is the 
31610 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
31620 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c  nts that the SQL
31630 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
31640 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e  aggregate takes.
31650 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65   ^If this parame
31660 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ter is -1, then 
31670 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
31680 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
31690 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75   may take any nu
316a0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
316b0 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  s between 0 and 
316c0 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74  the limit.** set
316d0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   by [sqlite3_lim
316e0 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  it]([SQLITE_LIMI
316f0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29  T_FUNCTION_ARG])
31700 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a  .  If the third.
31710 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ** parameter is 
31720 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20  less than -1 or 
31730 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37  greater than 127
31740 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
31750 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e  or is.** undefin
31760 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
31770 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c  ourth parameter,
31780 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69   eTextRep, speci
31790 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51  fies what.** [SQ
317a0 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74  LITE_UTF8 | text
317b0 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20   encoding] this 
317c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65  SQL function pre
317d0 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20  fers for.** its 
317e0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65  parameters.  The
317f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
31800 75 6c 64 20 73 65 74 20 74 68 69 73 20 70 61 72  uld set this par
31810 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51  ameter to.** [SQ
31820 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66  LITE_UTF16LE] if
31830 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d   the function im
31840 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76  plementation inv
31850 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  okes .** [sqlite
31860 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
31870 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c  ()] on an input,
31880 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
31890 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69  6BE] if the.** i
318a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
318b0 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76  vokes [sqlite3_v
318c0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d  alue_text16be()]
318d0 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72   on an input, or
318e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
318f0 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76  6] if [sqlite3_v
31900 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69  alue_text16()] i
31910 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49  s used, or [SQLI
31920 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65  TE_UTF8].** othe
31930 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d  rwise.  ^The sam
31940 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d  e SQL function m
31950 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
31960 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
31970 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65  using.** differe
31980 6e 74 20 70 72 65 66 65 72 72 65 64 20 74 65 78  nt preferred tex
31990 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74  t encodings, wit
319a0 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c  h different impl
319b0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a  ementations for.
319c0 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67  ** each encoding
319d0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69  ..** ^When multi
319e0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
319f0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
31a00 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
31a10 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
31a20 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
31a30 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
31a40 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
31a50 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
31a60 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rsion..**.** ^Th
31a70 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
31a80 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c  er may optionall
31a90 79 20 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b  y be ORed with [
31aa0 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
31ab0 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e  STIC].** to sign
31ac0 61 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e 63  al that the func
31ad0 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73  tion will always
31ae0 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65   return the same
31af0 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a   result given.**
31b00 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73   the same inputs
31b10 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65   within a single
31b20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
31b30 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69   Most SQL functi
31b40 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72  ons are.** deter
31b50 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62  ministic.  The b
31b60 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28  uilt-in [random(
31b70 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  )] SQL function 
31b80 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  is an example of
31b90 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74   a.** function t
31ba0 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72  hat is not deter
31bb0 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53  ministic.  The S
31bc0 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e  QLite query plan
31bd0 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a  ner is able to.*
31be0 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69  * perform additi
31bf0 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f  onal optimizatio
31c00 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73  ns on determinis
31c10 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73  tic functions, s
31c20 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20  o use.** of the 
31c30 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e  [SQLITE_DETERMIN
31c40 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72  ISTIC] flag is r
31c50 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65  ecommended where
31c60 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a   possible..**.**
31c70 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72   ^(The fifth par
31c80 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
31c90 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
31ca0 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
31cb0 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75  ion of the.** fu
31cc0 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
31cd0 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
31ce0 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71  ointer using [sq
31cf0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
31d00 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  )].)^.**.** ^The
31d10 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20   sixth, seventh 
31d20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d  and eighth param
31d30 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
31d40 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
31d50 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
31d60 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
31d70 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
31d80 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
31d90 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
31da0 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c  gregate. ^A scal
31db0 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
31dc0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
31dd0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
31de0 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
31df0 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70  ack only; NULL p
31e00 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20  ointers must be 
31e10 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53  passed as the xS
31e20 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a  tep and xFinal.*
31e30 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41  * parameters. ^A
31e40 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
31e50 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
31e60 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
31e70 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20  ion of xStep.** 
31e80 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
31e90 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74  ULL pointer must
31ea0 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78   be passed for x
31eb0 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65  Func. ^To delete
31ec0 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20   an existing.** 
31ed0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  SQL function or 
31ee0 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20  aggregate, pass 
31ef0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f  NULL pointers fo
31f00 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
31f10 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
31f20 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  s..**.** ^(If th
31f30 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  e ninth paramete
31f40 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
31f50 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
31f60 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a  ) is not NULL,.*
31f70 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73  * then it is des
31f80 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20  tructor for the 
31f90 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
31fa0 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68   pointer. .** Th
31fb0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
31fc0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
31fd0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c   function is del
31fe0 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20  eted, either by 
31ff0 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61  being.** overloa
32000 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20  ded or when the 
32010 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32020 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a  ion closes.)^.**
32030 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
32040 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64   is also invoked
32050 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a   if the call to.
32060 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
32070 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
32080 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20  fails..** ^When 
32090 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63  the destructor c
320a0 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74  allback of the t
320b0 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  enth parameter i
320c0 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a  s invoked, it.**
320d0 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e   is passed a sin
320e0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
320f0 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ch is a copy of 
32100 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
32110 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72  data .** pointer
32120 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66   which was the f
32130 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  ifth parameter t
32140 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
32150 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a  _function_v2()..
32160 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72  **.** ^It is per
32170 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
32180 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
32190 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
321a0 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
321b0 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
321c0 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
321d0 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
321e0 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
321f0 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
32200 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
32210 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
32220 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75    ^SQLite will u
32230 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
32240 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f  entation that mo
32250 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
32260 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
32270 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
32280 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
32290 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d    ^A function im
322a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
322b0 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  h a non-negative
322c0 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74  .** nArg paramet
322d0 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d  er is a better m
322e0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
322f0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
32300 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65  ion with.** a ne
32310 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41  gative nArg.  ^A
32320 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
32330 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65  the preferred te
32340 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d  xt encoding.** m
32350 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62  atches the datab
32360 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
32370 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63  a better.** matc
32380 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
32390 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
323a0 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
323b0 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74  t.  .** ^A funct
323c0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
323d0 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
323e0 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46  e is between UTF
323f0 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65  16le and UTF16be
32400 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20  .** is a closer 
32410 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
32420 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
32430 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
32440 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65  nce is.** betwee
32450 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36  n UTF8 and UTF16
32460 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69  ..**.** ^Built-i
32470 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  n functions may 
32480 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79  be overloaded by
32490 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
324a0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
324b0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70  ns..**.** ^An ap
324c0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
324d0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65  d function is pe
324e0 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20  rmitted to call 
324f0 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
32500 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77  interfaces.  How
32510 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73  ever, such calls
32520 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f   must not.** clo
32530 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
32540 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66  connection nor f
32550 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74  inalize or reset
32560 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a   the prepared.**
32570 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68   statement in wh
32580 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ich the function
32590 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
325a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
325b0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73  te_function(.  s
325c0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
325d0 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
325e0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
325f0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
32600 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
32610 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
32620 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
32630 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
32640 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
32650 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
32660 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
32670 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
32680 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
32690 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
326a0 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
326b0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
326c0 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  on16(.  sqlite3 
326d0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  *db,.  const voi
326e0 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
326f0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
32700 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
32710 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
32720 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
32730 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
32740 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
32750 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
32760 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
32770 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
32780 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
32790 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
327a0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
327b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
327c0 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a  te_function_v2(.
327d0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
327e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
327f0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
32800 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
32810 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
32820 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
32830 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
32840 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
32850 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
32860 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
32870 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
32880 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
32890 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
328a0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
328b0 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  text*),.  void(*
328c0 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
328d0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
328e0 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69  REF: Text Encodi
328f0 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ngs.**.** These 
32900 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20  constant define 
32910 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68  integer codes th
32920 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65  at represent the
32930 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74   various.** text
32940 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f   encodings suppo
32950 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  rted by SQLite..
32960 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
32970 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20  E_UTF8          
32980 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d   1    /* IMP: R-
32990 33 37 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23  37514-35566 */.#
329a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
329b0 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 20 20  F16LE        2  
329c0 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37    /* IMP: R-0337
329d0 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65 66 69  1-37637 */.#defi
329e0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42  ne SQLITE_UTF16B
329f0 45 20 20 20 20 20 20 20 20 33 20 20 20 20 2f 2a  E        3    /*
32a00 20 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33 34   IMP: R-51971-34
32a10 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  154 */.#define S
32a20 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
32a30 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
32a40 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
32a50 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
32a60 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
32a70 20 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72      5    /* Depr
32a80 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e  ecated */.#defin
32a90 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
32aa0 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
32ab0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
32ac0 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
32ad0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32ae0 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73  : Function Flags
32af0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
32b00 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 4f 52  stants may be OR
32b10 65 64 20 74 6f 67 65 74 68 65 72 20 77 69 74 68  ed together with
32b20 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
32b30 5f 55 54 46 38 20 7c 20 70 72 65 66 65 72 72 65  _UTF8 | preferre
32b40 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  d text encoding]
32b50 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61   as the fourth a
32b60 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73  rgument.** to [s
32b70 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
32b80 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69  nction()], [sqli
32b90 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32ba0 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
32bb0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32bc0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a  function_v2()]..
32bd0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
32be0 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 20  E_DETERMINISTIC 
32bf0 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20     0x800../*.** 
32c00 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63  CAPI3REF: Deprec
32c10 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ated Functions.*
32c20 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a  * DEPRECATED.**.
32c30 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
32c40 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74  ns are [deprecat
32c50 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74  ed].  In order t
32c60 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61  o maintain.** ba
32c70 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
32c80 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72  ility with older
32c90 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e   code, these fun
32ca0 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
32cb0 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72  .** to be suppor
32cc0 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ted.  However, n
32cd0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
32ce0 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20  should avoid.** 
32cf0 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65  the use of these
32d00 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20   functions.  To 
32d10 65 6e 63 6f 75 72 61 67 65 20 70 72 6f 67 72 61  encourage progra
32d20 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69 64 0a 2a  mmers to avoid.*
32d30 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * these function
32d40 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f 74 20 65  s, we will not e
32d50 78 70 6c 61 69 6e 20 77 68 61 74 20 74 68 65 79  xplain what they
32d60 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20   do..*/.#ifndef 
32d70 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52  SQLITE_OMIT_DEPR
32d80 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45  ECATED.SQLITE_DE
32d90 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
32da0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
32db0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ount(sqlite3_con
32dc0 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  text*);.SQLITE_D
32dd0 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
32de0 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71  lite3_expired(sq
32df0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
32e00 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
32e10 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e  int sqlite3_tran
32e20 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  sfer_bindings(sq
32e30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c  lite3_stmt*, sql
32e40 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
32e50 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
32e60 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61  nt sqlite3_globa
32e70 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b  l_recover(void);
32e80 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
32e90 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  ED void sqlite3_
32ea0 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76  thread_cleanup(v
32eb0 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  oid);.SQLITE_DEP
32ec0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
32ed0 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
32ee0 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73  (void(*)(void*,s
32ef0 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74  qlite3_int64,int
32f00 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  ),.             
32f10 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73           void*,s
32f20 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23  qlite3_int64);.#
32f30 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
32f40 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67  I3REF: Obtaining
32f50 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61   SQL Function Pa
32f60 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a  rameter Values.*
32f70 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75  *.** The C-langu
32f80 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  age implementati
32f90 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69  on of SQL functi
32fa0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
32fb0 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20  es uses.** this 
32fc0 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65  set of interface
32fd0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63   routines to acc
32fe0 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65  ess the paramete
32ff0 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74  r values on.** t
33000 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  he function or a
33010 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ggregate..**.** 
33020 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73  The xFunc (for s
33030 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29  calar functions)
33040 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61   or xStep (for a
33050 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d  ggregates) param
33060 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c  eters.** to [sql
33070 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33080 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
33090 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
330a0 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66  tion16()].** def
330b0 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  ine callbacks th
330c0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
330d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
330e0 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a  nd aggregates..*
330f0 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65  * The 3rd parame
33100 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c  ter to these cal
33110 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72  lbacks is an arr
33120 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
33130 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20  o.** [protected 
33140 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
33150 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69  bjects.  There i
33160 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76  s one [sqlite3_v
33170 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
33180 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74  .** each paramet
33190 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  er to the SQL fu
331a0 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72  nction.  These r
331b0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
331c0 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76   to.** extract v
331d0 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  alues from the [
331e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
331f0 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  bjects..**.** Th
33200 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
33210 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f  k only with [pro
33220 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
33230 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
33240 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
33250 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69   use these routi
33260 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f  nes on an [unpro
33270 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
33280 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  alue].** object 
33290 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
332a0 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
332b0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
332c0 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c  ines work just l
332d0 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ike the correspo
332e0 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63  nding [column ac
332f0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a  cess functions].
33300 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 74  ** except that t
33310 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
33320 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f  ke a single [pro
33330 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
33340 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
33350 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
33360 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  of a [sqlite3_st
33370 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
33380 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
33390 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
333a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
333b0 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
333c0 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
333d0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  a UTF-16 string.
333e0 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
333f0 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
33400 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
33410 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
33420 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
33430 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
33440 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20  alue_text16le() 
33450 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78  interfaces.** ex
33460 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72  tract UTF-16 str
33470 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69  ings as big-endi
33480 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e  an and little-en
33490 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
334a0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  y..**.** ^(The s
334b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
334c0 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
334d0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
334e0 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
334f0 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
33500 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
33510 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
33520 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
33530 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
33540 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
33550 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
33560 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
33570 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
33580 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
33590 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
335a0 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
335b0 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74  r.** words, if t
335c0 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74  he value is a st
335d0 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20  ring that looks 
335e0 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a  like a number).*
335f0 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65  * then the conve
33600 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
33610 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ed.  Otherwise n
33620 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
33630 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  urs..** The [SQL
33640 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
33650 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
33660 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
33670 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c  rned.)^.**.** Pl
33680 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75  ease pay particu
33690 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f  lar attention to
336a0 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74   the fact that t
336b0 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72  he pointer retur
336c0 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
336d0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
336e0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
336f0 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
33700 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
33710 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
33720 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
33730 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
33740 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
33750 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
33760 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
33770 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
33780 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
33790 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
337a0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
337b0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ()]..**.** These
337c0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
337d0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
337e0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
337f0 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
33800 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
33810 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ed the [sqlite3_
33820 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65  value*] paramete
33830 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  rs..*/.const voi
33840 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
33850 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
33860 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
33870 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
33880 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
33890 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
338a0 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
338b0 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c  3_value*);.doubl
338c0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
338d0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76  double(sqlite3_v
338e0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
338f0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
33900 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73  lite3_value*);.s
33910 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
33920 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
33930 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
33940 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
33950 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
33960 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
33970 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
33980 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
33990 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
339a0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
339b0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
339c0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
339d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
339e0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
339f0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
33a00 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
33a10 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
33a20 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
33a30 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
33a40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
33a50 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
33a60 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
33a70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
33a80 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
33a90 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a  unction Context.
33aa0 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61  **.** Implementa
33ab0 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61  tions of aggrega
33ac0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
33ad0 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75   use this.** rou
33ae0 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  tine to allocate
33af0 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72   memory for stor
33b00 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e  ing their state.
33b10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
33b20 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74  t time the sqlit
33b30 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
33b40 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
33b50 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20  e is called .** 
33b60 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
33b70 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
33b80 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ion, SQLite.** a
33b90 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65  llocates N of me
33ba0 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74  mory, zeroes out
33bb0 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e   that memory, an
33bc0 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
33bd0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65  ter.** to the ne
33be0 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65  w memory. ^On se
33bf0 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
33c00 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ent calls to.** 
33c10 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
33c20 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20  e_context() for 
33c30 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
33c40 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
33c50 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d  ance,.** the sam
33c60 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75  e buffer is retu
33c70 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61  rned.  Sqlite3_a
33c80 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
33c90 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a  () is normally.*
33ca0 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f  * called once fo
33cb0 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  r each invocatio
33cc0 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63  n of the xStep c
33cd0 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e  allback and then
33ce0 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d   one.** last tim
33cf0 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61  e when the xFina
33d00 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  l callback is in
33d10 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e  voked.  ^(When n
33d20 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20  o rows match.** 
33d30 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65  an aggregate que
33d40 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20  ry, the xStep() 
33d50 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
33d60 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
33d70 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  on.** implementa
33d80 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61  tion is never ca
33d90 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28  lled and xFinal(
33da0 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63  ) is called exac
33db0 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20  tly once..** In 
33dc0 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c  those cases, sql
33dd0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
33de0 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62  ontext() might b
33df0 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  e called for the
33e00 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66  .** first time f
33e10 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61  rom within xFina
33e20 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  l().)^.**.** ^Th
33e30 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
33e40 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
33e50 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
33e60 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
33e70 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63  .** when first c
33e80 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65  alled if N is le
33e90 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
33ea0 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61   to zero or if a
33eb0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
33ec0 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ate error occurs
33ed0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d  ..**.** ^(The am
33ee0 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c  ount of space al
33ef0 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
33f00 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
33f10 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20  text(C,N) is.** 
33f20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68  determined by th
33f30 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  e N parameter on
33f40 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75   first successfu
33f50 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e  l call.  Changin
33f60 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  g the.** value o
33f70 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e  f N in subsequen
33f80 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
33f90 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
33fa0 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20  ext() within.** 
33fb0 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
33fc0 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
33fd0 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65  ance will not re
33fe0 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a  size the memory.
33ff0 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e  ** allocation.)^
34000 20 20 57 69 74 68 69 6e 20 74 68 65 20 78 46 69    Within the xFi
34010 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74  nal callback, it
34020 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f   is customary to
34030 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63   set.** N=0 in c
34040 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
34050 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
34060 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e  t(C,N) so that n
34070 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20  o .** pointless 
34080 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
34090 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20  ns occur..**.** 
340a0 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69  ^SQLite automati
340b0 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
340c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64  memory allocated
340d0 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   by .** sqlite3_
340e0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
340f0 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67  t() when the agg
34100 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e  regate query con
34110 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
34120 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
34130 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79  r must be a copy
34140 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
34150 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51  te3_context | SQ
34160 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65  L function conte
34170 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20  xt] that is the 
34180 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a  first parameter.
34190 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20  ** to the xStep 
341a0 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
341b0 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20  ck routine that 
341c0 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61  implements the a
341d0 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63  ggregate.** func
341e0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
341f0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
34200 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
34210 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
34220 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67  which.** the agg
34230 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
34240 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
34250 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
34260 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
34270 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
34280 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29  xt*, int nBytes)
34290 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
342a0 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72  F: User Data For
342b0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
342c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73   ^The sqlite3_us
342d0 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66  er_data() interf
342e0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
342f0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
34300 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68  nter that was th
34310 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61  e pUserData para
34320 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70  meter (the 5th p
34330 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
34340 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
34350 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
34360 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
34370 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
34380 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
34390 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
343a0 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
343b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
343c0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ned function..**
343d0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
343e0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
343f0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
34400 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
34410 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34420 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
34430 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
34440 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
34450 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33  ser_data(sqlite3
34460 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
34470 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
34480 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
34490 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
344a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
344b0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
344c0 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  dle() interface 
344d0 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
344e0 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
344f0 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
34500 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
34510 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
34520 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
34530 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
34540 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
34550 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
34560 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
34570 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
34580 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
34590 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
345a0 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
345b0 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  tion..*/.sqlite3
345c0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   *sqlite3_contex
345d0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  t_db_handle(sqli
345e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
345f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34600 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
34610 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68  ry Data.**.** Th
34620 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  ese functions ma
34630 79 20 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f  y be used by (no
34640 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53 51 4c  n-aggregate) SQL
34650 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a   functions to.**
34660 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64   associate metad
34670 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ata with argumen
34680 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65  t values. If the
34690 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70   same value is p
346a0 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74  assed to.** mult
346b0 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73  iple invocations
346c0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c   of the same SQL
346d0 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67   function during
346e0 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e   query execution
346f0 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20  , under.** some 
34700 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68  circumstances th
34710 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74  e associated met
34720 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65  adata may be pre
34730 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d  served.  An exam
34740 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20  ple.** of where 
34750 74 68 69 73 20 6d 69 67 68 74 20 62 65 20 75 73  this might be us
34760 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72 65 67  eful is in a reg
34770 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
34780 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63  matching.** func
34790 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c  tion. The compil
347a0 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ed version of th
347b0 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
347c0 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f 72  sion can be stor
347d0 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74  ed as.** metadat
347e0 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
347f0 68 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74  h the pattern st
34800 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20  ring.  .** Then 
34810 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 70  as long as the p
34820 61 74 74 65 72 6e 20 73 74 72 69 6e 67 20 72 65  attern string re
34830 6d 61 69 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a  mains the same,.
34840 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20  ** the compiled 
34850 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
34860 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64  on can be reused
34870 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20   on multiple.** 
34880 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
34890 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
348a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
348b0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
348c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
348d0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
348e0 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a  o the metadata.*
348f0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20  * associated by 
34900 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
34910 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69  auxdata() functi
34920 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  on with the Nth 
34930 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75  argument.** valu
34940 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  e to the applica
34950 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
34960 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65  ction. ^If there
34970 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a   is no metadata.
34980 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
34990 74 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  th the function 
349a0 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 20 73  argument, this s
349b0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
349c0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  ta() interface.*
349d0 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  * returns a NULL
349e0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
349f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74  ^The sqlite3_set
34a00 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
34a10 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65  ) interface save
34a20 73 20 50 20 61 73 20 6d 65 74 61 64 61 74 61 20  s P as metadata 
34a30 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20  for the N-th.** 
34a40 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
34a50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
34a60 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e  ned function.  ^
34a70 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  Subsequent.** ca
34a80 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67  lls to sqlite3_g
34a90 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 20  et_auxdata(C,N) 
34aa0 72 65 74 75 72 6e 20 50 20 66 72 6f 6d 20 74 68  return P from th
34ab0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a  e most recent.**
34ac0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
34ad0 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61  data(C,N,P,X) ca
34ae0 6c 6c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61  ll if the metada
34af0 74 61 20 69 73 20 73 74 69 6c 6c 20 76 61 6c 69  ta is still vali
34b00 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20  d or.** NULL if 
34b10 74 68 65 20 6d 65 74 61 64 61 74 61 20 68 61 73  the metadata has
34b20 20 62 65 65 6e 20 64 69 73 63 61 72 64 65 64 2e   been discarded.
34b30 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61 63 68 20  .** ^After each 
34b40 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
34b50 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
34b60 50 2c 58 29 20 77 68 65 72 65 20 58 20 69 73 20  P,X) where X is 
34b70 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c  not NULL,.** SQL
34b80 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
34b90 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 66  the destructor f
34ba0 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 20 70  unction X with p
34bb0 61 72 61 6d 65 74 65 72 20 50 20 65 78 61 63 74  arameter P exact
34bc0 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e  ly.** once, when
34bd0 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73   the metadata is
34be0 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53   discarded..** S
34bf0 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f  QLite is free to
34c00 20 64 69 73 63 61 72 64 20 74 68 65 20 6d 65 74   discard the met
34c10 61 64 61 74 61 20 61 74 20 61 6e 79 20 74 69 6d  adata at any tim
34c20 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75  e, including: <u
34c30 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20  l>.** <li> when 
34c40 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
34c50 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
34c60 65 74 65 72 20 63 68 61 6e 67 65 73 2c 20 6f 72  eter changes, or
34c70 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73  .** <li> when [s
34c80 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
34c90 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
34ca0 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
34cb0 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  d for the.**    
34cc0 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c    SQL statement,
34cd0 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e   or.** <li> when
34ce0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
34cf0 64 61 74 61 28 29 20 69 73 20 69 6e 76 6f 6b 65  data() is invoke
34d00 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 65 20 73  d again on the s
34d10 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 6f  ame parameter, o
34d20 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67  r.** <li> during
34d30 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 71   the original sq
34d40 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
34d50 61 28 29 20 63 61 6c 6c 20 77 68 65 6e 20 61 20  a() call when a 
34d60 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20  memory .**      
34d70 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
34d80 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e   occurs. </ul>)^
34d90 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20  .**.** Note the 
34da0 6c 61 73 74 20 62 75 6c 6c 65 74 20 69 6e 20 70  last bullet in p
34db0 61 72 74 69 63 75 6c 61 72 2e 20 20 54 68 65 20  articular.  The 
34dc0 64 65 73 74 72 75 63 74 6f 72 20 58 20 69 6e 20  destructor X in 
34dd0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  .** sqlite3_set_
34de0 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
34df0 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
34e00 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
34e10 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69  fore the.** sqli
34e20 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
34e30 29 20 69 6e 74 65 72 66 61 63 65 20 65 76 65 6e  ) interface even
34e40 20 72 65 74 75 72 6e 73 2e 20 20 48 65 6e 63 65   returns.  Hence
34e50 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
34e60 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64  data().** should
34e70 20 62 65 20 63 61 6c 6c 65 64 20 6e 65 61 72 20   be called near 
34e80 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
34e90 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
34ea0 74 61 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a  tation and the.*
34eb0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  * function imple
34ec0 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
34ed0 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75 73   not make any us
34ee0 65 20 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a 20  e of P after.** 
34ef0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
34f00 61 74 61 28 29 20 68 61 73 20 62 65 65 6e 20 63  ata() has been c
34f10 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  alled..**.** ^(I
34f20 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61  n practice, meta
34f30 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65  data is preserve
34f40 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69  d between functi
34f50 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20  on calls for.** 
34f60 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
34f70 65 72 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d  ers that are com
34f80 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61  pile-time consta
34f90 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c  nts, including l
34fa0 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
34fb0 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73   and [parameters
34fc0 5d 20 61 6e 64 20 65 78 70 72 65 73 73 69 6f 6e  ] and expression
34fd0 73 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20  s composed from 
34fe0 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a  the same.)^.**.*
34ff0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
35000 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
35010 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
35020 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
35030 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
35040 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
35050 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67  .void *sqlite3_g
35060 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
35070 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
35080 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65   N);.void sqlite
35090 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_set_auxdata(sq
350a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
350b0 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f  int N, void*, vo
350c0 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  id (*)(void*));.
350d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
350e0 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69  : Constants Defi
350f0 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73  ning Special Des
35100 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72  tructor Behavior
35110 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
35120 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20   special values 
35130 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74  for the destruct
35140 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  or that is passe
35150 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
35160 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f  inal argument to
35170 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
35180 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
35190 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  lob()].  ^If the
351a0 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61   destructor.** a
351b0 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54  rgument is SQLIT
351c0 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61  E_STATIC, it mea
351d0 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
351e0 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63  ent pointer is c
351f0 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77  onstant.** and w
35200 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65  ill never change
35210 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e  .  It does not n
35220 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f  eed to be destro
35230 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51  yed.  ^The.** SQ
35240 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76  LITE_TRANSIENT v
35250 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20  alue means that 
35260 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c  the content will
35270 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69   likely change i
35280 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75  n.** the near fu
35290 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51  ture and that SQ
352a0 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65  Lite should make
352b0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
352c0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
352d0 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72  content before r
352e0 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
352f0 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e  The typedef is n
35300 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b  ecessary to work
35310 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73   around problems
35320 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43   in certain.** C
35330 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f  ++ compilers..*/
35340 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
35350 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
35360 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b  or_type)(void*);
35370 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
35380 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71  STATIC      ((sq
35390 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
353a0 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65  _type)0).#define
353b0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
353c0 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65  T   ((sqlite3_de
353d0 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31  structor_type)-1
353e0 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
353f0 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52  F: Setting The R
35400 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20  esult Of An SQL 
35410 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54  Function.**.** T
35420 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
35430 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46  e used by the xF
35440 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  unc or xFinal ca
35450 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20  llbacks that.** 
35460 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75  implement SQL fu
35470 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
35480 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20  egates.  See.** 
35490 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
354a0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
354b0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
354c0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
354d0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
354e0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
354f0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
35500 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63  ns work very muc
35510 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61  h like the [para
35520 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66  meter binding] f
35530 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63  amily of.** func
35540 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69  tions used to bi
35550 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
35560 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  t parameters in 
35570 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
35580 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f  nts..** Refer to
35590 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65   the [SQL parame
355a0 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  ter] documentati
355b0 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
355c0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
355d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
355e0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20  3_result_blob() 
355f0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
35600 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
35610 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
35620 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
35630 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42  n to be the BLOB
35640 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69   whose content i
35650 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20  s pointed.** to 
35660 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
35670 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63  rameter and whic
35680 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e  h is N bytes lon
35690 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  g where N is the
356a0 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
356b0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
356c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
356d0 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  eroblob() interf
356e0 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73  aces set the res
356f0 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
35700 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
35710 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
35720 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69   a BLOB containi
35730 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62  ng all zero.** b
35740 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73  ytes and N bytes
35750 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20   in size, where 
35760 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  N is the value o
35770 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
35780 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
35790 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
357a0 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  ouble() interfac
357b0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
357c0 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
357d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
357e0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
357f0 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
35800 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
35810 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61  .** by its 2nd a
35820 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
35830 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
35840 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
35850 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35860 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
35870 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
35880 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
35890 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
358a0 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a   an exception..*
358b0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
358c0 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  he string pointe
358d0 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32  d to by the.** 2
358e0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
358f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35900 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65  rror() or sqlite
35910 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
35920 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78  ().** as the tex
35930 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65  t of an error me
35940 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20  ssage.  ^SQLite 
35950 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65  interprets the e
35960 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
35970 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
35980 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
35990 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51  () as UTF-8. ^SQ
359a0 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  Lite.** interpre
359b0 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72  ts the string fr
359c0 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
359d0 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55  t_error16() as U
359e0 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a  TF-16 in native.
359f0 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20  ** byte order.  
35a00 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
35a10 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
35a20 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
35a30 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
35a40 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
35a50 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65   is negative the
35a60 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61  n SQLite takes a
35a70 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
35a80 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20  essage all text 
35a90 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  up through the f
35aa0 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
35ab0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
35ac0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
35ad0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
35ae0 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20  t_error() or.** 
35af0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35b00 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d  rror16() is non-
35b10 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
35b20 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20  Lite takes that 
35b30 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e  many.** bytes (n
35b40 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66  ot characters) f
35b50 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
35b60 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72  meter as the err
35b70 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e  or message..** ^
35b80 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
35b90 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
35ba0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35bb0 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  ror16().** routi
35bc0 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61  nes make a priva
35bd0 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65  te copy of the e
35be0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
35bf0 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79  t before.** they
35c00 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c   return.  Hence,
35c10 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
35c20 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f  ction can deallo
35c30 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66  cate or.** modif
35c40 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72  y the text after
35c50 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74   they return wit
35c60 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54  hout harm..** ^T
35c70 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35c80 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
35c90 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
35ca0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
35cb0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
35cc0 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
35cd0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
35ce0 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79  a function.  ^By
35cf0 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65   default,.** the
35d00 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53   error code is S
35d10 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41  QLITE_ERROR.  ^A
35d20 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
35d30 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
35d40 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
35d50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35d60 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73  error16() resets
35d70 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
35d80 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  to SQLITE_ERROR.
35d90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35da0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
35db0 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66  _toobig() interf
35dc0 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
35dd0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a  e to throw an.**
35de0 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e   error indicatin
35df0 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20  g that a string 
35e00 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c  or BLOB is too l
35e10 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ong to represent
35e20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
35e30 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35e40 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66  r_nomem() interf
35e50 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
35e60 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a  e to throw an.**
35e70 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e   error indicatin
35e80 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20  g that a memory 
35e90 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65  allocation faile
35ea0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
35eb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
35ec0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
35ed0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
35ee0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
35ef0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
35f00 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
35f10 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65  the 32-bit signe
35f20 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
35f30 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
35f40 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
35f50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
35f60 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
35f70 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
35f80 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
35f90 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
35fa0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
35fb0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
35fc0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
35fd0 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
35fe0 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
35ff0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
36000 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36010 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
36020 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
36030 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
36040 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
36050 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
36060 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
36070 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
36080 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71  esult_text(), sq
36090 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
360a0 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  t16(),.** sqlite
360b0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
360c0 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  e(), and sqlite3
360d0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
360e0 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
360f0 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20   set the return 
36100 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70  value of the app
36110 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36120 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
36130 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  ** a text string
36140 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73   which is repres
36150 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20  ented as UTF-8, 
36160 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
36170 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46  te order,.** UTF
36180 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61  -16 little endia
36190 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
361a0 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74   endian, respect
361b0 69 76 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20 73  ively..** ^The s
361c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
361d0 78 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65  xt64() interface
361e0 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
361f0 20 76 61 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a 20   value of an.** 
36200 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
36210 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
36220 62 65 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  be a text string
36230 20 69 6e 20 61 6e 20 65 6e 63 6f 64 69 6e 67 0a   in an encoding.
36240 2a 2a 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ** specified by 
36250 74 68 65 20 66 69 66 74 68 20 28 61 6e 64 20 6c  the fifth (and l
36260 61 73 74 29 20 70 61 72 61 6d 65 74 65 72 2c 20  ast) parameter, 
36270 77 68 69 63 68 20 6d 75 73 74 20 62 65 20 6f 6e  which must be on
36280 65 0a 2a 2a 20 6f 66 20 5b 53 51 4c 49 54 45 5f  e.** of [SQLITE_
36290 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
362a0 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  TF16], [SQLITE_U
362b0 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c  TF16BE], or [SQL
362c0 49 54 45 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a  ITE_UTF16LE]..**
362d0 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74   ^SQLite takes t
362e0 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66  he text result f
362f0 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74  rom the applicat
36300 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ion from.** the 
36310 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
36320 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
36330 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
36340 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  aces..** ^If the
36350 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
36360 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
36370 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
36380 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61  faces.** is nega
36390 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74  tive, then SQLit
363a0 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74  e takes result t
363b0 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  ext from the 2nd
363c0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68   parameter.** th
363d0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
363e0 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
363f0 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
36400 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
36410 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
36420 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
36430 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  ** is non-negati
36440 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79  ve, then as many
36450 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
36460 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74  acters) of the t
36470 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ext.** pointed t
36480 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  o by the 2nd par
36490 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e  ameter are taken
364a0 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74   as the applicat
364b0 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66  ion-defined.** f
364c0 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20  unction result. 
364d0 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
364e0 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67  meter is non-neg
364f0 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a  ative, then it.*
36500 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  * must be the by
36510 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74  te offset into t
36520 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20  he string where 
36530 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
36540 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65  or would.** appe
36550 61 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67  ar if the string
36560 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69   where NUL termi
36570 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
36580 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
36590 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74  cur.** in the st
365a0 72 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f  ring at a byte o
365b0 66 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65  ffset that is le
365c0 73 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75  ss than the valu
365d0 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20  e of the 3rd.** 
365e0 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20  parameter, then 
365f0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
36600 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69  ring will contai
36610 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  n embedded NULs 
36620 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  and the.** resul
36630 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
36640 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74   operating on st
36650 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64  rings with embed
36660 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
36670 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  fined..** ^If th
36680 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
36690 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
366a0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
366b0 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
366c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
366d0 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   is a non-NULL p
366e0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
366f0 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a  ite calls that.*
36700 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68  * function as th
36710 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  e destructor on 
36720 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
36730 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20   result when it 
36740 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
36750 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
36760 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
36770 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
36780 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36790 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
367a0 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  es or to.** sqli
367b0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
367c0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
367d0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53  onstant SQLITE_S
367e0 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69  TATIC, then SQLi
367f0 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68  te.** assumes th
36800 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  at the text or B
36810 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e  LOB result is in
36820 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20   constant space 
36830 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  and does not.** 
36840 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74  copy the content
36850 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   of the paramete
36860 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73  r nor call a des
36870 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63  tructor on the c
36880 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69  ontent.** when i
36890 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  t has finished u
368a0 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
368b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
368c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
368d0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
368e0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
368f0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
36900 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
36910 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
36920 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ant SQLITE_TRANS
36930 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c  IENT.** then SQL
36940 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
36950 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   of the result i
36960 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e  nto space obtain
36970 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20  ed from.** from 
36980 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
36990 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  )] before it ret
369a0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
369b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
369c0 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
369d0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
369e0 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
369f0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
36a00 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
36a10 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e   copy the.** [un
36a20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
36a30 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
36a40 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
36a50 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
36a60 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
36a70 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
36a80 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
36a90 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
36aa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
36ab0 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71   so that the [sq
36ac0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65  lite3_value] spe
36ad0 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61  cified in the pa
36ae0 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e  rameter may chan
36af0 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c  ge or.** be deal
36b00 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71  located after sq
36b10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
36b20 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74  ue() returns wit
36b30 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41  hout harm..** ^A
36b40 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
36b50 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
36b60 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20  t may always be 
36b70 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a  used where an.**
36b80 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
36b90 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
36ba0 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c  ect is required,
36bb0 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69   so either.** ki
36bc0 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76  nd of [sqlite3_v
36bd0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e  alue] object can
36be0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68   be used with th
36bf0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
36c00 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75  .** If these rou
36c10 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
36c20 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65   from within the
36c30 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
36c40 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e  d.** than the on
36c50 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
36c60 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
36c70 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68  ined function th
36c80 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74  at received.** t
36c90 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  he [sqlite3_cont
36ca0 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68  ext] pointer, th
36cb0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
36cc0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64  defined..*/.void
36cd0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36ce0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
36cf0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
36d00 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
36d10 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
36d20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
36d30 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ob64(sqlite3_con
36d40 74 65 78 74 2a 2c 63 6f 6e 73 74 20 76 6f 69 64  text*,const void
36d50 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  *,.             
36d60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71                sq
36d70 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 76 6f 69  lite3_uint64,voi
36d80 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
36d90 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36da0 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
36db0 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
36dc0 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  e);.void sqlite3
36dd0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
36de0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36df0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
36e00 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
36e10 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
36e20 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36e30 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
36e40 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
36e50 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
36e60 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e  obig(sqlite3_con
36e70 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
36e80 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36e90 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f  r_nomem(sqlite3_
36ea0 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
36eb0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36ec0 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
36ed0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
36ee0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36ef0 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
36f00 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
36f10 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36f20 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69  esult_int64(sqli
36f30 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
36f40 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f  lite3_int64);.vo
36f50 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36f60 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
36f70 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
36f80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
36f90 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
36fa0 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
36fb0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
36fc0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
36fd0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36fe0 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
36ff0 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
37000 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c  ,sqlite3_uint64,
37010 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
37020 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
37030 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69  (*)(void*), unsi
37040 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69  gned char encodi
37050 6e 67 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  ng);.void sqlite
37060 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
37070 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
37080 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
37090 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
370a0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
370b0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
370c0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
370d0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
370e0 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
370f0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
37100 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
37110 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  be(sqlite3_conte
37120 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
37130 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
37140 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
37150 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
37160 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37170 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  *, sqlite3_value
37180 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
37190 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
371a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
371b0 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  *, int n);../*.*
371c0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69  * CAPI3REF: Defi
371d0 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67  ne New Collating
371e0 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a   Sequences.**.**
371f0 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
37200 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f  s add, remove, o
37210 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c  r modify a [coll
37220 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65  ation] associate
37230 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64  d.** with the [d
37240 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37250 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73  on] specified as
37260 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
37270 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
37280 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c  name of the coll
37290 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38  ation is a UTF-8
372a0 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73   string.** for s
372b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
372c0 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71  llation() and sq
372d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
372e0 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61  lation_v2().** a
372f0 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  nd a UTF-16 stri
37300 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
37310 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  e order for sqli
37320 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
37330 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f  tion16()..** ^Co
37340 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68  llation names th
37350 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c  at compare equal
37360 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73   according to [s
37370 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28  qlite3_strnicmp(
37380 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64  )] are.** consid
37390 65 72 65 64 20 74 6f 20 62 65 20 74 68 65 20 73  ered to be the s
373a0 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ame name..**.** 
373b0 5e 28 54 68 65 20 74 68 69 72 64 20 61 72 67 75  ^(The third argu
373c0 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70 29 20  ment (eTextRep) 
373d0 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74  must be one of t
373e0 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a  he constants:.**
373f0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
37400 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20  QLITE_UTF8],.** 
37410 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
37420 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  16LE],.** <li> [
37430 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
37440 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
37450 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c  _UTF16], or.** <
37460 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
37470 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c  6_ALIGNED]..** <
37480 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65  /ul>)^.** ^The e
37490 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74  TextRep argument
374a0 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20   determines the 
374b0 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69  encoding of stri
374c0 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f  ngs passed.** to
374d0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
374e0 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
374f0 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  , xCallback..** 
37500 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46  ^The [SQLITE_UTF
37510 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  16] and [SQLITE_
37520 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76  UTF16_ALIGNED] v
37530 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74 52  alues for eTextR
37540 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69  ep.** force stri
37550 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31 36 20  ngs to be UTF16 
37560 77 69 74 68 20 6e 61 74 69 76 65 20 62 79 74 65  with native byte
37570 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20   order..** ^The 
37580 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
37590 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72  IGNED] value for
375a0 20 65 54 65 78 74 52 65 70 20 66 6f 72 63 65 73   eTextRep forces
375b0 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69   strings to begi
375c0 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20  n.** on an even 
375d0 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a  byte address..**
375e0 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
375f0 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20  argument, pArg, 
37600 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  is an applicatio
37610 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74  n data pointer t
37620 68 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a  hat is passed.**
37630 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
37640 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
37650 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
37660 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
37670 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  k..**.** ^The fi
37680 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43  fth argument, xC
37690 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f  allback, is a po
376a0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c  inter to the col
376b0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e  lating function.
376c0 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f  .** ^Multiple co
376d0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
376e0 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65  s can be registe
376f0 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 61  red using the sa
37700 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77  me name but.** w
37710 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 65 54  ith different eT
37720 65 78 74 52 65 70 20 70 61 72 61 6d 65 74 65 72  extRep parameter
37730 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c  s and SQLite wil
37740 6c 20 75 73 65 20 77 68 69 63 68 65 76 65 72 0a  l use whichever.
37750 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ** function requ
37760 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  ires the least a
37770 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72  mount of data tr
37780 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a  ansformation..**
37790 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61   ^If the xCallba
377a0 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e  ck argument is N
377b0 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c  ULL then the col
377c0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
377d0 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20  is.** deleted.  
377e0 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74  ^When all collat
377f0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61  ing functions ha
37800 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61  ving the same na
37810 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a  me are deleted,.
37820 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f  ** that collatio
37830 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75  n is no longer u
37840 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  sable..**.** ^Th
37850 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
37860 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73  tion callback is
37870 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
37880 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72 67  copy of the pArg
37890 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e   .** application
378a0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e   data pointer an
378b0 64 20 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e  d with two strin
378c0 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69  gs in the encodi
378d0 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ng specified.** 
378e0 62 79 20 74 68 65 20 65 54 65 78 74 52 65 70 20  by the eTextRep 
378f0 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63  argument.  The c
37900 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
37910 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e  n must return an
37920 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74  .** integer that
37930 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65   is negative, ze
37940 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a  ro, or positive.
37950 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73 74 20  ** if the first 
37960 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74  string is less t
37970 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f  han, equal to, o
37980 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74  r greater than t
37990 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65  he second,.** re
379a0 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63  spectively.  A c
379b0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
379c0 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65  n must always re
379d0 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e  turn the same an
379e0 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68  swer.** given th
379f0 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20  e same inputs.  
37a00 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63  If two or more c
37a10 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
37a20 6e 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65  ns are registere
37a30 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65  d.** to the same
37a40 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20   collation name 
37a50 28 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74  (using different
37a60 20 65 54 65 78 74 52 65 70 20 76 61 6c 75 65 73   eTextRep values
37a70 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75  ) then all.** mu
37a80 73 74 20 67 69 76 65 20 61 6e 20 65 71 75 69 76  st give an equiv
37a90 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65  alent answer whe
37aa0 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65  n invoked with e
37ab0 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67  quivalent string
37ac0 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74  s..** The collat
37ad0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
37ae0 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f  t obey the follo
37af0 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20  wing properties 
37b00 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e  for all.** strin
37b10 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a  gs A, B, and C:.
37b20 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
37b30 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20  i> If A==B then 
37b40 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  B==A..** <li> If
37b50 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74   A==B and B==C t
37b60 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69  hen A==C..** <li
37b70 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e  > If A&lt;B THEN
37b80 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e   B&gt;A..** <li>
37b90 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42   If A&lt;B and B
37ba0 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b  &lt;C then A&lt;
37bb0 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a  C..** </ol>.**.*
37bc0 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67  * If a collating
37bd0 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20   function fails 
37be0 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65  any of the above
37bf0 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64   constraints and
37c00 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69   that.** collati
37c10 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20  ng function is  
37c20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 75  registered and u
37c30 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65  sed, then the be
37c40 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
37c50 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
37c60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
37c70 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
37c80 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73  ation_v2() works
37c90 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72   like sqlite3_cr
37ca0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
37cb0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64 64  .** with the add
37cc0 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78  ition that the x
37cd0 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b  Destroy callback
37ce0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70   is invoked on p
37cf0 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  Arg when.** the 
37d00 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
37d10 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a  on is deleted..*
37d20 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  * ^Collating fun
37d30 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74  ctions are delet
37d40 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65  ed when they are
37d50 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c   overridden by l
37d60 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  ater.** calls to
37d70 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63   the collation c
37d80 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  reation function
37d90 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a  s or when the.**
37da0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37db0 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64  ction] is closed
37dc0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
37dd0 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  close()]..**.** 
37de0 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20 63 61  ^The xDestroy ca
37df0 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74  llback is <u>not
37e00 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74  </u> called if t
37e10 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  he .** sqlite3_c
37e20 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
37e30 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61  v2() function fa
37e40 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ils.  Applicatio
37e50 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a  ns that invoke.*
37e60 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
37e70 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
37e80 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
37e90 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e  xDestroy argumen
37ea0 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65  t should .** che
37eb0 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
37ec0 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f  de and dispose o
37ed0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
37ee0 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a  n data pointer.*
37ef0 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74  * themselves rat
37f00 68 65 72 20 74 68 61 6e 20 65 78 70 65 63 74 69  her than expecti
37f10 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61  ng SQLite to dea
37f20 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20 74 68  l with it for th
37f30 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64  em..** This is d
37f40 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76  ifferent from ev
37f50 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  ery other SQLite
37f60 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
37f70 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a   inconsistency .
37f80 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74  ** is unfortunat
37f90 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20  e but cannot be 
37fa0 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20  changed without 
37fb0 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72  breaking backwar
37fc0 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  ds .** compatibi
37fd0 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  lity..**.** See 
37fe0 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f  also:  [sqlite3_
37ff0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
38000 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
38010 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
38020 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  d16()]..*/.int s
38030 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
38040 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  llation(.  sqlit
38050 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
38060 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
38070 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
38080 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
38090 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
380a0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
380b0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
380c0 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
380d0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
380e0 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
380f0 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
38100 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
38110 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
38120 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
38130 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
38140 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
38150 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
38160 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
38170 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  oy)(void*).);.in
38180 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
38190 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20  _collation16(.  
381a0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
381b0 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a  st void *zName,.
381c0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
381d0 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
381e0 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
381f0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
38200 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
38210 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
38220 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61   CAPI3REF: Colla
38230 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c  tion Needed Call
38240 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20  backs.**.** ^To 
38250 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20  avoid having to 
38260 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c  register all col
38270 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
38280 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61   before a databa
38290 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  se.** can be use
382a0 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c  d, a single call
382b0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61  back function ma
382c0 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  y be registered 
382d0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74  with the.** [dat
382e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
382f0 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  ] to be invoked 
38300 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65  whenever an unde
38310 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a  fined collation.
38320 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72  ** sequence is r
38330 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
38340 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
38350 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73  is registered us
38360 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
38370 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
38380 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20  () API,.** then 
38390 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65  it is passed the
383a0 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69   names of undefi
383b0 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ned collation se
383c0 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e  quences as strin
383d0 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e  gs.** encoded in
383e0 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69   UTF-8. ^If sqli
383f0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
38400 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64  eded16() is used
38410 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61  ,.** the names a
38420 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46  re passed as UTF
38430 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e  -16 in machine n
38440 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
38450 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
38460 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20  either function 
38470 72 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69  replaces the exi
38480 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d  sting collation-
38490 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e  needed callback.
384a0 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68  .**.** ^(When th
384b0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
384c0 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74  voked, the first
384d0 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
384e0 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66   is a copy.** of
384f0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
38500 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
38510 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
38520 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
38530 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
38540 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f  d16().  The seco
38550 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
38560 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
38570 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20  onnection.  The 
38580 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
38590 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
385a0 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
385b0 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20  UTF16BE],.** or 
385c0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
385d0 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65  , indicating the
385e0 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20   most desirable 
385f0 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c  form of the coll
38600 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
38610 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  e function requi
38620 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68  red.  The fourth
38630 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
38640 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
38650 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74   required collat
38660 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a  ion sequence.)^.
38670 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
38680 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  ck function shou
38690 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20  ld register the 
386a0 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  desired collatio
386b0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
386c0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
386d0 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  tion()], [sqlite
386e0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
386f0 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  on16()], or.** [
38700 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
38710 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a  ollation_v2()]..
38720 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
38730 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
38740 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
38750 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  void*, .  void(*
38760 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
38770 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
38780 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e  nst char*).);.in
38790 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
387a0 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20  ion_needed16(.  
387b0 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
387c0 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  d*,.  void(*)(vo
387d0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
387e0 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
387f0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65  void*).);..#ifde
38800 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44  f SQLITE_HAS_COD
38810 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  EC./*.** Specify
38820 20 74