/ Hex Artifact Content
Login

Artifact 2f9606a682af372415ce9d1f244183c5cc8385aa:


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 41 64 64 20  ndif../*.** Add 
0710: 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f  the ability to o
0720: 76 65 72 72 69 64 65 20 27 63 64 65 63 6c 27 0a  verride 'cdecl'.
0730: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
0740: 45 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65  E_CDECL.# define
0750: 20 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65   SQLITE_CDECL.#e
0760: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0770: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0780: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0790: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
07a0: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
07c0: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
07d0: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
07e0: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
07f0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
0800: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
0810: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
0820: 79 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  y are supported 
0830: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
0840: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
0850: 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  nly.  Applicatio
0860: 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64  n writers should
0870: 20 62 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a   be aware that.*
0880: 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69  * experimental i
0890: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73 75  nterfaces are su
08a0: 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
08b0: 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65  in point release
08c0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d  s..**.** These m
08d0: 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65  acros used to re
08e0: 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73  solve to various
08f0: 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c   kinds of compil
0900: 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a  er magic that.**
0910: 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20   would generate 
0920: 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73  warning messages
0930: 20 77 68 65 6e 20 74 68 65 79 20 77 65 72 65 20   when they were 
0940: 75 73 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a  used.  But that.
0950: 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69  ** compiler magi
0960: 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72  c ended up gener
0970: 61 74 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75  ating such a flu
0980: 72 72 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72  rry of bug repor
0990: 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61  ts.** that we ha
09a0: 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20  ve taken it all 
09b0: 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63  out and gone bac
09c0: 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c  k to using simpl
09d0: 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73  e.** noop macros
09e0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
09f0: 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23  ITE_DEPRECATED.#
0a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58  define SQLITE_EX
0a10: 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a  PERIMENTAL../*.*
0a20: 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65 20 73  * Ensure these s
0a30: 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20  ymbols were not 
0a40: 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20  defined by some 
0a50: 70 72 65 76 69 6f 75 73 20 68 65 61 64 65 72 20  previous header 
0a60: 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  file..*/.#ifdef 
0a70: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23  SQLITE_VERSION.#
0a80: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0a90: 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66  RSION.#endif.#if
0aa0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0ab0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65  ON_NUMBER.# unde
0ac0: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0ad0: 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a  _NUMBER.#endif..
0ae0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
0af0: 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62  Compile-Time Lib
0b00: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
0b10: 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  bers.**.** ^(The
0b20: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0b30: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0b40: 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71   macro in the sq
0b50: 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a  lite3.h header.*
0b60: 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61  * evaluates to a
0b70: 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20   string literal 
0b80: 74 68 61 74 20 69 73 20 74 68 65 20 53 51 4c 69  that is the SQLi
0b90: 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68  te version in th
0ba0: 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59  e.** format "X.Y
0bb0: 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73 20 74  .Z" where X is t
0bc0: 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e  he major version
0bd0: 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20   number (always 
0be0: 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33  3 for.** SQLite3
0bf0: 29 20 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d  ) and Y is the m
0c00: 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d  inor version num
0c10: 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65  ber and Z is the
0c20: 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e   release number.
0c30: 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  )^.** ^(The [SQL
0c40: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0c50: 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ER] C preprocess
0c60: 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65  or macro resolve
0c70: 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a  s to an integer.
0c80: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61 6c 75  ** with the valu
0c90: 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59  e (X*1000000 + Y
0ca0: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65  *1000 + Z) where
0cb0: 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65   X, Y, and Z are
0cc0: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d   the same.** num
0cd0: 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51  bers used in [SQ
0ce0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e  LITE_VERSION].)^
0cf0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56  .** The SQLITE_V
0d00: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f  ERSION_NUMBER fo
0d10: 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65  r any given rele
0d20: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ase of SQLite wi
0d30: 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61  ll also.** be la
0d40: 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 72 65  rger than the re
0d50: 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68  lease from which
0d60: 20 69 74 20 69 73 20 64 65 72 69 76 65 64 2e 20   it is derived. 
0d70: 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a   Either Y will.*
0d80: 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61  * be held consta
0d90: 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  nt and Z will be
0da0: 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20   incremented or 
0db0: 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69  else Y will be i
0dc0: 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e  ncremented.** an
0dd0: 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65  d Z will be rese
0de0: 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  t to zero..**.**
0df0: 20 53 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33   Since version 3
0e00: 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f  .6.18, SQLite so
0e10: 75 72 63 65 20 63 6f 64 65 20 68 61 73 20 62 65  urce code has be
0e20: 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65  en stored in the
0e30: 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74  .** <a href="htt
0e40: 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73  p://www.fossil-s
0e50: 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20  cm.org/">Fossil 
0e60: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0e70: 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74  nagement.** syst
0e80: 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51  em</a>.  ^The SQ
0e90: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d  LITE_SOURCE_ID m
0ea0: 61 63 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74  acro evaluates t
0eb0: 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68  o.** a string wh
0ec0: 69 63 68 20 69 64 65 6e 74 69 66 69 65 73 20 61  ich identifies a
0ed0: 20 70 61 72 74 69 63 75 6c 61 72 20 63 68 65 63   particular chec
0ee0: 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a  k-in of SQLite.*
0ef0: 2a 20 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e  * within its con
0f00: 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67  figuration manag
0f10: 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e  ement system.  ^
0f20: 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  The SQLITE_SOURC
0f30: 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63  E_ID.** string c
0f40: 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 65  ontains the date
0f50: 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65   and time of the
0f60: 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20   check-in (UTC) 
0f70: 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68  and an SHA1.** h
0f80: 61 73 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72  ash of the entir
0f90: 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a  e source tree..*
0fa0: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
0fb0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
0fc0: 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  on()],.** [sqlit
0fd0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
0fe0: 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65  mber()], [sqlite
0ff0: 33 5f 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a  3_sourceid()],.*
1000: 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f  * [sqlite_versio
1010: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
1020: 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a  _source_id()]..*
1030: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1040: 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20  _VERSION        
1050: 22 2d 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69  "--VERS--".#defi
1060: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
1070: 4e 5f 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49  N_NUMBER --VERSI
1080: 4f 4e 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66  ON-NUMBER--.#def
1090: 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  ine SQLITE_SOURC
10a0: 45 5f 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55  E_ID      "--SOU
10b0: 52 43 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a  RCE-ID--"../*.**
10c0: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
10d0: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
10e0: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b  ion Numbers.** K
10f0: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
1100: 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65  _version, sqlite
1110: 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a  3_sourceid.**.**
1120: 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   These interface
1130: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
1140: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
1150: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
1160: 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  RSION],.** [SQLI
1170: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1180: 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  R], and [SQLITE_
1190: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
11a0: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73  processor macros
11b0: 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f  .** but are asso
11c0: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
11d0: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
11e0: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
11f0: 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a  le.  ^(Cautious.
1200: 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  ** programmers m
1210: 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73  ight include ass
1220: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
1230: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63   in their applic
1240: 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69  ation to.** veri
1250: 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72  fy that values r
1260: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1270: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63   interfaces matc
1280: 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a  h the macros in.
1290: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61  ** the header, a
12a0: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74  nd thus insure t
12b0: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  hat the applicat
12c0: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ion is.** compil
12d0: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67  ed with matching
12e0: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61   library and hea
12f0: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  der files..**.**
1300: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1310: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71  e>.** assert( sq
1320: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1330: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54  _number()==SQLIT
1340: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1350: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73   );.** assert( s
1360: 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f  trcmp(sqlite3_so
1370: 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f  urceid(),SQLITE_
1380: 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b  SOURCE_ID)==0 );
1390: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
13a0: 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  mp(sqlite3_libve
13b0: 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56  rsion(),SQLITE_V
13c0: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
13d0: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
13e0: 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
13f0: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1400: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1410: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ant contains the
1420: 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45   text of [SQLITE
1430: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63  _VERSION].** mac
1440: 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ro.  ^The sqlite
1450: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66  3_libversion() f
1460: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1470: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1480: 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74  .** to the sqlit
1490: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
14a0: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54  ing constant.  T
14b0: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
14c0: 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74  rsion().** funct
14d0: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
14e0: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
14f0: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
1500: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
1510: 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63  ave.** direct ac
1520: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63  cess to string c
1530: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
1540: 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a  the DLL.  ^The.*
1550: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  * sqlite3_libver
1560: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75  sion_number() fu
1570: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1580: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
1590: 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  to.** [SQLITE_VE
15a0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20  RSION_NUMBER].  
15b0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75  ^The sqlite3_sou
15c0: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e  rceid() function
15d0: 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70   returns .** a p
15e0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
15f0: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73  ng constant whos
1600: 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73  e value is the s
1610: 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b  ame as the .** [
1620: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
1630: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
1640: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65   macro..**.** Se
1650: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f  e also: [sqlite_
1660: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
1670: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
1680: 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45  ()]..*/.SQLITE_E
1690: 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72  XTERN const char
16a0: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
16b0: 5b 5d 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  [];.const char *
16c0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16d0: 6f 6e 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20  on(void);.const 
16e0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f  char *sqlite3_so
16f0: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e  urceid(void);.in
1700: 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  t sqlite3_libver
1710: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64  sion_number(void
1720: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1730: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
1740: 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e  rary Compilation
1750: 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73   Options Diagnos
1760: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tics.**.** ^The 
1770: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1780: 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e  ption_used() fun
1790: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20  ction returns 0 
17a0: 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74  or 1 .** indicat
17b0: 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 20  ing whether the 
17c0: 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e  specified option
17d0: 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 20   was defined at 
17e0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  .** compile time
17f0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20  .  ^The SQLITE_ 
1800: 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d  prefix may be om
1810: 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a  itted from the .
1820: 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70  ** option name p
1830: 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33  assed to sqlite3
1840: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
1850: 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e  sed().  .**.** ^
1860: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
1870: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1880: 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  function allows 
1890: 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65  iterating.** ove
18a0: 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70  r the list of op
18b0: 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20  tions that were 
18c0: 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69  defined at compi
18d0: 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65  le time by.** re
18e0: 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68  turning the N-th
18f0: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70   compile time op
1900: 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49  tion string.  ^I
1910: 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  f N is out of ra
1920: 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  nge,.** sqlite3_
1930: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1940: 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  t() returns a NU
1950: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
1960: 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72  e SQLITE_ .** pr
1970: 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20  efix is omitted 
1980: 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73  from any strings
1990: 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a   returned by .**
19a0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
19b0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a  option_get()..**
19c0: 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72  .** ^Support for
19d0: 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20   the diagnostic 
19e0: 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65  functions sqlite
19f0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1a00: 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71  used().** and sq
1a10: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1a20: 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65  ion_get() may be
1a30: 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 63   omitted by spec
1a40: 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b  ifying the .** [
1a50: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50  SQLITE_OMIT_COMP
1a60: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d  ILEOPTION_DIAGS]
1a70: 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69   option at compi
1a80: 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53  le time..**.** S
1a90: 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e  ee also: SQL fun
1aa0: 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63  ctions [sqlite_c
1ab0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1ac0: 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1ad0: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1ae0: 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65  n_get()] and the
1af0: 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e   [compile_option
1b00: 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69  s pragma]..*/.#i
1b10: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
1b20: 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f  T_COMPILEOPTION_
1b30: 44 49 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65  DIAGS.int sqlite
1b40: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1b50: 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20  used(const char 
1b60: 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73  *zOptName);.cons
1b70: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1b80: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b90: 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66  t(int N);.#endif
1ba0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1bb0: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66  : Test To See If
1bc0: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20   The Library Is 
1bd0: 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a  Threadsafe.**.**
1be0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68   ^The sqlite3_th
1bf0: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
1c00: 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ion returns zero
1c10: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
1c20: 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f  ** SQLite was co
1c30: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65  mpiled with mute
1c40: 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65  xing code omitte
1c50: 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20  d due to the.** 
1c60: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1c70: 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  FE] compile-time
1c80: 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65   option being se
1c90: 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51  t to 0..**.** SQ
1ca0: 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70  Lite can be comp
1cb0: 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 74  iled with or wit
1cc0: 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57  hout mutexes.  W
1cd0: 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  hen.** the [SQLI
1ce0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43  TE_THREADSAFE] C
1cf0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
1d00: 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d  cro is 1 or 2, m
1d10: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
1d20: 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65  abled and SQLite
1d30: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20   is threadsafe. 
1d40: 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51   When the.** [SQ
1d50: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d60: 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a   macro is 0, .**
1d70: 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65   the mutexes are
1d80: 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f   omitted.  Witho
1d90: 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20  ut the mutexes, 
1da0: 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a  it is not safe.*
1db0: 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20  * to use SQLite 
1dc0: 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f  concurrently fro
1dd0: 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  m more than one 
1de0: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e  thread..**.** En
1df0: 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69  abling mutexes i
1e00: 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62  ncurs a measurab
1e10: 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70  le performance p
1e20: 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66  enalty..** So if
1e30: 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d   speed is of utm
1e40: 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20  ost importance, 
1e50: 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74  it makes sense t
1e60: 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  o disable.** the
1e70: 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66   mutexes.  But f
1e80: 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74  or maximum safet
1e90: 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  y, mutexes shoul
1ea0: 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  d be enabled..**
1eb0: 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 65   ^The default be
1ec0: 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75  havior is for mu
1ed0: 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62  texes to be enab
1ee0: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  led..**.** This 
1ef0: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
1f00: 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c   used by an appl
1f10: 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20  ication to make 
1f20: 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
1f30: 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69   version of SQLi
1f40: 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c 69  te that it is li
1f50: 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61  nking against wa
1f60: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
1f70: 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 73  ** the desired s
1f80: 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53  etting of the [S
1f90: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1fa0: 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54  ] macro..**.** T
1fb0: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e  his interface on
1fc0: 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68  ly reports on th
1fd0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  e compile-time m
1fe0: 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20  utex setting.** 
1ff0: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
2000: 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e  HREADSAFE] flag.
2010: 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
2020: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
2030: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
2040: 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d  E=1 or =2 then m
2050: 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c  utexes are enabl
2060: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 75  ed by default bu
2070: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c  t.** can be full
2080: 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64  y or partially d
2090: 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20  isabled using a 
20a0: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
20b0: 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69  _config()].** wi
20c0: 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 51  th the verbs [SQ
20d0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
20e0: 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49  LETHREAD], [SQLI
20f0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
2100: 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  HREAD],.** or [S
2110: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
2120: 49 41 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65  IALIZED].  ^(The
2130: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
2140: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
2150: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
2160: 63 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79  ction shows only
2170: 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   the compile-tim
2180: 65 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20  e setting of.** 
2190: 74 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e  thread safety, n
21a0: 6f 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20  ot any run-time 
21b0: 63 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20  changes to that 
21c0: 73 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a  setting made by.
21d0: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  ** sqlite3_confi
21e0: 67 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  g(). In other wo
21f0: 72 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20  rds, the return 
2200: 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
2210: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a  e3_threadsafe().
2220: 2a 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20  ** is unchanged 
2230: 62 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  by calls to sqli
2240: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a  te3_config().)^.
2250: 2a 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74  **.** See the [t
2260: 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64  hreading mode] d
2270: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
2280: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
2290: 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20  rmation..*/.int 
22a0: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
22b0: 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  fe(void);../*.**
22c0: 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
22d0: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48  ase Connection H
22e0: 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44  andle.** KEYWORD
22f0: 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  S: {database con
2300: 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61  nection} {databa
2310: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a  se connections}.
2320: 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20  **.** Each open 
2330: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
2340: 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  is represented b
2350: 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  y a pointer to a
2360: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a  n instance of.**
2370: 20 74 68 65 20 6f 70 61 71 75 65 20 73 74 72 75   the opaque stru
2380: 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c  cture named "sql
2390: 69 74 65 33 22 2e 20 20 49 74 20 69 73 20 75 73  ite3".  It is us
23a0: 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66  eful to think of
23b0: 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70   an sqlite3.** p
23c0: 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a  ointer as an obj
23d0: 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ect.  The [sqlit
23e0: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
23f0: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
2400: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2410: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
2420: 66 61 63 65 73 20 61 72 65 20 69 74 73 20 63 6f  faces are its co
2430: 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20  nstructors, and 
2440: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29  [sqlite3_close()
2450: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2460: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72  3_close_v2()] ar
2470: 65 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72  e its destructor
2480: 73 2e 20 20 54 68 65 72 65 20 61 72 65 20 6d 61  s.  There are ma
2490: 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65  ny other.** inte
24a0: 72 66 61 63 65 73 20 28 73 75 63 68 20 61 73 0a  rfaces (such as.
24b0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
24c0: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
24d0: 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
24e0: 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ion()], and.** [
24f0: 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
2500: 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20  eout()] to name 
2510: 62 75 74 20 74 68 72 65 65 29 20 74 68 61 74 20  but three) that 
2520: 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61  are methods on a
2530: 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a  n.** sqlite3 obj
2540: 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ect..*/.typedef 
2550: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 20 73  struct sqlite3 s
2560: 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43  qlite3;../*.** C
2570: 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20  API3REF: 64-Bit 
2580: 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a  Integer Types.**
2590: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
25a0: 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75  e_int64 sqlite_u
25b0: 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61  int64.**.** Beca
25c0: 75 73 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20  use there is no 
25d0: 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77  cross-platform w
25e0: 61 79 20 74 6f 20 73 70 65 63 69 66 79 20 36 34  ay to specify 64
25f0: 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74 79 70  -bit integer typ
2600: 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63  es.** SQLite inc
2610: 6c 75 64 65 73 20 74 79 70 65 64 65 66 73 20 66  ludes typedefs f
2620: 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  or 64-bit signed
2630: 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e   and unsigned in
2640: 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  tegers..**.** Th
2650: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
2660: 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  and sqlite3_uint
2670: 36 34 20 61 72 65 20 74 68 65 20 70 72 65 66 65  64 are the prefe
2680: 72 72 65 64 20 74 79 70 65 20 64 65 66 69 6e 69  rred type defini
2690: 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71  tions..** The sq
26a0: 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73  lite_int64 and s
26b0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70  qlite_uint64 typ
26c0: 65 73 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  es are supported
26d0: 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a   for backwards.*
26e0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
26f0: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  only..**.** ^The
2700: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61   sqlite3_int64 a
2710: 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  nd sqlite_int64 
2720: 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20  types can store 
2730: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a  integer values.*
2740: 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33  * between -92233
2750: 37 32 30 33 36 38 35 34 37 37 35 38 30 38 20 61  72036854775808 a
2760: 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36 38 35  nd +922337203685
2770: 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76  4775807 inclusiv
2780: 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
2790: 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73  te3_uint64 and s
27a0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70  qlite_uint64 typ
27b0: 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74  es can store int
27c0: 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20  eger values .** 
27d0: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31  between 0 and +1
27e0: 38 34 34 36 37 34 34 30 37 33 37 30 39 35 35 31  8446744073709551
27f0: 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a  615 inclusive..*
2800: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
2810: 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70  INT64_TYPE.  typ
2820: 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36  edef SQLITE_INT6
2830: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e  4_TYPE sqlite_in
2840: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2850: 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49  nsigned SQLITE_I
2860: 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65  NT64_TYPE sqlite
2870: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64  _uint64;.#elif d
2880: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
2890: 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f   || defined(__BO
28a0: 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65  RLANDC__).  type
28b0: 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  def __int64 sqli
28c0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
28d0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69  def unsigned __i
28e0: 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74  nt64 sqlite_uint
28f0: 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65  64;.#else.  type
2900: 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e  def long long in
2910: 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  t sqlite_int64;.
2920: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2930: 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74  ed long long int
2940: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
2950: 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73  #endif.typedef s
2960: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
2970: 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64  te3_int64;.typed
2980: 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  ef sqlite_uint64
2990: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b   sqlite3_uint64;
29a0: 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69  ../*.** If compi
29b0: 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65  ling for a proce
29c0: 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20  ssor that lacks 
29d0: 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73  floating point s
29e0: 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74  upport,.** subst
29f0: 69 74 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f  itute integer fo
2a00: 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74  r floating-point
2a10: 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49  ..*/.#ifdef SQLI
2a20: 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47  TE_OMIT_FLOATING
2a30: 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20  _POINT.# define 
2a40: 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69  double sqlite3_i
2a50: 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  nt64.#endif../*.
2a60: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f  ** CAPI3REF: Clo
2a70: 73 69 6e 67 20 41 20 44 61 74 61 62 61 73 65 20  sing A Database 
2a80: 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  Connection.**.**
2a90: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
2aa0: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
2ab0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
2ac0: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
2ad0: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
2ae0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
2af0: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
2b00: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2b10: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2b20: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
2b30: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
2b40: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2b50: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
2b60: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
2b70: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
2b80: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
2b90: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
2ba0: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
2bb0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2bc0: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
2bd0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2be0: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2bf0: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
2c00: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
2c10: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
2c20: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
2c30: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
2c40: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2c50: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
2c60: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2c70: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
2c80: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2c90: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
2ca0: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
2cb0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
2cc0: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
2cd0: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
2ce0: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
2cf0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d00: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
2d10: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
2d20: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
2d30: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
2d40: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
2d50: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
2d60: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
2d70: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
2d80: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
2d90: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
2da0: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
2db0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
2dc0: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
2dd0: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
2de0: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
2df0: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
2e00: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
2e10: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
2e20: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
2e30: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
2e40: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
2e50: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
2e60: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
2e70: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2e80: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
2e90: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ea0: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
2eb0: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
2ec0: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
2ed0: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
2ee0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
2ef0: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
2f00: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
2f10: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
2f20: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
2f30: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
2f40: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
2f50: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
2f60: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
2f70: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
2f80: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
2f90: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
2fa0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2fb0: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
2fc0: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
2fd0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2fe0: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
2ff0: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
3000: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
3010: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
3020: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
3030: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
3040: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
3050: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3060: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
3070: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
3080: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
3090: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
30a0: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
30b0: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
30c0: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
30d0: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
30e0: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
30f0: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
3100: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
3110: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
3120: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
3130: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
3140: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
3150: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3160: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
3170: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
3180: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
3190: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
31a0: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
31b0: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
31c0: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
31d0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
31e0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
31f0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
3200: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
3210: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
3220: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
3230: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
3240: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
3250: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3260: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
3270: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
3280: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
3290: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
32a0: 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  p..*/.int sqlite
32b0: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
32c0: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
32d0: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
32e0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
32f0: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
3300: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
3310: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
3320: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
3330: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
3340: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
3350: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
3360: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
3370: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
3380: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
3390: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
33a0: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
33b0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33c0: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
33d0: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
33e0: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65  erface.**.** The
33f0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3400: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
3410: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
3420: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
3430: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
3440: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
3450: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
3460: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
3470: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
3480: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
3490: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
34a0: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
34b0: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
34c0: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
34d0: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
34e0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
34f0: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
3500: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
3510: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
3520: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
3530: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
3540: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
3550: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
3560: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
3570: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
3580: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3590: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
35a0: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
35b0: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
35c0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
35d0: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
35e0: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
35f0: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3600: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
3610: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
3620: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
3630: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
3640: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
3650: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
3660: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
3670: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3680: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
3690: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
36a0: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
36b0: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
36c0: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
36d0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
36e0: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
36f0: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
3700: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
3710: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
3720: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
3730: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
3740: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3750: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
3760: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
3770: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
3780: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
3790: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
37a0: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
37b0: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
37c0: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
37d0: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
37e0: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
37f0: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
3800: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3810: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3820: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
3830: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
3840: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
3850: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
3860: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3870: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
3880: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
3890: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
38a0: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
38b0: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
38c0: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
38d0: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
38e0: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
38f0: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
3900: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
3910: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
3920: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3930: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73  meter of.** of s
3940: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3950: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
3960: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
3970: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
3980: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
3990: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
39a0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
39b0: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
39c0: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
39d0: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
39e0: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
39f0: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3a00: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3a10: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3a20: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3a30: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3a40: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3a50: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
3a60: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3a70: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
3a80: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
3a90: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
3aa0: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
3ab0: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3ac0: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3ad0: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3ae0: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3af0: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3b00: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3b10: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3b20: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3b30: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3b40: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3b50: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
3b60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3b70: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3b80: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
3b90: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3ba0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
3bb0: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3bc0: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3bd0: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3be0: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3bf0: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3c00: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3c10: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3c20: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3c30: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3c40: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3c50: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
3c60: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
3c70: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
3c80: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3c90: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
3ca0: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
3cb0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3cc0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3cd0: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3ce0: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3cf0: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3d00: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3d10: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
3d20: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3d30: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
3d40: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
3d50: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
3d60: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3d70: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
3d80: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
3d90: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
3da0: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
3db0: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
3dc0: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
3dd0: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
3de0: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
3df0: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
3e00: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
3e10: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
3e20: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
3e30: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
3e40: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
3e50: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
3e60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3e70: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68  t insure that th
3e80: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
3e90: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3ea0: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
3eb0: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
3ec0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3ed0: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
3ee0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3ef0: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
3f00: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3f10: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
3f20: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
3f30: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
3f40: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
3f50: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
3f60: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
3f70: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3f80: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3f90: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
3fa0: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
3fb0: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
3fc0: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
3fd0: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
3fe0: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
3ff0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
4000: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
4010: 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
4020: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
4030: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
4040: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4050: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
4060: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
4070: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
4080: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4090: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
40a0: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
40b0: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
40c0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
40d0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
40e0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
40f0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4110: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4120: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
4130: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
4140: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
4150: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
4160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
4170: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
4180: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
4190: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
41a0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
41b0: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
41c0: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
41d0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  ns}.**.** Many S
41e0: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
41f0: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
4200: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
4210: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
4220: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
4230: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
4240: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
4250: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
4260: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
4270: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4280: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4290: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
42a0: 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  o: [extended res
42b0: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
42c0: 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65  ions].*/.#define
42d0: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
42e0: 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63       0   /* Succ
42f0: 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f  essful result */
4300: 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66  ./* beginning-of
4310: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
4330: 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20  RROR        1   
4340: 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20  /* SQL error or 
4350: 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65  missing database
4360: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4370: 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20  TE_INTERNAL     
4380: 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20  2   /* Internal 
4390: 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53  logic error in S
43a0: 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  QLite */.#define
43b0: 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20   SQLITE_PERM    
43c0: 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65       3   /* Acce
43d0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65  ss permission de
43e0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
43f0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20  SQLITE_ABORT    
4400: 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62      4   /* Callb
4410: 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75  ack routine requ
4420: 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a  ested an abort *
4430: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4440: 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20  _BUSY         5 
4450: 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73    /* The databas
4460: 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64  e file is locked
4470: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4480: 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  TE_LOCKED       
4490: 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69  6   /* A table i
44a0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
44b0: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
44c0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ine SQLITE_NOMEM
44d0: 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41          7   /* A
44e0: 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64   malloc() failed
44f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4500: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  TE_READONLY     
4510: 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74  8   /* Attempt t
4520: 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e  o write a readon
4530: 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23  ly database */.#
4540: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
4550: 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f  TERRUPT    9   /
4560: 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d  * Operation term
4570: 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  inated by sqlite
4580: 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a  3_interrupt()*/.
4590: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
45a0: 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20  OERR       10   
45b0: 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20  /* Some kind of 
45c0: 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f  disk I/O error o
45d0: 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69  ccurred */.#defi
45e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
45f0: 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68  T     11   /* Th
4600: 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20  e database disk 
4610: 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d  image is malform
4620: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4630: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20  LITE_NOTFOUND   
4640: 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e   12   /* Unknown
4650: 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74   opcode in sqlit
4660: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
4670: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4680: 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  ITE_FULL        
4690: 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f  13   /* Insertio
46a0: 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65  n failed because
46b0: 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c   database is ful
46c0: 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
46d0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20  ITE_CANTOPEN    
46e0: 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74  14   /* Unable t
46f0: 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
4700: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
4710: 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f  ine SQLITE_PROTO
4720: 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44  COL    15   /* D
4730: 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f  atabase lock pro
4740: 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23  tocol error */.#
4750: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d  define SQLITE_EM
4760: 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f  PTY       16   /
4770: 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d  * Database is em
4780: 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  pty */.#define S
4790: 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20  QLITE_SCHEMA    
47a0: 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61    17   /* The da
47b0: 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
47c0: 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  anged */.#define
47d0: 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20   SQLITE_TOOBIG  
47e0: 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69      18   /* Stri
47f0: 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65  ng or BLOB excee
4800: 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f  ds size limit */
4810: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4820: 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20  CONSTRAINT  19  
4830: 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f   /* Abort due to
4840: 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
4850: 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  ation */.#define
4860: 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48   SQLITE_MISMATCH
4870: 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61      20   /* Data
4880: 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a   type mismatch *
4890: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
48a0: 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20  _MISUSE      21 
48b0: 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65    /* Library use
48c0: 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f  d incorrectly */
48d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
48e0: 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20  NOLFS       22  
48f0: 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74   /* Uses OS feat
4900: 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74  ures not support
4910: 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64  ed on host */.#d
4920: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
4930: 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a  H        23   /*
4940: 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64   Authorization d
4950: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
4960: 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20   SQLITE_FORMAT  
4970: 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69      24   /* Auxi
4980: 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66  liary database f
4990: 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23  ormat error */.#
49a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41  define SQLITE_RA
49b0: 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f  NGE       25   /
49c0: 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
49d0: 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20  to sqlite3_bind 
49e0: 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a  out of range */.
49f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4a00: 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20  OTADB      26   
4a10: 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74  /* File opened t
4a20: 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74  hat is not a dat
4a30: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
4a40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4a50: 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a  ICE      27   /*
4a60: 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66   Notifications f
4a70: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
4a80: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
4a90: 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20  ITE_WARNING     
4aa0: 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73  28   /* Warnings
4ab0: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f   from sqlite3_lo
4ac0: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  g() */.#define S
4ad0: 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20  QLITE_ROW       
4ae0: 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65    100  /* sqlite
4af0: 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f  3_step() has ano
4b00: 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a  ther row ready *
4b10: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b20: 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31  _DONE        101
4b30: 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65    /* sqlite3_ste
4b40: 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64  p() has finished
4b50: 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a   executing */./*
4b60: 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f   end-of-error-co
4b70: 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  des */../*.** CA
4b80: 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64  PI3REF: Extended
4b90: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4ba0: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4bb0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4bc0: 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a   definitions}.**
4bd0: 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75  .** In its defau
4be0: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
4bf0: 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75  , SQLite API rou
4c00: 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65  tines return one
4c10: 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a   of 30 integer.*
4c20: 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  * [result codes]
4c30: 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65  .  However, expe
4c40: 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e  rience has shown
4c50: 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a   that many of.**
4c60: 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f   these result co
4c70: 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72  des are too coar
4c80: 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65  se-grained.  The
4c90: 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65  y do not provide
4ca0: 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f   as.** much info
4cb0: 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72  rmation about pr
4cc0: 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61  oblems as progra
4cd0: 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65  mmers might like
4ce0: 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20  .  In an effort 
4cf0: 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68  to.** address th
4d00: 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f  is, newer versio
4d10: 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65  ns of SQLite (ve
4d20: 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20  rsion 3.3.8 and 
4d30: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a  later) include.*
4d40: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64  * support for ad
4d50: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20  ditional result 
4d60: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69  codes that provi
4d70: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  de more detailed
4d80: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
4d90: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68  about errors. Th
4da0: 65 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65  ese [extended re
4db0: 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20  sult codes] are 
4dc0: 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
4dd0: 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20  led.** on a per 
4de0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4df0: 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20  ion basis using 
4e00: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
4e10: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
4e20: 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f  codes()] API.  O
4e30: 72 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 20  r, the extended 
4e40: 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  code for.** the 
4e50: 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f  most recent erro
4e60: 72 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  r can be obtaine
4e70: 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
4e80: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
4e90: 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  code()]..*/.#def
4ea0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4eb0: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
4ec0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4ed0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
4ee0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4ef0: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20  SHORT_READ      
4f00: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4f10: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
4f20: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57  e SQLITE_IOERR_W
4f30: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
4f40: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4f50: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
4f60: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
4f70: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
4f80: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4f90: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
4fa0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
4fb0: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28  _FSYNC         (
4fc0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4fd0: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
4fe0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e  QLITE_IOERR_TRUN
4ff0: 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53  CATE          (S
5000: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36  QLITE_IOERR | (6
5010: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5020: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54  LITE_IOERR_FSTAT
5030: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5040: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c  LITE_IOERR | (7<
5050: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5060: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b  ITE_IOERR_UNLOCK
5070: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5080: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c  ITE_IOERR | (8<<
5090: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
50a0: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20  TE_IOERR_RDLOCK 
50b0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
50c0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38  TE_IOERR | (9<<8
50d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50e0: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20  E_IOERR_DELETE  
50f0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5100: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38  E_IOERR | (10<<8
5110: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5120: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20  E_IOERR_BLOCKED 
5130: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5140: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38  E_IOERR | (11<<8
5150: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5160: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20  E_IOERR_NOMEM   
5170: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5180: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38  E_IOERR | (12<<8
5190: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
51a0: 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20  E_IOERR_ACCESS  
51b0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
51c0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38  E_IOERR | (13<<8
51d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
51e0: 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53  E_IOERR_CHECKRES
51f0: 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54  ERVEDLOCK (SQLIT
5200: 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38  E_IOERR | (14<<8
5210: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5220: 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20  E_IOERR_LOCK    
5230: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5240: 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38  E_IOERR | (15<<8
5250: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5260: 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20  E_IOERR_CLOSE   
5270: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5280: 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38  E_IOERR | (16<<8
5290: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
52a0: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53  E_IOERR_DIR_CLOS
52b0: 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  E         (SQLIT
52c0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38  E_IOERR | (17<<8
52d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
52e0: 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20  E_IOERR_SHMOPEN 
52f0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5300: 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38  E_IOERR | (18<<8
5310: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5320: 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20  E_IOERR_SHMSIZE 
5330: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5340: 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38  E_IOERR | (19<<8
5350: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5360: 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20  E_IOERR_SHMLOCK 
5370: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5380: 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38  E_IOERR | (20<<8
5390: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
53a0: 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20  E_IOERR_SHMMAP  
53b0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
53c0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38  E_IOERR | (21<<8
53d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
53e0: 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20  E_IOERR_SEEK    
53f0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5400: 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38  E_IOERR | (22<<8
5410: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5420: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e  E_IOERR_DELETE_N
5430: 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54  OENT      (SQLIT
5440: 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38  E_IOERR | (23<<8
5450: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5460: 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20  E_IOERR_MMAP    
5470: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5480: 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38  E_IOERR | (24<<8
5490: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
54a0: 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50  E_IOERR_GETTEMPP
54b0: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
54c0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38  E_IOERR | (25<<8
54d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
54e0: 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48  E_IOERR_CONVPATH
54f0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5500: 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38  E_IOERR | (26<<8
5510: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5520: 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43  E_LOCKED_SHAREDC
5530: 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54  ACHE      (SQLIT
5540: 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c  E_LOCKED |  (1<<
5550: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5560: 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59  TE_BUSY_RECOVERY
5570: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5580: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c  TE_BUSY   |  (1<
5590: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
55a0: 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f  ITE_BUSY_SNAPSHO
55b0: 54 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  T           (SQL
55c0: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32  ITE_BUSY   |  (2
55d0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
55e0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
55f0: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
5600: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5610: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5620: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
5630: 49 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28  ISDIR          (
5640: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
5650: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5660: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
5670: 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20  N_FULLPATH      
5680: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5690: 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  N | (3<<8)).#def
56a0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
56b0: 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20  PEN_CONVPATH    
56c0: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
56d0: 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  PEN | (4<<8)).#d
56e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
56f0: 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20  RUPT_VTAB       
5700: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52       (SQLITE_COR
5710: 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23  RUPT | (1<<8)).#
5720: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
5730: 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20  ADONLY_RECOVERY 
5740: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
5750: 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29  ADONLY | (1<<8))
5760: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5770: 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43  READONLY_CANTLOC
5780: 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  K       (SQLITE_
5790: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38  READONLY | (2<<8
57a0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
57b0: 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42  E_READONLY_ROLLB
57c0: 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  ACK       (SQLIT
57d0: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c  E_READONLY | (3<
57e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
57f0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d  ITE_READONLY_DBM
5800: 4f 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c  OVED        (SQL
5810: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5820: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5830: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
5840: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
5850: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
5860: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5870: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5880: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
5890: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
58a0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
58b0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
58c0: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
58d0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
58e0: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
58f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5900: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
5910: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
5920: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
5930: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5940: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
5950: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
5960: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
5970: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5980: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5990: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
59a0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
59b0: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
59c0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
59d0: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
59e0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
59f0: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
5a00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5a10: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
5a20: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5a30: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
5a40: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5a50: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
5a60: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
5a70: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
5a80: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5a90: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5aa0: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
5ab0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5ac0: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
5ad0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5ae0: 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20  INT_ROWID       
5af0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5b00: 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64  INT |(10<<8)).#d
5b10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
5b20: 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20  ICE_RECOVER_WAL 
5b30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54       (SQLITE_NOT
5b40: 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ICE | (1<<8)).#d
5b50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
5b60: 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c  ICE_RECOVER_ROLL
5b70: 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54  BACK (SQLITE_NOT
5b80: 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ICE | (2<<8)).#d
5b90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
5ba0: 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20  NING_AUTOINDEX  
5bb0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52       (SQLITE_WAR
5bc0: 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23  NING | (1<<8)).#
5bd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
5be0: 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20  TH_USER         
5bf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55        (SQLITE_AU
5c00: 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a  TH | (1<<8))../*
5c10: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
5c20: 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65  ags For File Ope
5c30: 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a  n Operations.**.
5c40: 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c  ** These bit val
5c50: 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  ues are intended
5c60: 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a   for use in the.
5c70: 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ** 3rd parameter
5c80: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5c90: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
5ca0: 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20  rface and.** in 
5cb0: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
5cc0: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
5cd0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
5ce0: 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  hod..*/.#define 
5cf0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
5d00: 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30  ONLY         0x0
5d10: 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66  0000001  /* Ok f
5d20: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5d30: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5d40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
5d50: 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30  WRITE        0x0
5d60: 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66  0000002  /* Ok f
5d70: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5d80: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5d90: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
5da0: 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30  TE           0x0
5db0: 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66  0000004  /* Ok f
5dc0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5dd0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5de0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
5df0: 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30  TEONCLOSE    0x0
5e00: 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20  0000008  /* VFS 
5e10: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5e20: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
5e30: 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30  USIVE        0x0
5e40: 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20  0000010  /* VFS 
5e50: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5e60: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f  SQLITE_OPEN_AUTO
5e70: 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30  PROXY        0x0
5e80: 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20  0000020  /* VFS 
5e90: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5ea0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
5eb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5ec0: 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66  0000040  /* Ok f
5ed0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5ee0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5ef0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f  SQLITE_OPEN_MEMO
5f00: 52 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30  RY           0x0
5f10: 30 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66  0000080  /* Ok f
5f20: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
5f30: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
5f40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
5f50: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
5f60: 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20  0000100  /* VFS 
5f70: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5f80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
5f90: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
5fa0: 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20  0000200  /* VFS 
5fb0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
5fc0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
5fd0: 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30  SIENT_DB     0x0
5fe0: 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20  0000400  /* VFS 
5ff0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
6000: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
6010: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
6020: 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20  0000800  /* VFS 
6030: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
6040: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
6050: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
6060: 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20  0001000  /* VFS 
6070: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
6080: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
6090: 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30  OURNAL       0x0
60a0: 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20  0002000  /* VFS 
60b0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
60c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
60d0: 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30  ER_JOURNAL   0x0
60e0: 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20  0004000  /* VFS 
60f0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
6100: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
6110: 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30  TEX          0x0
6120: 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0008000  /* Ok f
6130: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
6140: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
6150: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
6160: 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30  MUTEX        0x0
6170: 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0010000  /* Ok f
6180: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
6190: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
61a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
61b0: 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30  EDCACHE      0x0
61c0: 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0020000  /* Ok f
61d0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
61e0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
61f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
6200: 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30  ATECACHE     0x0
6210: 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0040000  /* Ok f
6220: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
6230: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
6240: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20  SQLITE_OPEN_WAL 
6250: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6260: 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20  0080000  /* VFS 
6270: 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65  only */../* Rese
6280: 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20  rved:           
6290: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
62a0: 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a  00F00000 */../*.
62b0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76  ** CAPI3REF: Dev
62c0: 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74  ice Characterist
62d0: 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44  ics.**.** The xD
62e0: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
62f0: 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  tics method of t
6300: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
6310: 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63  ethods].** objec
6320: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  t returns an int
6330: 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20  eger which is a 
6340: 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a  vector of these.
6350: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
6360: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
6370: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
6380: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
6390: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
63a0: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
63b0: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
63c0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
63d0: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
63e0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
63f0: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
6400: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
6410: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
6420: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
6430: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
6440: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
6450: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
6460: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
6470: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
6480: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
6490: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
64a0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
64b0: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
64c0: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
64d0: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
64e0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
64f0: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
6500: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
6510: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
6520: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
6530: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
6540: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
6550: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
6560: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
6570: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
6580: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
6590: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
65a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
65b0: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
65c0: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
65d0: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
65e0: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
65f0: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
6600: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
6610: 72 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c  rite().  The SQL
6620: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
6630: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72  AFE_OVERWRITE pr
6640: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
6650: 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f  t.** after reboo
6660: 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72  t following a cr
6670: 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73  ash or power los
6680: 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65  s, the only byte
6690: 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74  s in a.** file t
66a0: 68 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e  hat were written
66b0: 20 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74   at the applicat
66c0: 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20  ion level might 
66d0: 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  have changed.** 
66e0: 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e  and that adjacen
66f0: 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79  t bytes, even by
6700: 74 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73  tes within the s
6710: 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a  ame sector are.*
6720: 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  * guaranteed to 
6730: 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54  be unchanged.  T
6740: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6750: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
6760: 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e  _OPEN.** flag in
6770: 64 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69  dicate that a fi
6780: 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c  le cannot be del
6790: 65 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20  eted when open. 
67a0: 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49   The.** SQLITE_I
67b0: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66  OCAP_IMMUTABLE f
67c0: 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68  lag indicates th
67d0: 61 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f  at the file is o
67e0: 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  n.** read-only m
67f0: 65 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20  edia and cannot 
6800: 62 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20  be changed even 
6810: 62 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74  by processes wit
6820: 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72  h.** elevated pr
6830: 69 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65  ivileges..*/.#de
6840: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6850: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
6860: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6870: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
6880: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
6890: 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20  12              
68a0: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
68b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
68c0: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
68d0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
68e0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
68f0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20  _IOCAP_ATOMIC2K 
6900: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6910: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
6920: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6930: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20  OMIC4K          
6940: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
6950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6960: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
6970: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6980: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
6990: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
69a0: 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20  IC16K           
69b0: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64     0x00000040.#d
69c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
69d0: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20  AP_ATOMIC32K    
69e0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
69f0: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0080.#define SQL
6a00: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6a10: 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  64K             
6a20: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
6a30: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6a40: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
6a50: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
6a60: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6a70: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
6a80: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30  AL             0
6a90: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e  x00000400.#defin
6aa0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
6ab0: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
6ac0: 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30  OPEN  0x00000800
6ad0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6ae0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
6af0: 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30  OVERWRITE    0x0
6b00: 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20  0001000.#define 
6b10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
6b20: 55 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  UTABLE          
6b30: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a      0x00002000..
6b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6b50: 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76  File Locking Lev
6b60: 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  els.**.** SQLite
6b70: 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65   uses one of the
6b80: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
6b90: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  s as the second.
6ba0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  ** argument to c
6bb0: 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f  alls it makes to
6bc0: 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64   the xLock() and
6bd0: 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f   xUnlock() metho
6be0: 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c  ds.** of an [sql
6bf0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6c00: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66   object..*/.#def
6c10: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6c20: 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a  NONE          0.
6c30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6c40: 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20  OCK_SHARED      
6c50: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
6c60: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
6c70: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
6c80: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
6c90: 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66  ING       3.#def
6ca0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6cb0: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a  EXCLUSIVE     4.
6cc0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6cd0: 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   Synchronization
6ce0: 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a   Type Flags.**.*
6cf0: 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  * When SQLite in
6d00: 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28  vokes the xSync(
6d10: 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a  ) method of an.*
6d20: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
6d30: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74  thods] object it
6d40: 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74   uses a combinat
6d50: 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  ion of.** these 
6d60: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
6d70: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
6d80: 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ument..**.** Whe
6d90: 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  n the SQLITE_SYN
6da0: 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20  C_DATAONLY flag 
6db0: 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e  is used, it mean
6dc0: 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79  s that the.** sy
6dd0: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c  nc operation onl
6de0: 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68  y needs to flush
6df0: 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74   data to mass st
6e00: 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a  orage.  Inode.**
6e10: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65   information nee
6e20: 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64  d not be flushed
6e30: 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  . If the lower f
6e40: 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20  our bits of the 
6e50: 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51  flag.** equal SQ
6e60: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
6e70: 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20  , that means to 
6e80: 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  use normal fsync
6e90: 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a  () semantics..**
6ea0: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
6eb0: 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51  ur bits equal SQ
6ec0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
6ed0: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f  that means.** to
6ee0: 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74   use Mac OS X st
6ef0: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73  yle fullsync ins
6f00: 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e  tead of fsync().
6f10: 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f  .**.** Do not co
6f20: 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45  nfuse the SQLITE
6f30: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
6f40: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6f50: 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20  L flags.** with 
6f60: 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  the [PRAGMA sync
6f70: 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20  hronous]=NORMAL 
6f80: 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  and [PRAGMA sync
6f90: 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a  hronous]=FULL.**
6fa0: 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20   settings.  The 
6fb0: 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61  [synchronous pra
6fc0: 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20  gma] determines 
6fd0: 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68  when calls to th
6fe0: 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d  e.** xSync VFS m
6ff0: 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20  ethod occur and 
7000: 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c  applies uniforml
7010: 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61  y across all pla
7020: 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53  tforms..** The S
7030: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
7040: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
7050: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74  C_FULL flags det
7060: 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e  ermine how.** en
7070: 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72  ergetic or rigor
7080: 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20  ous or forceful 
7090: 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69  the sync operati
70a0: 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f  ons are and.** o
70b0: 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65  nly make a diffe
70c0: 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58  rence on Mac OSX
70d0: 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74   for the default
70e0: 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a   SQLite code..**
70f0: 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46   (Third-party VF
7100: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7110: 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b  s might also mak
7120: 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
7130: 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c  n.** between SQL
7140: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
7150: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
7160: 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20  FULL, but among 
7170: 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67  the.** operating
7180: 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c   systems nativel
7190: 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  y supported by S
71a0: 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20  QLite, only Mac 
71b0: 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f  OSX.** cares abo
71c0: 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63  ut the differenc
71d0: 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e.).*/.#define S
71e0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
71f0: 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32  L        0x00002
7200: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7210: 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20  SYNC_FULL       
7220: 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69     0x00003.#defi
7230: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  ne SQLITE_SYNC_D
7240: 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30  ATAONLY      0x0
7250: 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0010../*.** CAPI
7260: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
7270: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e  ce Open File Han
7280: 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71  dle.**.** An [sq
7290: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
72a0: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
72b0: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68   open file in th
72c0: 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  e .** [sqlite3_v
72d0: 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63  fs | OS interfac
72e0: 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76  e layer].  Indiv
72f0: 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61  idual OS interfa
7300: 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ce.** implementa
7310: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61  tions will.** wa
7320: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74  nt to subclass t
7330: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70  his object by ap
7340: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e  pending addition
7350: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72  al fields.** for
7360: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20   their own use. 
7370: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e   The pMethods en
7380: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72  try is a pointer
7390: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
73a0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
73b0: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
73c0: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70  es methods for p
73d0: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f  erforming.** I/O
73e0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
73f0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f  he open file..*/
7400: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
7410: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c  sqlite3_file sql
7420: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63  ite3_file;.struc
7430: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b  t sqlite3_file {
7440: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20  .  const struct 
7450: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7460: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f  ds *pMethods;  /
7470: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e  * Methods for an
7480: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b   open file */.};
7490: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
74a0: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46  : OS Interface F
74b0: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68  ile Virtual Meth
74c0: 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ods Object.**.**
74d0: 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e   Every file open
74e0: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
74f0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
7500: 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61  thod populates a
7510: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  n.** [sqlite3_fi
7520: 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20  le] object (or, 
7530: 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61  more commonly, a
7540: 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
7550: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7560: 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20  e] object) with 
7570: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
7580: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
7590: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73   object..** This
75a0: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
75b0: 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64  the methods used
75c0: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
75d0: 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ous operations.*
75e0: 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70  * against the op
75f0: 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e  en file represen
7600: 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ted by the [sqli
7610: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7620: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ..**.** If the [
7630: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7640: 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74  n] method sets t
7650: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
7660: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
7670: 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55   .** to a non-NU
7680: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
7690: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f   the sqlite3_io_
76a0: 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d  methods.xClose m
76b0: 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20  ethod.** may be 
76c0: 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20  invoked even if 
76d0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
76e0: 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64  .xOpen] reported
76f0: 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e   that it failed.
7700: 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61    The.** only wa
7710: 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63  y to prevent a c
7720: 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f  all to xClose fo
7730: 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64  llowing a failed
7740: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7750: 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74  pen].** is for t
7760: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
7770: 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68  xOpen] to set th
7780: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
7790: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a  Methods element.
77a0: 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ** to NULL..**.*
77b0: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
77c0: 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61  ment to xSync ma
77d0: 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  y be one of [SQL
77e0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d  ITE_SYNC_NORMAL]
77f0: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53   or.** [SQLITE_S
7800: 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20  YNC_FULL].  The 
7810: 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20  first choice is 
7820: 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  the normal fsync
7830: 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ()..** The secon
7840: 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61  d choice is a Ma
7850: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
7860: 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c  lsync.  The [SQL
7870: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
7880: 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62  Y].** flag may b
7890: 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64  e ORed in to ind
78a0: 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20  icate that only 
78b0: 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20  the data of the 
78c0: 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20  file.** and not 
78d0: 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20  its inode needs 
78e0: 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a  to be synced..**
78f0: 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20  .** The integer 
7900: 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28  values to xLock(
7910: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
7920: 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75  are one of.** <u
7930: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
7940: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a  TE_LOCK_NONE],.*
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 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
7970: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7980: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20  K_RESERVED],.** 
7990: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
79a0: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a  K_PENDING], or.*
79b0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
79c0: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a  OCK_EXCLUSIVE]..
79d0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63  ** </ul>.** xLoc
79e0: 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68  k() increases th
79f0: 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28  e lock. xUnlock(
7a00: 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20  ) decreases the 
7a10: 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68  lock..** The xCh
7a20: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28  eckReservedLock(
7a30: 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20  ) method checks 
7a40: 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61  whether any data
7a50: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
7a60: 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68  .** either in th
7a70: 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e  is process or in
7a80: 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63   some other proc
7a90: 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20  ess, is holding 
7aa0: 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50  a RESERVED,.** P
7ab0: 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55  ENDING, or EXCLU
7ac0: 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  SIVE lock on the
7ad0: 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72   file.  It retur
7ae0: 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75  ns true.** if su
7af0: 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73  ch a lock exists
7b00: 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72   and false other
7b10: 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  wise..**.** The 
7b20: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
7b30: 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72  ethod is a gener
7b40: 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ic interface tha
7b50: 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a  t allows custom.
7b60: 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ** VFS implement
7b70: 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74  ations to direct
7b80: 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70  ly control an op
7b90: 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68  en file using th
7ba0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
7bb0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e  le_control()] in
7bc0: 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65  terface.  The se
7bd0: 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65  cond "op" argume
7be0: 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65  nt is an.** inte
7bf0: 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65  ger opcode.  The
7c00: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
7c10: 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69  is a generic poi
7c20: 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f  nter intended to
7c30: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  .** point to a s
7c40: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61  tructure that ma
7c50: 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65  y contain argume
7c60: 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20  nts or space in 
7c70: 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74  which to.** writ
7c80: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e  e return values.
7c90: 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73    Potential uses
7ca0: 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f   for xFileContro
7cb0: 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20  l() might be.** 
7cc0: 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61  functions to ena
7cd0: 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63  ble blocking loc
7ce0: 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73  ks with timeouts
7cf0: 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a  , to change the.
7d00: 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74  ** locking strat
7d10: 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  egy (for example
7d20: 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65   to use dot-file
7d30: 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75   locks), to inqu
7d40: 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65  ire.** about the
7d50: 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63   status of a loc
7d60: 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73  k, or to break s
7d70: 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65  tale locks.  The
7d80: 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20   SQLite.** core 
7d90: 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63  reserves all opc
7da0: 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31  odes less than 1
7db0: 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75  00 for its own u
7dc0: 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63  se..** A [file c
7dd0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c  ontrol opcodes |
7de0: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
7df0: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
7e00: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
7e10: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
7e20: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
7e30: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
7e40: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
7e50: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
7e60: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
7e70: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
7e80: 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  .  VFS implement
7e90: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a  ations should.**
7ea0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
7eb0: 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69  NOTFOUND] for fi
7ec0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
7ed0: 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  es that they do 
7ee0: 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65  not.** recognize
7ef0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
7f00: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
7f10: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
7f20: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
7f30: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
7f40: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
7f50: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
7f60: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
7f70: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
7f80: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
7f90: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
7fa0: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
7fb0: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
7fc0: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
7fd0: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
7fe0: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
7ff0: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
8000: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
8010: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
8020: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
8030: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
8040: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8050: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
8060: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8070: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <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 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <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 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
80c0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
80d0: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
80e0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
80f0: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
8100: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8110: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
8120: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8130: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
8140: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8150: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
8160: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8170: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
8180: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8190: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
81a0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
81b0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
81c0: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
81d0: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
81e0: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
81f0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
8200: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
8210: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
8220: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
8230: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
8240: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
8250: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
8260: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
8270: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
8280: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
8290: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
82a0: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
82b0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
82c0: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
82d0: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
82e0: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
82f0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
8300: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
8310: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
8320: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
8330: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
8340: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
8350: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
8360: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
8370: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
8380: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
8390: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
83a0: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
83b0: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
83c0: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
83d0: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
83e0: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
83f0: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
8400: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
8410: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
8420: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
8430: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
8440: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
8450: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
8460: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
8470: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
8480: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
8490: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
84a0: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
84b0: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
84c0: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
84d0: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
84e0: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
84f0: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
8500: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
8510: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
8520: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
8530: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
8540: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8550: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
8560: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
8570: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
8580: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
8590: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
85a0: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
85b0: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
85c0: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
85d0: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
85e0: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
85f0: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
8600: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8610: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
8620: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
8630: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8640: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
8650: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
8660: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
8670: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
8680: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
8690: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
86a0: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
86b0: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
86c0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
86d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
86e0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
86f0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
8700: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
8710: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
8720: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
8730: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
8740: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
8750: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
8760: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
8770: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
8780: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
8790: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
87a0: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
87b0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
87c0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
87d0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
87e0: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
87f0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
8800: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8810: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
8820: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
8830: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
8840: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
8850: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
8860: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
8870: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
8880: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
8890: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
88a0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
88b0: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
88c0: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
88d0: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
88e0: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
88f0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
8900: 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29  .  int (*xFetch)
8910: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8920: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
8930: 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76  fst, int iAmt, v
8940: 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74  oid **pp);.  int
8950: 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c   (*xUnfetch)(sql
8960: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8970: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
8980: 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20   void *p);.  /* 
8990: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
89a0: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
89b0: 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64  ion 3 */.  /* Ad
89c0: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
89d0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
89e0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
89f0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
8a00: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
8a10: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
8a20: 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  codes.** KEYWORD
8a30: 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  S: {file control
8a40: 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20   opcodes} {file 
8a50: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a  control opcode}.
8a60: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
8a70: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
8a80: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
8a90: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
8aa0: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
8ab0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
8ac0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
8ad0: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
8ae0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
8af0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  .** interface..*
8b00: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8b10: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
8b20: 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54  LOCKSTATE]].** T
8b30: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8b40: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
8b50: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
8b60: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
8b70: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
8b80: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
8b90: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
8ba0: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
8bb0: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
8bc0: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
8bd0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
8be0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
8bf0: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
8c00: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
8c10: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
8c20: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
8c30: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
8c40: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
8c50: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
8c60: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
8c70: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
8c80: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
8c90: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
8ca0: 67 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76  g and is only av
8cb0: 61 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65  ailable when the
8cc0: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20   SQLITE_TEST.** 
8cd0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
8ce0: 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
8cf0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8d00: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8d10: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
8d20: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
8d30: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8d40: 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69   by SQLite to gi
8d50: 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61  ve the VFS.** la
8d60: 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f  yer a hint of ho
8d70: 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61  w large the data
8d80: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67  base file will g
8d90: 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67  row to be during
8da0: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
8db0: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68  transaction.  Th
8dc0: 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67  is hint is not g
8dd0: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
8de0: 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a  accurate but it.
8df0: 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73  ** is often clos
8e00: 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69  e.  The underlyi
8e10: 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f  ng VFS might cho
8e20: 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61  ose to prealloca
8e30: 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  te database.** f
8e40: 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20  ile space based 
8e50: 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20  on this hint in 
8e60: 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72  order to help wr
8e70: 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61  ites to the data
8e80: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e  base.** file run
8e90: 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c   faster..**.** <
8ea0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8eb0: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a  L_CHUNK_SIZE]].*
8ec0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
8ed0: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20  NTL_CHUNK_SIZE] 
8ee0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
8ef0: 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74  o request that t
8f00: 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64  he VFS.** extend
8f10: 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20  s and truncates 
8f20: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
8f30: 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61  e in chunks of a
8f40: 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a   size specified.
8f50: 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20  ** by the user. 
8f60: 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
8f70: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
8f80: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
8f90: 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74  should .** point
8fa0: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28   to an integer (
8fb0: 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69  type int) contai
8fc0: 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75  ning the new chu
8fd0: 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a  nk-size to use.*
8fe0: 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61  * for the nomina
8ff0: 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c  ted database. Al
9000: 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73  locating databas
9010: 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20  e file space in 
9020: 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20  large.** chunks 
9030: 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69  (say 1MB at a ti
9040: 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20  me), may reduce 
9050: 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67  file-system frag
9060: 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  mentation and.**
9070: 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d   improve perform
9080: 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73  ance on some sys
9090: 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tems..**.** <li>
90a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  [[SQLITE_FCNTL_F
90b0: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a  ILE_POINTER]].**
90c0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
90d0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
90e0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
90f0: 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e  to obtain a poin
9100: 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ter.** to the [s
9110: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
9120: 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  ect associated w
9130: 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
9140: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
9150: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68  nection.  See th
9160: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
9170: 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d  control()] docum
9180: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
9190: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
91a0: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  mation..**.** <l
91b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
91c0: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a  _SYNC_OMITTED]].
91d0: 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20  ** No longer in 
91e0: 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  use..**.** <li>[
91f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
9200: 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NC]].** The [SQL
9210: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20  ITE_FCNTL_SYNC] 
9220: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
9230: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
9240: 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20  y SQLite and.** 
9250: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
9260: 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f  immediately befo
9270: 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  re the xSync met
9280: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  hod is invoked o
9290: 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  n a.** database 
92a0: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e  file descriptor.
92b0: 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e   Or, if the xSyn
92c0: 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20  c method is not 
92d0: 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61  invoked .** beca
92e0: 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73  use the user has
92f0: 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69   configured SQLi
9300: 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41  te with .** [PRA
9310: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20  GMA synchronous 
9320: 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f  | PRAGMA synchro
9330: 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20  nous=OFF] it is 
9340: 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65  invoked in place
9350: 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e   .** of the xSyn
9360: 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73  c method. In mos
9370: 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69  t cases, the poi
9380: 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61  nter argument pa
9390: 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69  ssed with.** thi
93a0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
93b0: 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c  s NULL. However,
93c0: 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65   if the database
93d0: 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73   file is being s
93e0: 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74  ynced.** as part
93f0: 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61   of a multi-data
9400: 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65  base commit, the
9410: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
9420: 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e   to a nul-termin
9430: 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63  ated.** string c
9440: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72  ontaining the tr
9450: 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65  ansactions maste
9460: 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e  r-journal file n
9470: 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20  ame. VFSes that 
9480: 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  .** do not need 
9490: 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75  this signal shou
94a0: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
94b0: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  re this opcode. 
94c0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a  Applications .**
94d0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
94e0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
94f0: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
9500: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
9510: 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64  ing so may .** d
9520: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61  isrupt the opera
9530: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
9540: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
9550: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
9560: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
9570: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
9580: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a  MIT_PHASETWO]].*
9590: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
95a0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
95b0: 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  TWO] opcode is g
95c0: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
95d0: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  lly by SQLite.**
95e0: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65   and sent to the
95f0: 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61   VFS after a tra
9600: 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65  nsaction has bee
9610: 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65  n committed imme
9620: 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62  diately.** but b
9630: 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61  efore the databa
9640: 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20  se is unlocked. 
9650: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  VFSes that do no
9660: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
9670: 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c  al.** should sil
9680: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
9690: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
96a0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
96b0: 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
96c0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
96d0: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63  )] with this opc
96e0: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
96f0: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
9700: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  .** operation of
9710: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
9720: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72   VFSes that do r
9730: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
9740: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9750: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
9760: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  ETRY]].** ^The [
9770: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
9780: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
9790: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
97a0: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
97b0: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
97c0: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
97d0: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
97e0: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
97f0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
9800: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
9810: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  er to provide ro
9820: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20  bustness in the 
9830: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61  presence of.** a
9840: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61  nti-virus progra
9850: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ms.  By default,
9860: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
9870: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65   will retry file
9880: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77   read,.** file w
9890: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64  rite, and file d
98a0: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  elete operations
98b0: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
98c0: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
98d0: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
98e0: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
98f0: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
9900: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
9910: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
9920: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
9930: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
9940: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
9950: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
9960: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
9970: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73  these two values
9980: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
9990: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
99a0: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
99b0: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
99c0: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
99d0: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
99e0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
99f0: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
9a00: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
9a10: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
9a20: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9a30: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
9a40: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
9a50: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
9a60: 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79   i the new retry
9a70: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73   count and the s
9a80: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  econd.** integer
9a90: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20   is the delay.  
9aa0: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65  If either intege
9ab0: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
9ac0: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a  hen the setting.
9ad0: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
9ae0: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68  d but instead th
9af0: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
9b00: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73   that setting is
9b10: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f   written.** into
9b20: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79   the array entry
9b30: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63  , allowing the c
9b40: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74  urrent retry set
9b50: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69  tings to be.** i
9b60: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
9b70: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65  e zDbName parame
9b80: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  ter is ignored..
9b90: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9ba0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
9bb0: 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  _WAL]].** ^The [
9bc0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
9bd0: 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65  SIST_WAL] opcode
9be0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9bf0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9c00: 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20  persistent [WAL 
9c10: 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f  | Write Ahead Lo
9c20: 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20  g] setting.  By 
9c30: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78  default, the aux
9c40: 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20  iliary.** write 
9c50: 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68  ahead log and sh
9c60: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
9c70: 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73  s used for trans
9c80: 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a  action control.*
9c90: 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  * are automatica
9ca0: 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e  lly deleted when
9cb0: 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e   the latest conn
9cc0: 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61  ection to the da
9cd0: 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73  tabase.** closes
9ce0: 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69  .  Setting persi
9cf0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63  stent WAL mode c
9d00: 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65  auses those file
9d10: 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74  s to persist aft
9d20: 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65  er.** close.  Pe
9d30: 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c  rsisting the fil
9d40: 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65  es is useful whe
9d50: 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65  n other processe
9d60: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a  s that do not.**
9d70: 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d   have write perm
9d80: 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69  ission on the di
9d90: 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69  rectory containi
9da0: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
9db0: 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20  file want.** to 
9dc0: 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73  read the databas
9dd0: 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57  e file, as the W
9de0: 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  AL and shared me
9df0: 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20  mory files must 
9e00: 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65  exist.** in orde
9e10: 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  r for the databa
9e20: 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c  se to be readabl
9e30: 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  e.  The fourth p
9e40: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
9e50: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9e60: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
9e70: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
9e80: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
9e90: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
9ea0: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
9eb0: 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69  to disable persi
9ec0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f  stent WAL mode o
9ed0: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65  r 1 to enable pe
9ee0: 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20  rsistent.** WAL 
9ef0: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
9f00: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
9f10: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
9f20: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
9f30: 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73  rent.** WAL pers
9f40: 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e  istence setting.
9f50: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9f60: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
9f70: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  AFE_OVERWRITE]].
9f80: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
9f90: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
9fa0: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
9fb0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
9fc0: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
9fd0: 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77   persistent "pow
9fe0: 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65  ersafe-overwrite
9ff0: 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74  " or "PSOW" sett
a000: 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73  ing.  The PSOW s
a010: 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d  etting.** determ
a020: 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45  ines the [SQLITE
a030: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
a040: 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20  _OVERWRITE] bit 
a050: 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63  of the.** xDevic
a060: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
a070: 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f   methods. The fo
a080: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
a090: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
a0a0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
a0b0: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
a0c0: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
a0d0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
a0e0: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
a0f0: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
a100: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
a110: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
a120: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20   zero-damage.** 
a130: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
a140: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
a150: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
a160: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
a170: 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d  rent.** zero-dam
a180: 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67  age mode setting
a190: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a1a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
a1b0: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
a1c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
a1d0: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
a1e0: 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  s invoked by SQL
a1f0: 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e  ite after openin
a200: 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61  g.** a write tra
a210: 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69  nsaction to indi
a220: 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73  cate that, unles
a230: 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62  s it is rolled b
a240: 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20  ack for some.** 
a250: 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69  reason, the enti
a260: 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  re database file
a270: 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69   will be overwri
a280: 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72  tten by the curr
a290: 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ent .** transact
a2a0: 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65  ion. This is use
a2b0: 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72  d by VACUUM oper
a2c0: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ations..**.** <l
a2d0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a2e0: 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54  _VFSNAME]].** ^T
a2f0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a300: 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65  _VFSNAME] opcode
a310: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
a320: 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  obtain the names
a330: 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65   of.** all [VFSe
a340: 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  s] in the VFS st
a350: 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20  ack.  The names 
a360: 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73  are of all VFS s
a370: 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  hims and the.** 
a380: 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76  final bottom-lev
a390: 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74  el VFS are writt
a3a0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
a3b0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
a3c0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
a3d0: 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75  ()] and the resu
a3e0: 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  lt is stored in 
a3f0: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
a400: 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66  le.** that the f
a410: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a420: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  of [sqlite3_file
a430: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e  _control()] poin
a440: 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61  ts to..** The ca
a450: 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69  ller is responsi
a460: 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20  ble for freeing 
a470: 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20  the memory when 
a480: 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a  done.  As with.*
a490: 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72  * all file-contr
a4a0: 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72  ol actions, ther
a4b0: 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65  e is no guarante
a4c0: 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c  e that this will
a4d0: 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20   actually.** do 
a4e0: 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65  anything.  Calle
a4f0: 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61  rs should initia
a500: 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76  lize the char* v
a510: 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c  ariable to a NUL
a520: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20  L.** pointer in 
a530: 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63  case this file-c
a540: 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d  ontrol is not im
a550: 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73  plemented.  This
a560: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
a570: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
a580: 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20   diagnostic use 
a590: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  only..**.** <li>
a5a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
a5b0: 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e  RAGMA]].** ^When
a5c0: 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20  ever a [PRAGMA] 
a5d0: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72  statement is par
a5e0: 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f  sed, an [SQLITE_
a5f0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a  FCNTL_PRAGMA] .*
a600: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  * file control i
a610: 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70  s sent to the op
a620: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  en [sqlite3_file
a630: 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70  ] object corresp
a640: 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65  onding.** to the
a650: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
a660: 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67  o which the prag
a670: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66  ma statement ref
a680: 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65  ers. ^The argume
a690: 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51  nt.** to the [SQ
a6a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a6b0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
a6c0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a  is an array of.*
a6d0: 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  * pointers to st
a6e0: 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69  rings (char**) i
a6f0: 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f  n which the seco
a700: 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68  nd element of th
a710: 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68  e array.** is th
a720: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72  e name of the pr
a730: 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69  agma and the thi
a740: 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68  rd element is th
a750: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  e argument to th
a760: 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e  e.** pragma or N
a770: 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d  ULL if the pragm
a780: 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e  a has no argumen
a790: 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  t.  ^The handler
a7a0: 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49   for an.** [SQLI
a7b0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a7c0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61   file control ca
a7d0: 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b  n optionally mak
a7e0: 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d  e the first elem
a7f0: 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68  ent.** of the ch
a800: 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f  ar** argument po
a810: 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
a820: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
a830: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
a840: 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69  ].** or the equi
a850: 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20  valent and that 
a860: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f  string will beco
a870: 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  me the result of
a880: 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a   the pragma or.*
a890: 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  * the error mess
a8a0: 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d  age if the pragm
a8b0: 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65  a fails. ^If the
a8c0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
a8d0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
a8e0: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
a8f0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
a900: 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a  , then normal .*
a910: 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65  * [PRAGMA] proce
a920: 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e  ssing continues.
a930: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
a940: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
a950: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
a960: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
a970: 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61  OK], then the pa
a980: 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61  rser assumes tha
a990: 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73  t the.** VFS has
a9a0: 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41   handled the PRA
a9b0: 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74  GMA itself and t
a9c0: 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61  he parser genera
a9d0: 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70  tes a no-op.** p
a9e0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
a9f0: 74 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69  t if result stri
aa00: 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74  ng is NULL, or t
aa10: 68 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f  hat returns a co
aa20: 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  py.** of the res
aa30: 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68  ult string if th
aa40: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d  e string is non-
aa50: 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  NULL..** ^If the
aa60: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
aa70: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
aa80: 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  rol returns.** a
aa90: 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f  ny result code o
aaa0: 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
aab0: 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45  E_OK] or [SQLITE
aac0: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74  _NOTFOUND], that
aad0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74   means.** that t
aae0: 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72  he VFS encounter
aaf0: 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c  ed an error whil
ab00: 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b  e handling the [
ab10: 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a  PRAGMA] and the.
ab20: 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f  ** compilation o
ab30: 66 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69  f the PRAGMA fai
ab40: 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ls with an error
ab50: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
ab60: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
ab70: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63   file control oc
ab80: 63 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69  curs at the begi
ab90: 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20  nning of pragma 
aba0: 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73  statement analys
abb0: 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20  is and so.** it 
abc0: 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72  is able to overr
abd0: 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52  ide built-in [PR
abe0: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73  AGMA] statements
abf0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
ac00: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
ac10: 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65  ANDLER]].** ^The
ac20: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42   [SQLITE_FCNTL_B
ac30: 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66  USYHANDLER].** f
ac40: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20  ile-control may 
ac50: 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51  be invoked by SQ
ac60: 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61  Lite on the data
ac70: 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65  base file handle
ac80: 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65  .** shortly afte
ac90: 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69  r it is opened i
aca0: 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69  n order to provi
acb0: 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20  de a custom VFS 
acc0: 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74  with access.** t
acd0: 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  o the connection
ace0: 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63  s busy-handler c
acf0: 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67  allback. The arg
ad00: 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65  ument is of type
ad10: 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20   (void **).** - 
ad20: 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20  an array of two 
ad30: 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e  (void *) values.
ad40: 20 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64   The first (void
ad50: 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69   *) actually poi
ad60: 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63  nts.** to a func
ad70: 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e  tion of type (in
ad80: 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20  t (*)(void *)). 
ad90: 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f  In order to invo
ada0: 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ke the connectio
adb0: 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c  ns.** busy-handl
adc0: 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  er, this functio
add0: 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f  n should be invo
ade0: 6b 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63  ked with the sec
adf0: 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a  ond (void *) in.
ae00: 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20  ** the array as 
ae10: 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e  the only argumen
ae20: 74 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  t. If it returns
ae30: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
ae40: 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
ae50: 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69   should be retri
ae60: 65 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e  ed. If it return
ae70: 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74  s zero, the cust
ae80: 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62  om VFS should ab
ae90: 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72  andon the.** cur
aea0: 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a  rent operation..
aeb0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
aec0: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
aed0: 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c  ENAME]].** ^Appl
aee0: 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f  ication can invo
aef0: 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  ke the [SQLITE_F
af00: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
af10: 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a  E] file-control.
af20: 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74  ** to have SQLit
af30: 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20  e generate a.** 
af40: 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61  temporary filena
af50: 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  me using the sam
af60: 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74  e algorithm that
af70: 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20   is followed to 
af80: 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70  generate.** temp
af90: 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20  orary filenames 
afa0: 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20  for TEMP tables 
afb0: 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e  and other intern
afc0: 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a  al uses.  The.**
afd0: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
afe0: 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69   be a char** whi
aff0: 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65  ch will be fille
b000: 64 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e  d with the filen
b010: 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69  ame.** written i
b020: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
b030: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
b040: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68  3_malloc()].  Th
b050: 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a  e caller should.
b060: 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ** invoke [sqlit
b070: 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68  e3_free()] on th
b080: 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69  e result to avoi
b090: 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e  d a memory leak.
b0a0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b0b0: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
b0c0: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
b0d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
b0e0: 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  SIZE] file contr
b0f0: 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75  ol is used to qu
b100: 65 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a  ery or set the.*
b110: 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  * maximum number
b120: 20 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77   of bytes that w
b130: 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20  ill be used for 
b140: 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f  memory-mapped I/
b150: 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  O..** The argume
b160: 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
b170: 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79  to a value of ty
b180: 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  pe sqlite3_int64
b190: 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61   that.** is an a
b1a0: 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20  dvisory maximum 
b1b0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
b1c0: 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d  in the file to m
b1d0: 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a  emory map.  The.
b1e0: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76  ** pointer is ov
b1f0: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
b200: 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54  he old value.  T
b210: 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20  he limit is not 
b220: 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68  changed if.** th
b230: 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c  e value original
b240: 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73  ly pointed to is
b250: 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73   negative, and s
b260: 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69  o the current li
b270: 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71  mit .** can be q
b280: 75 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e  ueried by passin
b290: 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74  g in a pointer t
b2a0: 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  o a negative num
b2b0: 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69  ber.  This.** fi
b2c0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le-control is us
b2d0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
b2e0: 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47   implement [PRAG
b2f0: 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a  MA mmap_size]..*
b300: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b310: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a  E_FCNTL_TRACE]].
b320: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
b330: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65  CNTL_TRACE] file
b340: 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65   control provide
b350: 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72  s advisory infor
b360: 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65  mation.** to the
b370: 20 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20   VFS about what 
b380: 74 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72  the higher layer
b390: 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20  s of the SQLite 
b3a0: 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e  stack are doing.
b3b0: 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f  .** This file co
b3c0: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79  ntrol is used by
b3d0: 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69   some VFS activi
b3e0: 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d  ty tracing [shim
b3f0: 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  s]..** The argum
b400: 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65  ent is a zero-te
b410: 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e  rminated string.
b420: 20 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20    Higher layers 
b430: 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65  in the.** SQLite
b440: 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72   stack may gener
b450: 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66  ate instances of
b460: 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72   this file contr
b470: 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51  ol if.** the [SQ
b480: 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54  LITE_USE_FCNTL_T
b490: 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  RACE] compile-ti
b4a0: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
b4b0: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  bled..**.** <li>
b4c0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48  [[SQLITE_FCNTL_H
b4d0: 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68  AS_MOVED]].** Th
b4e0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b4f0: 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20  HAS_MOVED] file 
b500: 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65  control interpre
b510: 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20  ts its argument 
b520: 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  as a.** pointer 
b530: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e  to an integer an
b540: 64 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f  d it writes a bo
b550: 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20  olean into that 
b560: 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e  integer dependin
b570: 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20  g.** on whether 
b580: 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20  or not the file 
b590: 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64  has been renamed
b5a0: 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65  , moved, or dele
b5b0: 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20  ted since it.** 
b5c0: 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64  was first opened
b5d0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b5e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
b5f0: 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a  _SET_HANDLE]].**
b600: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b610: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
b620: 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  DLE] opcode is u
b630: 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e  sed for debuggin
b640: 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  g.  This.** opco
b650: 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46  de causes the xF
b660: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
b670: 64 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69  d to swap the fi
b680: 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74  le handle with t
b690: 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65  he one.** pointe
b6a0: 64 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67  d to by the pArg
b6b0: 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73   argument.  This
b6c0: 20 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75   capability is u
b6d0: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
b6e0: 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e  ng.** and only n
b6f0: 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f  eeds to be suppo
b700: 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45  rted when SQLITE
b710: 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64  _TEST is defined
b720: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b730: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
b740: 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  LOCK]].** The [S
b750: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f  QLITE_FCNTL_WAL_
b760: 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e  BLOCK] is a sign
b770: 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61  al to the VFS la
b780: 79 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68  yer that it migh
b790: 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67  t.** be advantag
b7a0: 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e  eous to block on
b7b0: 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f   the next WAL lo
b7c0: 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69  ck if the lock i
b7d0: 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c  s not immediatel
b7e0: 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20  y.** available. 
b7f0: 20 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74   The WAL subsyst
b800: 65 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73  em issues this s
b810: 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72  ignal during rar
b820: 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63  e.** circumstanc
b830: 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  es in order to f
b840: 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74  ix a problem wit
b850: 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72  h priority inver
b860: 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  sion..** Applica
b870: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d  tions should <em
b880: 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68  >not</em> use th
b890: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e  is file-control.
b8a0: 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  .**.** </ul>.*/.
b8b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b8c0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20  CNTL_LOCKSTATE  
b8d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
b8e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b8f0: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
b900: 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64  YFILE       2.#d
b910: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b920: 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_SET_LOCKPROXY
b930: 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65  FILE       3.#de
b940: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b950: 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  L_LAST_ERRNO    
b960: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
b970: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b980: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
b990: 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
b9a0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b9b0: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20  CHUNK_SIZE      
b9c0: 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
b9d0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  e SQLITE_FCNTL_F
b9e0: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  ILE_POINTER     
b9f0: 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
ba00: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
ba10: 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20  NC_OMITTED      
ba20: 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
ba30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
ba40: 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20  32_AV_RETRY     
ba50: 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
ba60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
ba70: 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20  IST_WAL         
ba80: 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
ba90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
baa0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
bab0: 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    11.#define SQL
bac0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
bad0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
bae0: 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   12.#define SQLI
baf0: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
bb00: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
bb10: 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  13.#define SQLIT
bb20: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20  E_FCNTL_PRAGMA  
bb30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
bb40: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
bb50: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
bb60: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35  ER            15
bb70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bb80: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
bb90: 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a  ME           16.
bba0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bbb0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  CNTL_MMAP_SIZE  
bbc0: 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23              18.#
bbd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bbe0: 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20  NTL_TRACE       
bbf0: 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64             19.#d
bc00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bc10: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20  TL_HAS_MOVED    
bc20: 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65            20.#de
bc30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bc40: 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  L_SYNC          
bc50: 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66           21.#def
bc60: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bc70: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
bc80: 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69          22.#defi
bc90: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bca0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
bcb0: 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e         23.#defin
bcc0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
bcd0: 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20  AL_BLOCK        
bce0: 20 20 20 20 20 20 32 34 0a 0a 2f 2a 20 64 65 70        24../* dep
bcf0: 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f  recated names */
bd00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bd10: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
bd20: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43  E      SQLITE_FC
bd30: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
bd40: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51  YFILE.#define SQ
bd50: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_SET_LOCKPRO
bd60: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49  XYFILE      SQLI
bd70: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43  TE_FCNTL_SET_LOC
bd80: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69  KPROXYFILE.#defi
bd90: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
bda0: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
bdb0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
bdc0: 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a  ST_ERRNO.../*.**
bdd0: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
bde0: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68   Handle.**.** Th
bdf0: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
be00: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
be10: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
be20: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
be30: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
be40: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
be50: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
be60: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
be70: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
be80: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
be90: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
bea0: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
beb0: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
bec0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
bed0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
bee0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
bef0: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
bf00: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
bf10: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
bf20: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
bf30: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
bf40: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
bf50: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
bf60: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62   OS Interface Ob
bf70: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ject.**.** An in
bf80: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71  stance of the sq
bf90: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
bfa0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
bfb0: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a  erface between.*
bfc0: 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * the SQLite cor
bfd0: 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c  e and the underl
bfe0: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
bff0: 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73  ystem.  The "vfs
c000: 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65  ".** in the name
c010: 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73   of the object s
c020: 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75  tands for "virtu
c030: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e  al file system".
c040: 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46    See.** the [VF
c050: 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74  S | VFS document
c060: 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68  ation] for furth
c070: 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  er information..
c080: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
c090: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
c0a0: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
c0b0: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
c0c0: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
c0d0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
c0e0: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
c0f0: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
c100: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
c110: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
c120: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
c130: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
c140: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
c150: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
c160: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
c170: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
c180: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
c190: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
c1a0: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
c1b0: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
c1c0: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
c1d0: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
c1e0: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
c1f0: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
c200: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
c210: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
c220: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
c230: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
c240: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
c250: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
c260: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
c270: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
c280: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
c290: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
c2a0: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
c2b0: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
c2c0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
c2d0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
c2e0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
c2f0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
c300: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
c310: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
c320: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
c330: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
c340: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
c350: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
c360: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
c370: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
c380: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
c390: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
c3a0: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
c3b0: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
c3c0: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
c3d0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
c3e0: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
c3f0: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
c400: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
c410: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
c420: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
c430: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
c440: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
c450: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
c460: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
c470: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
c480: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
c490: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
c4a0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
c4b0: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
c4c0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
c4d0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
c4e0: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
c4f0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
c500: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
c510: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
c520: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
c530: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
c540: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
c550: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
c560: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
c570: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
c580: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
c590: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
c5a0: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
c5b0: 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c  .xOpen]].** ^SQL
c5c0: 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
c5d0: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
c5e0: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
c5f0: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65  Open.** is eithe
c600: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
c610: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69   or string obtai
c620: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c  ned.** from xFul
c630: 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68  lPathname() with
c640: 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66   an optional suf
c650: 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49  fix added..** ^I
c660: 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64  f a suffix is ad
c670: 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65  ded to the zFile
c680: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20  name parameter, 
c690: 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69  it will.** consi
c6a0: 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22  st of a single "
c6b0: 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c  -" character fol
c6c0: 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65  lowed by no more
c6d0: 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68   than.** 11 alph
c6e0: 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20  anumeric and/or 
c6f0: 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a  "-" characters..
c700: 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68  ** ^SQLite furth
c710: 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  er guarantees th
c720: 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  at.** the string
c730: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
c740: 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74  nd unchanged unt
c750: 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a  il xClose() is.*
c760: 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73  * called. Becaus
c770: 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75  e of the previou
c780: 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74  s sentence,.** t
c790: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
c7a0: 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f  ] can safely sto
c7b0: 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  re a pointer to 
c7c0: 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  the.** filename 
c7d0: 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72  if it needs to r
c7e0: 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65  emember the file
c7f0: 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65  name for some re
c800: 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ason..** If the 
c810: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
c820: 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20  ter to xOpen is 
c830: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
c840: 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73  hen xOpen.** mus
c850: 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e  t invent its own
c860: 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20   temporary name 
c870: 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e  for the file.  ^
c880: 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a  Whenever the .**
c890: 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   xFilename param
c8a0: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20  eter is NULL it 
c8b0: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65  will also be the
c8c0: 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a   case that the.*
c8d0: 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  * flags paramete
c8e0: 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b  r will include [
c8f0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
c900: 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a  TEONCLOSE]..**.*
c910: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
c920: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20  ment to xOpen() 
c930: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74  includes all bit
c940: 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20  s set in.** the 
c950: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
c960: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
c970: 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73  v2()].  Or if [s
c980: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
c990: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
c9a0: 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  en16()] is used,
c9b0: 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c   then flags incl
c9c0: 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a  udes at least.**
c9d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
c9e0: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
c9f0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
ca00: 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20   .** If xOpen() 
ca10: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
ca20: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
ca30: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
ca40: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
ca50: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
ca60: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
ca70: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
ca80: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
ca90: 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61   ^(SQLite will a
caa0: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
cab0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
cac0: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28  gs to the xOpen(
cad0: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e  ).** call, depen
cae0: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65  ding on the obje
caf0: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a  ct being opened:
cb00: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
cb10: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
cb20: 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_MAIN_DB].** <l
cb30: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
cb40: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _MAIN_JOURNAL].*
cb50: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
cb60: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a  OPEN_TEMP_DB].**
cb70: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
cb80: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
cb90: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
cba0: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
cbb0: 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  T_DB].** <li>  [
cbc0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
cbd0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
cbe0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
cbf0: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  STER_JOURNAL].**
cc00: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
cc10: 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  PEN_WAL].** </ul
cc20: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  >)^.**.** The fi
cc30: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
cc40: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
cc50: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
cc60: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65  ags to.** change
cc70: 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c   the way it deal
cc80: 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46  s with files.  F
cc90: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  or example, an a
cca0: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68  pplication.** th
ccb0: 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  at does not care
ccc0: 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63   about crash rec
ccd0: 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63  overy or rollbac
cce0: 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20  k might make.** 
ccf0: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f  the open of a jo
cd00: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d  urnal file a no-
cd10: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  op.  Writes to t
cd20: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  his journal woul
cd30: 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d  d.** also be no-
cd40: 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74  ops, and any att
cd50: 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65  empt to read the
cd60: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72   journal would r
cd70: 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
cd80: 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69  IOERR.  Or the i
cd90: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
cda0: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
cdb0: 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  at a database.**
cdc0: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f   file will be do
cdd0: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
cde0: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
cdf0: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
ce00: 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  ndom.** order an
ce10: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
ce20: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
ce30: 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51  dingly..**.** SQ
ce40: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
ce50: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
ce60: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
ce70: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
ce80: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
ce90: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
cea0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
ceb0: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
cec0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
ced0: 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  E].** </ul>.**.*
cee0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  * The [SQLITE_OP
cef0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
cf00: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
cf10: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a   file should be.
cf20: 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ** deleted when 
cf30: 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e  it is closed.  ^
cf40: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
cf50: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
cf60: 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66  ** will be set f
cf70: 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65  or TEMP database
cf80: 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72  s and their jour
cf90: 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a  nals, transient.
cfa0: 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e  ** databases, an
cfb0: 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a  d subjournals..*
cfc0: 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
cfd0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
cfe0: 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73  ] flag is always
cff0: 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63   used in conjunc
d000: 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  tion.** with the
d010: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
d020: 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63  EATE] flag, whic
d030: 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63  h are both direc
d040: 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73  tly.** analogous
d050: 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61   to the O_EXCL a
d060: 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73  nd O_CREAT flags
d070: 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70   of the POSIX op
d080: 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68  en().** API.  Th
d090: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58  e SQLITE_OPEN_EX
d0a0: 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68  CLUSIVE flag, wh
d0b0: 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74  en paired with t
d0c0: 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50  he .** SQLITE_OP
d0d0: 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73  EN_CREATE, is us
d0e0: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
d0f0: 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  hat file should 
d100: 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65  always.** be cre
d110: 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69  ated, and that i
d120: 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66  t is an error if
d130: 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73   it already exis
d140: 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e  ts..** It is <i>
d150: 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20  not</i> used to 
d160: 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c  indicate the fil
d170: 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e  e should be open
d180: 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75  ed .** for exclu
d190: 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a  sive access..**.
d1a0: 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f  ** ^At least szO
d1b0: 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d  sFile bytes of m
d1c0: 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61  emory are alloca
d1d0: 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  ted by SQLite.**
d1e0: 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73   to hold the  [s
d1f0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72  qlite3_file] str
d200: 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73  ucture passed as
d210: 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   the third.** ar
d220: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e  gument to xOpen.
d230: 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68    The xOpen meth
d240: 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  od does not have
d250: 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20   to.** allocate 
d260: 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69  the structure; i
d270: 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69  t should just fi
d280: 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20  ll it in.  Note 
d290: 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65  that.** the xOpe
d2a0: 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65  n method must se
d2b0: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
d2c0: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65  le.pMethods to e
d2d0: 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64  ither.** a valid
d2e0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
d2f0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20  hods] object or 
d300: 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20  to NULL.  xOpen 
d310: 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20  must do.** this 
d320: 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e  even if the open
d330: 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20   fails.  SQLite 
d340: 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65  expects that the
d350: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
d360: 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e  ethods.** elemen
d370: 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  t will be valid 
d380: 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75  after xOpen retu
d390: 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f  rns regardless o
d3a0: 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a  f the success.**
d3b0: 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74   or failure of t
d3c0: 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a  he xOpen call..*
d3d0: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
d3e0: 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20  fs.xAccess]].** 
d3f0: 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d  ^The flags argum
d400: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
d410: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
d420: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
d430: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
d440: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
d450: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
d460: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
d470: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
d480: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
d490: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
d4a0: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
d4b0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
d4c0: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
d4d0: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
d4e0: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
d4f0: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
d500: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
d510: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
d520: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
d530: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
d540: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
d550: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
d560: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
d570: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78  athname.  The ex
d580: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
d590: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
d5a0: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
d5b0: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
d5c0: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
d5d0: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
d5e0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  uffer.** is not 
d5f0: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
d600: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
d610: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
d620: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69  ed. Since this i
d630: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20  s.** handled as 
d640: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
d650: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70   SQLite, vfs imp
d660: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
d670: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20  uld endeavor.** 
d680: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
d690: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74  by setting mxPat
d6a0: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
d6b0: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
d6c0: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  lue..**.** The x
d6d0: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53  Randomness(), xS
d6e0: 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74  leep(), xCurrent
d6f0: 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72  Time(), and xCur
d700: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a  rentTimeInt64().
d710: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ** interfaces ar
d720: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
d730: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
d740: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
d750: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
d760: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
d770: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
d780: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
d790: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
d7a0: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
d7b0: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
d7c0: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
d7d0: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
d7e0: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
d7f0: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
d800: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
d810: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
d820: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
d830: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
d840: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
d850: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
d860: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
d870: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
d880: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
d890: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
d8a0: 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75  given.  ^The xCu
d8b0: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
d8c0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
d8d0: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
d8e0: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
d8f0: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  t date and time 
d900: 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67  as.** a floating
d910: 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a   point value..**
d920: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
d930: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
d940: 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20   returns, as an 
d950: 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c  integer, the Jul
d960: 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65  ian.** Day Numbe
d970: 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20  r multiplied by 
d980: 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75  86400000 (the nu
d990: 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
d9a0: 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34  onds in .** a 24
d9b0: 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a  -hour day).  .**
d9c0: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
d9d0: 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69  e the xCurrentTi
d9e0: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
d9f0: 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72   to get the curr
da00: 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20  ent.** date and 
da10: 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74  time if that met
da20: 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65  hod is available
da30: 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73   (if iVersion is
da40: 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65   2 or .** greate
da50: 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69  r and the functi
da60: 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
da70: 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c  t NULL) and will
da80: 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f   fall back.** to
da90: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20   xCurrentTime() 
daa0: 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  if xCurrentTimeI
dab0: 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69  nt64() is unavai
dac0: 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lable..**.** ^Th
dad0: 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  e xSetSystemCall
dae0: 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61  (), xGetSystemCa
daf0: 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53  ll(), and xNestS
db00: 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65  ystemCall() inte
db10: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
db20: 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51  t used by the SQ
db30: 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73  Lite core.  Thes
db40: 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72  e optional inter
db50: 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
db60: 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46  ed.** by some VF
db70: 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74  Ses to facilitat
db80: 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65  e testing of the
db90: 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76   VFS code. By ov
dba0: 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73  erriding .** sys
dbb0: 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66  tem calls with f
dbc0: 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69  unctions under i
dbd0: 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65  ts control, a te
dbe0: 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a  st program can.*
dbf0: 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74  * simulate fault
dc00: 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64  s and error cond
dc10: 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c  itions that woul
dc20: 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64  d otherwise be d
dc30: 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69  ifficult.** or i
dc40: 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64  mpossible to ind
dc50: 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66  uce.  The set of
dc60: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68   system calls th
dc70: 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  at can be overri
dc80: 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66  dden.** varies f
dc90: 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61  rom one VFS to a
dca0: 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d  nother, and from
dcb0: 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20   one version of 
dcc0: 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20  the same VFS to 
dcd0: 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70  the.** next.  Ap
dce0: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
dcf0: 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66  use these interf
dd00: 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65  aces must be pre
dd10: 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a  pared for any.**
dd20: 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65   or all of these
dd30: 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62   interfaces to b
dd40: 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68  e NULL or for th
dd50: 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20  eir behavior to 
dd60: 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f  change.** from o
dd70: 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68  ne release to th
dd80: 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  e next.  Applica
dd90: 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61  tions must not a
dda0: 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73  ttempt to access
ddb0: 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65  .** any of these
ddc0: 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20   methods if the 
ddd0: 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20  iVersion of the 
dde0: 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e  VFS is less than
ddf0: 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73   3..*/.typedef s
de00: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
de10: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74  s sqlite3_vfs;.t
de20: 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
de30: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
de40: 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74  r)(void);.struct
de50: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
de60: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
de70: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
de80: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
de90: 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79  umber (currently
dea0: 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f   3) */.  int szO
deb0: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
dec0: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
ded0: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
dee0: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
def0: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
df00: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
df10: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
df20: 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  th */.  sqlite3_
df30: 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20  vfs *pNext;     
df40: 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65   /* Next registe
df50: 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e  red VFS */.  con
df60: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20  st char *zName; 
df70: 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
df80: 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69   this virtual fi
df90: 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76  le system */.  v
dfa0: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
dfb0: 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74          /* Point
dfc0: 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
dfd0: 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20  n-specific data 
dfe0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  */.  int (*xOpen
dff0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e000: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e010: 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e, sqlite3_file*
e020: 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
e030: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
e040: 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69  *pOutFlags);.  i
e050: 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71  nt (*xDelete)(sq
e060: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e070: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
e080: 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69  nt syncDir);.  i
e090: 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71  nt (*xAccess)(sq
e0a0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e0b0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
e0c0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
e0d0: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
e0e0: 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28  *xFullPathname)(
e0f0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
e100: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
e110: 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20   int nOut, char 
e120: 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
e130: 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74  (*xDlOpen)(sqlit
e140: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
e150: 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b  har *zFilename);
e160: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72  .  void (*xDlErr
e170: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
e180: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
e190: 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76  r *zErrMsg);.  v
e1a0: 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28  oid (*(*xDlSym)(
e1b0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
e1c0: 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
e1d0: 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b  zSymbol))(void);
e1e0: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
e1f0: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
e200: 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
e210: 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
e220: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
e230: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
e240: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
e250: 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
e260: 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
e270: 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
e280: 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
e290: 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
e2a0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74  *);.  int (*xGet
e2b0: 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74  LastError)(sqlit
e2c0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68  e3_vfs*, int, ch
e2d0: 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  ar *);.  /*.  **
e2e0: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
e2f0: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
e300: 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74  n 1 of the sqlit
e310: 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a  e_vfs object.  *
e320: 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  * definition.  T
e330: 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77  hose that follow
e340: 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65   are added in ve
e350: 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72  rsion 2 or later
e360: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43  .  */.  int (*xC
e370: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29  urrentTimeInt64)
e380: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73  (sqlite3_vfs*, s
e390: 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a  qlite3_int64*);.
e3a0: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
e3b0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
e3c0: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e  in versions 1 an
e3d0: 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74  d 2 of the sqlit
e3e0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
e3f0: 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61  ** Those below a
e400: 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  re for version 3
e410: 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20   and greater..  
e420: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53  */.  int (*xSetS
e430: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
e440: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
e450: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
e460: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
e470: 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63  ;.  sqlite3_sysc
e480: 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79  all_ptr (*xGetSy
e490: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
e4a0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e4b0: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f  ar *zName);.  co
e4c0: 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78  nst char *(*xNex
e4d0: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
e4e0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
e4f0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
e500: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
e510: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
e520: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72  n versions 1 thr
e530: 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71  ough 3 of the sq
e540: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
e550: 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73  .  ** New fields
e560: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
e570: 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69   in figure versi
e580: 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69  ons.  The iVersi
e590: 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69  on.  ** value wi
e5a0: 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65  ll increment whe
e5b0: 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65  never this happe
e5c0: 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ns. .  */.};../*
e5d0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
e5e0: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
e5f0: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ess VFS method.*
e600: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
e610: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
e620: 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
e630: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
e640: 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
e650: 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
e660: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
e670: 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72  ect.  They deter
e680: 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e  mine.** what kin
e690: 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73  d of permissions
e6a0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
e6b0: 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66  hod is looking f
e6c0: 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  or..** With SQLI
e6d0: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
e6e0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
e6f0: 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63  thod.** simply c
e700: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
e710: 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a  e file exists..*
e720: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
e730: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20  CESS_READWRITE, 
e740: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
e750: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
e760: 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64  ther the named d
e770: 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68  irectory is both
e780: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
e790: 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74  itable.** (in ot
e7a0: 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69  her words, if fi
e7b0: 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64  les can be added
e7c0: 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72  , removed, and r
e7d0: 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a  enamed within.**
e7e0: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e   the directory).
e7f0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41  .** The SQLITE_A
e800: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
e810: 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72  constant is curr
e820: 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20  ently used only 
e830: 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f  by the.** [temp_
e840: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
e850: 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20  pragma], though 
e860: 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67  this could chang
e870: 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a  e in a future.**
e880: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
e890: 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  te..** With SQLI
e8a0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20  TE_ACCESS_READ, 
e8b0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
e8c0: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
e8d0: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73  ther the file is
e8e0: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
e8f0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
e900: 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a  AD constant is.*
e910: 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73  * currently unus
e920: 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69  ed, though it mi
e930: 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61  ght be used in a
e940: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
e950: 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f  of.** SQLite..*/
e960: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e970: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
e980: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
e990: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
e9a0: 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62  TE 1   /* Used b
e9b0: 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74  y PRAGMA temp_st
e9c0: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f  ore_directory */
e9d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e9e0: 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
e9f0: 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a   2   /* Unused *
ea00: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
ea10: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
ea20: 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65   xShmLock VFS me
ea30: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
ea40: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
ea50: 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61  ts define the va
ea60: 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70  rious locking op
ea70: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f  erations.** allo
ea80: 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c  wed by the xShmL
ea90: 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73  ock method of [s
eaa0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
eab0: 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c  s].  The.** foll
eac0: 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e  owing are the on
ead0: 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61  ly legal combina
eae0: 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74  tions of flags t
eaf0: 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63  o the.** xShmLoc
eb00: 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  k method:.**.** 
eb10: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  <ul>.** <li>  SQ
eb20: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
eb30: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
eb40: 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
eb50: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
eb60: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
eb70: 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  E.** <li>  SQLIT
eb80: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
eb90: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
eba0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
ebb0: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
ebc0: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
ebd0: 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VE.** </ul>.**.*
ebe0: 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67  * When unlocking
ebf0: 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45  , the same SHARE
ec00: 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66  D or EXCLUSIVE f
ec10: 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70  lag must be supp
ec20: 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67  lied as.** was g
ec30: 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72  iven on the corr
ec40: 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20  esponding lock. 
ec50: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d   .**.** The xShm
ec60: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20  Lock method can 
ec70: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
ec80: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
ec90: 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74  SHARED or.** bet
eca0: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
ecb0: 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74  d EXCLUSIVE.  It
ecc0: 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69   cannot transiti
ecd0: 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45  on between SHARE
ece0: 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49  D.** and EXCLUSI
ecf0: 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  VE..*/.#define S
ed00: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
ed10: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
ed20: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
ed30: 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
ed40: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48  ne SQLITE_SHM_SH
ed50: 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65  ARED       4.#de
ed60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
ed70: 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a  EXCLUSIVE    8..
ed80: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
ed90: 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b  Maximum xShmLock
eda0: 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65   index.**.** The
edb0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
edc0: 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   on [sqlite3_io_
edd0: 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65  methods] may use
ede0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
edf0: 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70  en 0 and this up
ee00: 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73  per bound as its
ee10: 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65   "offset" argume
ee20: 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  nt..** The SQLit
ee30: 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65  e core will neve
ee40: 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71  r attempt to acq
ee50: 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20  uire or release 
ee60: 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64  a.** lock outsid
ee70: 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a  e of this range.
ee80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ee90: 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20  E_SHM_NLOCK     
eea0: 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     8.../*.** CAP
eeb0: 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a  I3REF: Initializ
eec0: 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  e The SQLite Lib
eed0: 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rary.**.** ^The 
eee0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
eef0: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69  ze() routine ini
ef00: 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20  tializes the.** 
ef10: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
ef20: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68   ^The sqlite3_sh
ef30: 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65  utdown() routine
ef40: 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  .** deallocates 
ef50: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68  any resources th
ef60: 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65  at were allocate
ef70: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  d by sqlite3_ini
ef80: 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68  tialize()..** Th
ef90: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
efa0: 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64   designed to aid
efb0: 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74   in process init
efc0: 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a  ialization and.*
efd0: 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d  * shutdown on em
efe0: 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20  bedded systems. 
eff0: 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70   Workstation app
f000: 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a  lications using.
f010: 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c  ** SQLite normal
f020: 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ly do not need t
f030: 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  o invoke either 
f040: 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
f050: 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  s..**.** A call 
f060: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
f070: 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65  alize() is an "e
f080: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
f090: 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66  f it is.** the f
f0a0: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
f0b0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f0c0: 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67  s invoked during
f0d0: 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66   the lifetime of
f0e0: 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c  .** the process,
f0f0: 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65   or if it is the
f100: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
f110: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f120: 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66   is invoked.** f
f130: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20  ollowing a call 
f140: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
f150: 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61  own().  ^(Only a
f160: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
f170: 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69  .** of sqlite3_i
f180: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73  nitialize() does
f190: 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74   any initializat
f1a0: 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ion.  All other 
f1b0: 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72  calls.** are har
f1c0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
f1d0: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
f1e0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f1f0: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
f200: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
f210: 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
f220: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
f230: 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65  shutdown() since
f240: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
f250: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20  3_initialize(). 
f260: 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66   ^(Only.** an ef
f270: 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20  fective call to 
f280: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f290: 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e  () does any dein
f2a0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  itialization..**
f2b0: 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64   All other valid
f2c0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
f2d0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65  3_shutdown() are
f2e0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
f2f0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  .)^.**.** The sq
f300: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f310: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
f320: 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20  threadsafe, but 
f330: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f340: 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54  ().** is not.  T
f350: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
f360: 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  own() interface 
f370: 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c  must only be cal
f380: 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69  led from a.** si
f390: 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c  ngle thread.  Al
f3a0: 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  l open [database
f3b0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75   connections] mu
f3c0: 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64  st be closed and
f3d0: 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51   all.** other SQ
f3e0: 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d  Lite resources m
f3f0: 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  ust be deallocat
f400: 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f  ed prior to invo
f410: 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  king.** sqlite3_
f420: 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a  shutdown()..**.*
f430: 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68  * Among other th
f440: 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69  ings, ^sqlite3_i
f450: 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c  nitialize() will
f460: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
f470: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53  e3_os_init().  S
f480: 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74  imilarly, ^sqlit
f490: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
f4a0: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c   will invoke sql
f4b0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a  ite3_os_end()..*
f4c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
f4d0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
f4e0: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
f4f0: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
f500: 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f  ccess..** ^If fo
f510: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73  r some reason, s
f520: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f530: 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  e() is unable to
f540: 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74   initialize.** t
f550: 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68  he library (perh
f560: 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65  aps it is unable
f570: 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e   to allocate a n
f580: 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73  eeded resource s
f590: 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65  uch.** as a mute
f5a0: 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e  x) it returns an
f5b0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74   [error code] ot
f5c0: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
f5d0: 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _OK]..**.** ^The
f5e0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f5f0: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
f600: 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
f610: 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
f620: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
f630: 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
f640: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
f650: 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
f660: 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
f670: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f680: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
f690: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
f6a0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
f6b0: 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
f6c0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
f6d0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
f6e0: 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
f6f0: 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
f700: 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
f710: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
f720: 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
f730: 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
f740: 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
f750: 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51   ^However, if SQ
f760: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
f770: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
f780: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
f790: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
f7a0: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68   option, then th
f7b0: 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c  e automatic call
f7c0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  s to sqlite3_ini
f7d0: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65  tialize().** are
f7e0: 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65   omitted and the
f7f0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
f800: 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69  t call sqlite3_i
f810: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
f820: 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ctly.** prior to
f830: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
f840: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
f850: 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20  e.  For maximum 
f860: 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20  portability,.** 
f870: 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
f880: 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
f890: 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b  ons always invok
f8a0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
f8b0: 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74  lize().** direct
f8c0: 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ly prior to usin
f8d0: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
f8e0: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
f8f0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a  uture releases.*
f900: 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  * of SQLite may 
f910: 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49  require this.  I
f920: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
f930: 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69  he behavior exhi
f940: 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51  bited.** when SQ
f950: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
f960: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d   with [SQLITE_OM
f970: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67  IT_AUTOINIT] mig
f980: 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a  ht become the.**
f990: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
f9a0: 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  r in some future
f9b0: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
f9c0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te..**.** The sq
f9d0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
f9e0: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65  routine does ope
f9f0: 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
fa00: 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61  ecific.** initia
fa10: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  lization of the 
fa20: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
fa30: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
fa40: 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  end().** routine
fa50: 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
fa60: 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  ct of sqlite3_os
fa70: 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61  _init().  Typica
fa80: 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f  l tasks.** perfo
fa90: 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f  rmed by these ro
faa0: 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61  utines include a
fab0: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61  llocation or dea
fac0: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
fad0: 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73  static resources
fae0: 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  , initialization
faf0: 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61   of global varia
fb00: 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67  bles,.** setting
fb10: 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73   up a default [s
fb20: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75  qlite3_vfs] modu
fb30: 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75  le, or setting u
fb40: 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63  p.** a default c
fb50: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69  onfiguration usi
fb60: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ng [sqlite3_conf
fb70: 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ig()]..**.** The
fb80: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
fb90: 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  uld never invoke
fba0: 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
fbb0: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20  os_init().** or 
fbc0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
fbd0: 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20   directly.  The 
fbe0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
fbf0: 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a  ld only invoke.*
fc00: 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
fc10: 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lize() and sqlit
fc20: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
fc30: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
fc40: 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  nit().** interfa
fc50: 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74  ce is called aut
fc60: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
fc70: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fc80: 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  () and.** sqlite
fc90: 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
fca0: 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
fcb0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
fcc0: 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
fcd0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
fce0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
fcf0: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
fd00: 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
fd10: 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
fd20: 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
fd30: 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69  led for Unix, Wi
fd40: 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a  ndows, or OS/2..
fd50: 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20  ** When [custom 
fd60: 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66  builds | built f
fd70: 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72  or other platfor
fd80: 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68  ms].** (using th
fd90: 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48  e [SQLITE_OS_OTH
fda0: 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ER=1] compile-ti
fdb0: 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
fdc0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
fdd0: 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
fde0: 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
fdf0: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
fe00: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
fe10: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
fe20: 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
fe30: 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
fe40: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
fe50: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
fe60: 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
fe70: 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
fe80: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
fe90: 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
fea0: 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72   some other [err
feb0: 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a  or code] upon.**
fec0: 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74   failure..*/.int
fed0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fee0: 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ize(void);.int s
fef0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ff00: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
ff10: 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
ff20: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
ff30: 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
ff40: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
ff50: 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
ff60: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
ff70: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
ff80: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
ff90: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
ffa0: 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
ffb0: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
ffc0: 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
ffd0: 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
ffe0: 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
fff0: 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
10000 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
10010 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
10020 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
10030 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
10040 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
10050 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
10060 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
10070 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
10080 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
10090 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
100a0 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
100b0 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
100c0 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  eds..**.** The s
100d0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
100e0 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
100f0 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
10100 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
10110 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
10120 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
10130 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
10140 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
10150 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
10160 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
10170 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  g() is running. 
10180 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71   Furthermore, sq
10190 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a  lite3_config().*
101a0 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
101b0 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
101c0 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
101d0 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
101e0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
101f0 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
10200 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
10210 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
10220 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
10230 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c  config() is call
10240 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
10250 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
10260 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73  and before.** [s
10270 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10280 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20  )] then it will 
10290 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49  return SQLITE_MI
102a0 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68  SUSE..** Note, h
102b0 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71  owever, that ^sq
102c0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
102d0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
102e0 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
102f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
10300 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
10310 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
10320 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
10330 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
10340 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
10350 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
10360 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66  integer.** [conf
10370 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10380 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
10390 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
103a0 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
103b0 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
103c0 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
103d0 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
103e0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
103f0 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
10400 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
10410 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10420 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ..**.** ^When a 
10430 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10440 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
10450 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
10460 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
10470 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70  ]..** ^If the op
10480 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
10490 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
104a0 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
104b0 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68  ption.** then th
104c0 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
104d0 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  ns a non-zero [e
104e0 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69  rror code]..*/.i
104f0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  nt sqlite3_confi
10500 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  g(int, ...);../*
10510 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
10520 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65  nfigure database
10530 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a   connections.**.
10540 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
10550 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
10560 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
10570 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
10580 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
10590 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
105a0 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
105b0 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
105c0 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
105d0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
105e0 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
105f0 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
10600 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
10610 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
10620 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
10630 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10640 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  )..**.** The sec
10650 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
10660 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
10670 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
10680 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42  he.** [SQLITE_DB
10690 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
106a0 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
106b0 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65   verb] - an inte
106c0 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61  ger code .** tha
106d0 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
106e0 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
106f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10700 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
10710 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62  nfigured..** Sub
10720 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
10730 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  s vary depending
10740 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72   on the configur
10750 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a  ation verb..**.*
10760 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
10770 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
10780 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
10790 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
107a0 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
107b0 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
107c0 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  sful..*/.int sql
107d0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
107e0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
107f0 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
10800 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
10810 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
10820 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
10830 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
10840 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
10850 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
10860 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
10870 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
10880 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
10890 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
108a0 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
108b0 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
108c0 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
108d0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
108e0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
108f0 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
10900 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
10910 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
10920 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
10930 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
10940 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
10950 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
10960 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
10970 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
10980 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
10990 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
109a0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
109b0 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
109c0 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
109d0 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
109e0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
109f0 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
10a00 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
10a10 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
10a20 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
10a30 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
10a40 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
10a50 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
10a60 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
10a70 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
10a80 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
10a90 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
10aa0 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
10ab0 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
10ac0 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
10ad0 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
10ae0 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
10af0 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
10b00 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
10b10 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
10b20 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
10b30 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
10b40 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
10b50 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
10b60 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
10b70 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
10b80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10b90 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
10ba0 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
10bb0 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
10bc0 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
10bd0 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
10be0 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
10bf0 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
10c00 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
10c10 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
10c20 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
10c30 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
10c40 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
10c50 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
10c60 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
10c70 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
10c80 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
10c90 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52   The xMalloc, xR
10ca0 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65  ealloc, and xFre
10cb0 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  e methods must w
10cc0 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
10cd0 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
10ce0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
10cf0 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
10d00 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
10d10 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  rary..** ^SQLite
10d20 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
10d30 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
10d40 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
10d50 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
10d60 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
10d70 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
10d80 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a  o xRoundup..**.*
10d90 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
10da0 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
10db0 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
10dc0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
10dd0 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
10de0 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
10df0 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
10e00 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
10e10 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
10e20 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
10e30 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
10e40 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
10e50 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
10e60 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
10e70 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
10e80 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
10e90 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
10ea0 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
10eb0 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
10ec0 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
10ed0 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
10ee0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
10ef0 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
10f00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10f10 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
10f20 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
10f30 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
10f40 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
10f50 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
10f60 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
10f70 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45  power of 2..** E
10f80 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
10f90 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63  cation request c
10fa0 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68  oming in through
10fb0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
10fc0 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
10fd0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69  e3_realloc()] fi
10fe0 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64  rst calls xRound
10ff0 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70  up.  If xRoundup
11000 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20   returns 0, .** 
11010 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20  that causes the 
11020 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65  corresponding me
11030 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11040 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54  to fail..**.** T
11050 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
11060 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
11070 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11080 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  .  For example,.
11090 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
110a0 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
110b0 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
110c0 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
110d0 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
110e0 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
110f0 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
11100 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
11110 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
11120 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
11130 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
11140 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
11150 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
11160 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
11170 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
11180 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
11190 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
111a0 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
111b0 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
111c0 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
111d0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
111e0 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
111f0 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
11200 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
11210 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
11220 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
11230 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
11240 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
11250 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
11260 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
11270 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11280 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
11290 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
112a0 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
112b0 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
112c0 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
112d0 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
112e0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
112f0 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
11300 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
11310 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
11320 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
11330 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
11340 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
11350 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
11360 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
11370 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
11380 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
11390 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
113a0 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
113b0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
113c0 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
113d0 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
113e0 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
113f0 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
11400 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
11410 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
11420 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
11430 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
11440 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
11450 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
11460 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
11470 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
11480 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
11490 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
114a0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
114b0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
114c0 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
114d0 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
114e0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
114f0 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
11500 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
11510 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
11520 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
11530 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
11540 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
11550 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
11560 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
11570 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
11580 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
11590 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
115a0 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
115b0 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
115c0 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
115d0 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
115e0 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
115f0 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
11600 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
11610 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
11620 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
11630 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
11640 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
11650 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
11660 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
11670 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
11680 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
11690 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
116a0 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
116b0 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
116c0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
116d0 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
116e0 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
116f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
11700 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
11710 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
11720 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
11730 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
11740 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
11750 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
11760 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11770 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
11780 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
11790 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
117a0 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
117b0 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
117c0 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
117d0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
117e0 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
117f0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
11800 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
11810 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
11820 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
11830 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
11840 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
11850 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
11860 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11870 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
11880 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
11890 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
118a0 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
118b0 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
118c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
118d0 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
118e0 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
118f0 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
11900 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
11910 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
11920 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
11930 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
11940 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
11950 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
11960 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
11970 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
11980 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
11990 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
119a0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
119b0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
119c0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
119d0 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
119e0 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
119f0 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
11a00 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
11a10 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
11a20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
11a30 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
11a40 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
11a50 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
11a60 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
11a70 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
11a80 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
11a90 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
11aa0 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
11ab0 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
11ac0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
11ad0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
11ae0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
11af0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
11b00 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
11b10 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
11b20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
11b30 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
11b40 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
11b50 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
11b60 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
11b70 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
11b80 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
11b90 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
11ba0 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
11bb0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
11bc0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
11bd0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
11be0 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
11bf0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11c00 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
11c10 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11c20 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
11c30 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11c40 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
11c50 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
11c60 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
11c70 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
11c80 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
11c90 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
11ca0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
11cb0 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
11cc0 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
11cd0 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
11ce0 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
11cf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
11d00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
11d10 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
11d20 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
11d30 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
11d40 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
11d50 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
11d60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
11d70 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
11d80 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
11d90 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
11da0 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
11db0 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
11dc0 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
11dd0 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
11de0 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
11df0 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
11e00 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
11e10 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
11e20 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
11e30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11e40 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
11e50 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
11e60 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
11e70 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
11e80 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
11e90 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
11ea0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
11eb0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
11ec0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
11ed0 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
11ee0 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
11ef0 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
11f00 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
11f10 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
11f20 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
11f30 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
11f40 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
11f50 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
11f60 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
11f70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
11f80 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
11f90 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
11fa0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11fb0 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
11fc0 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
11fd0 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
11fe0 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
11ff0 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
12000 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
12010 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
12020 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
12030 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
12040 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
12050 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
12060 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
12070 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
12080 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12090 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
120a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
120b0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
120c0 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
120d0 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
120e0 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
120f0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
12100 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12110 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
12120 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
12130 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
12140 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
12150 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12160 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
12170 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
12180 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
12190 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
121a0 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
121b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
121c0 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
121d0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
121e0 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
121f0 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
12200 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
12210 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
12220 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
12230 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
12240 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
12250 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
12260 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
12270 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
12280 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
12290 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
122a0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
122b0 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
122c0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
122d0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
122e0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
122f0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
12300 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
12310 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
12320 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
12330 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12340 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
12350 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
12360 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
12370 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
12380 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
12390 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
123a0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
123b0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
123c0 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
123d0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
123e0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
123f0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
12400 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  e..** The argume
12410 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
12420 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
12430 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
12440 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
12450 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
12460 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
12470 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12480 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
12490 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
124a0 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
124b0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
124c0 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
124d0 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
124e0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
124f0 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
12500 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
12510 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
12520 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
12530 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12540 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d  NFIG_GETMALLOC]]
12550 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12560 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
12570 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
12580 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12590 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74  TMALLOC option t
125a0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
125b0 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
125c0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
125d0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
125e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
125f0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
12600 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  re..** The [sqli
12610 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
12620 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
12630 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
12640 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
12650 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
12660 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
12670 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
12680 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
12690 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
126a0 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
126b0 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
126c0 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
126d0 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
126e0 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
126f0 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
12700 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
12710 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
12720 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
12730 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12740 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
12750 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
12760 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
12770 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
12780 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
12790 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  S option takes s
127a0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
127b0 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69  f type int,.** i
127c0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
127d0 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
127e0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
127f0 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
12800 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  n of.** memory a
12810 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
12820 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
12830 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
12840 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a  tatistics are.**
12850 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66   disabled, the f
12860 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20  ollowing SQLite 
12870 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d  interfaces becom
12880 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61  e non-operationa
12890 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20  l:.**   <ul>.** 
128a0 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
128b0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a  memory_used()].*
128c0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
128d0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
128e0 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  er()].**   <li> 
128f0 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
12900 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a  ap_limit64()].**
12910 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
12920 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20  _status64()].** 
12930 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
12940 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12950 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
12960 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
12970 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
12980 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
12990 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
129a0 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
129b0 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
129c0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
129d0 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
129e0 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
129f0 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
12a00 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12a10 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d  CONFIG_SCRATCH]]
12a20 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12a30 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
12a40 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
12a50 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
12a60 43 48 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  CH option specif
12a70 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
12a80 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  ory buffer.** th
12a90 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
12aa0 65 20 66 6f 72 20 73 63 72 61 74 63 68 20 6d 65  e for scratch me
12ab0 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72 65 20 61  mory.  ^(There a
12ac0 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
12ad0 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f  ts.** to SQLITE_
12ae0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3a 20  CONFIG_SCRATCH: 
12af0 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
12b00 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
12b10 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
12b20 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
12b30 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
12b40 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77   will be.** draw
12b50 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  n, the size of e
12b60 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  ach scratch allo
12b70 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20  cation (sz),.** 
12b80 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
12b90 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63  number of scratc
12ba0 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e  h allocations (N
12bb0 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73  ).)^.** The firs
12bc0 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
12bd0 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
12be0 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  an 8-byte aligne
12bf0 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61  d buffer.** of a
12c00 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
12c10 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
12c20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f   ^SQLite will no
12c30 74 20 75 73 65 20 6d 6f 72 65 20 74 68 61 6e 20  t use more than 
12c40 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66  one scratch buff
12c50 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 0a  ers per thread..
12c60 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
12c70 6e 65 76 65 72 20 72 65 71 75 65 73 74 20 61 20  never request a 
12c80 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74  scratch buffer t
12c90 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e  hat is more than
12ca0 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20   6.** times the 
12cb0 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
12cc0 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  ze..** ^If SQLit
12cd0 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64  e needs needs ad
12ce0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61  ditional.** scra
12cf0 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  tch memory beyon
12d00 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
12d10 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69  ed by this confi
12d20 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c  guration option,
12d30 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   then .** [sqlit
12d40 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c  e3_malloc()] wil
12d50 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  l be used to obt
12d60 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e  ain the memory n
12d70 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68  eeded.<p>.** ^Wh
12d80 65 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  en the applicati
12d90 6f 6e 20 70 72 6f 76 69 64 65 73 20 61 6e 79 20  on provides any 
12da0 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72 61 74 63  amount of scratc
12db0 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a  h memory using.*
12dc0 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
12dd0 53 43 52 41 54 43 48 2c 20 53 51 4c 69 74 65 20  SCRATCH, SQLite 
12de0 61 76 6f 69 64 73 20 75 6e 6e 65 63 65 73 73 61  avoids unnecessa
12df0 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c  ry large.** [sql
12e00 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70  ite3_malloc|heap
12e10 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a   allocations]..*
12e20 2a 20 54 68 69 73 20 63 61 6e 20 68 65 6c 70 20  * This can help 
12e30 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72  [Robson proof|pr
12e40 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  event memory all
12e50 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 73  ocation failures
12e60 5d 20 64 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a  ] due to heap.**
12e70 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69   fragmentation i
12e80 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62  n low-memory emb
12e90 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a  edded systems..*
12ea0 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
12eb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
12ec0 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51  GECACHE]] <dt>SQ
12ed0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
12ee0 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
12ef0 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
12f00 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
12f10 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
12f20 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
12f30 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
12f40 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
12f50 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
12f60 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20  page cache with 
12f70 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65  the default page
12f80 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
12f90 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54  entation.  .** T
12fa0 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
12fb0 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  n should not be 
12fc0 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69  used if an appli
12fd0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61  cation-define pa
12fe0 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
12ff0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f  ementation is lo
13000 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  aded using the [
13010 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
13020 41 43 48 45 32 5d 0a 2a 2a 20 63 6f 6e 66 69 67  ACHE2].** config
13030 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 0a  uration option..
13040 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68  ** ^There are th
13050 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
13060 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
13070 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69 6e  AGECACHE: A poin
13080 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65  ter to.** 8-byte
13090 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f   aligned.** memo
130a0 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ry, the size of 
130b0 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72  each page buffer
130c0 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
130d0 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28  umber of pages (
130e0 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
130f0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
13100 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
13110 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73   largest databas
13120 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77  e page.** (a pow
13130 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
13140 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33 36 29  n 512 and 65536)
13150 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61   plus some extra
13160 20 62 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a   bytes for each.
13170 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20  ** page header. 
13180 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
13190 65 78 74 72 61 20 62 79 74 65 73 20 6e 65 65 64  extra bytes need
131a0 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 68  ed by the page h
131b0 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20  eader.** can be 
131c0 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
131d0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
131e0 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
131f0 5d 20 6f 70 74 69 6f 6e 20 0a 2a 2a 20 74 6f 20  ] option .** to 
13200 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13210 29 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61  )]..** ^It is ha
13220 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72  rmless, apart fr
13230 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65  om the wasted me
13240 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65  mory,.** for the
13250 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f   sz parameter to
13260 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
13270 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65 20  necessary.  The 
13280 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
13290 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 65 72  t should pointer
132a0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c   to an 8-byte al
132b0 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d  igned block of m
132c0 65 6d 6f 72 79 20 74 68 61 74 0a 2a 2a 20 69 73  emory that.** is
132d0 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
132e0 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  ytes of memory, 
132f0 6f 74 68 65 72 77 69 73 65 20 73 75 62 73 65 71  otherwise subseq
13300 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73  uent behavior is
13310 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
13320 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
13330 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
13340 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69  ovided by the fi
13350 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
13360 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d  satisfy its.** m
13370 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20  emory needs for 
13380 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65  the first N page
13390 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74  s that it adds t
133a0 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64  o cache.  ^If ad
133b0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
133c0 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
133d0 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
133e0 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
133f0 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20  by this option, 
13400 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67  then.** SQLite g
13410 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
13420 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68  malloc()] for th
13430 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f  e additional sto
13440 72 61 67 65 20 73 70 61 63 65 2e 3c 2f 64 64 3e  rage space.</dd>
13450 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13460 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64  CONFIG_HEAP]] <d
13470 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13480 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  HEAP</dt>.** <dd
13490 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
134a0 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e  NFIG_HEAP option
134b0 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
134c0 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
134d0 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74  r .** that SQLit
134e0 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61  e will use for a
134f0 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
13500 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  c memory allocat
13510 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79  ion needs.** bey
13520 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64  ond those provid
13530 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54  ed for by [SQLIT
13540 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
13550 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  ] and.** [SQLITE
13560 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
13570 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49  E]..** ^The SQLI
13580 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f  TE_CONFIG_HEAP o
13590 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
135a0 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74  ailable if SQLit
135b0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  e is compiled.**
135c0 20 77 69 74 68 20 65 69 74 68 65 72 20 5b 53 51   with either [SQ
135d0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
135e0 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  YS3] or [SQLITE_
135f0 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20  ENABLE_MEMSYS5] 
13600 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  and returns.** [
13610 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
13620 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69   invoked otherwi
13630 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72  se..** ^There ar
13640 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
13650 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  s to SQLITE_CONF
13660 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38  IG_HEAP:.** An 8
13670 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f  -byte aligned po
13680 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
13690 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  ory,.** the numb
136a0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
136b0 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
136c0 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
136d0 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
136e0 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  e..** ^If the fi
136f0 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
13700 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
13710 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
13720 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
13730 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
13740 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
13750 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
13760 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
13770 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
13780 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
13790 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
137a0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
137b0 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65  ALLOC].  ^If the
137c0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  .** memory point
137d0 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  er is not NULL t
137e0 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
137f0 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
13800 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
13810 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
13820 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
13830 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
13840 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  eds..** The firs
13850 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
13860 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d  emory pointer) m
13870 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
13880 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62  o an 8-byte.** b
13890 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
138a0 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
138b0 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  f SQLite will be
138c0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
138d0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
138e0 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61  ation size is ca
138f0 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52  pped at 2**12. R
13900 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73  easonable values
13910 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69  .** for the mini
13920 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
13930 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72  ize are 2**5 thr
13940 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a  ough 2**8.</dd>.
13950 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13960 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64  ONFIG_MUTEX]] <d
13970 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13980 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
13990 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
139a0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74  CONFIG_MUTEX opt
139b0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
139c0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
139d0 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  h is a.** pointe
139e0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
139f0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
13a00 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
13a10 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
13a20 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
13a30 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65  fies alternative
13a40 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
13a50 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
13a60 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65  used.** in place
13a70 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
13a80 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
13a90 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74  QLite.)^  ^SQLit
13aa0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
13ab0 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
13ac0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
13ad0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
13ae0 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65  structure before
13af0 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
13b00 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13b10 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20  )] returns. ^If 
13b20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
13b30 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
13b40 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13b50 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
13b60 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
13b70 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
13b80 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
13b90 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
13ba0 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
13bb0 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
13bc0 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
13bd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
13be0 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
13bf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
13c00 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
13c10 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
13c20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
13c30 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
13c40 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13c50 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74  G_GETMUTEX]] <dt
13c60 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
13c70 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
13c80 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
13c90 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
13ca0 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  X option takes a
13cb0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
13cc0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
13cd0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
13ce0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
13cf0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
13d00 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
13d10 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
13d20 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a  _mutex_methods].
13d30 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
13d40 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
13d50 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
13d60 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  d mutex routines
13d70 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
13d80 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
13d90 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
13da0 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c  efault mutex all
13db0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
13dc0 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
13dd0 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b  er used to track
13de0 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72   mutex usage for
13df0 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20   performance.** 
13e00 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73  profiling or tes
13e10 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c  ting, for exampl
13e20 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  e.   ^If SQLite 
13e30 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13e40 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
13e50 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
13e60 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
13e70 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
13e80 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
13e90 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
13ea0 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
13eb0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
13ec0 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
13ed0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
13ee0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
13ef0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
13f00 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63  ONFIG_GETMUTEX c
13f10 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13f20 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
13f30 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
13f40 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
13f50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
13f60 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51  OKASIDE]] <dt>SQ
13f70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
13f80 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
13f90 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
13fa0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
13fb0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
13fc0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
13fd0 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68   determine.** th
13fe0 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f  e default size o
13ff0 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  f lookaside memo
14000 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61  ry on each [data
14010 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
14020 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
14030 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
14040 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
14050 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
14060 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
14070 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
14080 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
14090 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
140a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
140b0 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45  ion.)^  ^(SQLITE
140c0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
140d0 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69  E.** sets the <i
140e0 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
140f0 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
14100 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
14110 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
14120 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74  option to [sqlit
14130 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
14140 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
14150 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
14160 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
14170 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
14180 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
14190 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
141a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
141b0 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
141c0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
141d0 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
141e0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
141f0 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f  IG_PCACHE2 optio
14200 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
14210 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
14220 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  is .** a pointer
14230 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   to an [sqlite3_
14240 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
14250 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
14260 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 0a  bject specifies.
14270 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ** the interface
14280 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67   to a custom pag
14290 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
142a0 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51  tation.)^.** ^SQ
142b0 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
142c0 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
142d0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
142e0 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a  2] object.</dd>.
142f0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14300 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
14310 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14320 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c  NFIG_GETPCACHE2<
14330 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
14340 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14350 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70 74 69  _GETPCACHE2 opti
14360 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
14370 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
14380 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
14390 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   to an [sqlite3_
143a0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
143b0 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65   object.  SQLite
143c0 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68   copies of.** th
143d0 65 20 63 75 72 72 65 6e 74 20 70 61 67 65 20 63  e current page c
143e0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
143f0 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62  ion into that ob
14400 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ject.)^ </dd>.**
14410 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14420 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51  FIG_LOG]] <dt>SQ
14430 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
14440 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  /dt>.** <dd> The
14450 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
14460 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  OG option is use
14470 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74  d to configure t
14480 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f  he SQLite.** glo
14490 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e  bal [error log].
144a0 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45  .** (^The SQLITE
144b0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
144c0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
144d0 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65  uments: a pointe
144e0 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69  r to a.** functi
144f0 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73  on with a call s
14500 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64  ignature of void
14510 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  (*)(void*,int,co
14520 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20  nst char*), .** 
14530 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  and a pointer to
14540 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66   void. ^If the f
14550 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
14560 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20  is not NULL, it 
14570 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79  is.** invoked by
14580 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
14590 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68   to process each
145a0 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20   logging event. 
145b0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63   ^If the.** func
145c0 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
145d0 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74  NULL, the [sqlit
145e0 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66  e3_log()] interf
145f0 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f  ace becomes a no
14600 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69  -op..** ^The voi
14610 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  d pointer that i
14620 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
14630 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f  ument to SQLITE_
14640 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a  CONFIG_LOG is.**
14650 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
14660 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
14670 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70  ameter to the ap
14680 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
14690 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
146a0 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68  tion whenever th
146b0 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  at function is i
146c0 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65  nvoked.  ^The se
146d0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
146e0 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20  o.** the logger 
146f0 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f  function is a co
14700 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  py of the first 
14710 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
14720 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
14730 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  * [sqlite3_log()
14740 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e  ] call and is in
14750 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b  tended to be a [
14760 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
14770 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  an.** [extended 
14780 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e  result code].  ^
14790 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
147a0 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
147b0 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c  e logger is.** l
147c0 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72  og message after
147d0 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20   formatting via 
147e0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
147f0 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  f()]..** The SQL
14800 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65  ite logging inte
14810 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65  rface is not ree
14820 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67  ntrant; the logg
14830 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  er function.** s
14840 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61  upplied by the a
14850 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
14860 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53  not invoke any S
14870 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
14880 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74  .** In a multi-t
14890 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
148a0 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61  ion, the applica
148b0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
148c0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
148d0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
148e0 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  fe. </dd>.**.** 
148f0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14900 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  URI]] <dt>SQLITE
14910 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c  _CONFIG_URI.** <
14920 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  dd>^(The SQLITE_
14930 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f  CONFIG_URI optio
14940 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
14950 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
14960 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e  e int..** If non
14970 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20  -zero, then URI 
14980 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
14990 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66  ally enabled. If
149a0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
149b0 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20  s zero,.** then 
149c0 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
149d0 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
149e0 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e  d.)^ ^If URI han
149f0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
14a00 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c  y.** enabled, al
14a10 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73  l filenames pass
14a20 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ed to [sqlite3_o
14a30 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
14a40 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20  _open_v2()],.** 
14a50 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
14a60 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69  )] or.** specifi
14a70 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41  ed as part of [A
14a80 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20  TTACH] commands 
14a90 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
14aa0 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c  as URIs, regardl
14ab0 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65  ess.** of whethe
14ac0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51  r or not the [SQ
14ad0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
14ae0 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
14af0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
14b00 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
14b10 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20  ened. ^If it is 
14b20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
14b30 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  d, filenames are
14b40 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72  .** only interpr
14b50 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20  eted as URIs if 
14b60 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
14b70 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20  URI flag is set 
14b80 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61  when the.** data
14b90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
14ba0 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20  is opened. ^(By 
14bb0 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e  default, URI han
14bc0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
14bd0 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54  y.** disabled. T
14be0 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
14bf0 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20   may be changed 
14c00 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74  by compiling wit
14c10 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
14c20 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c  _USE_URI] symbol
14c30 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a   defined.)^.**.*
14c40 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14c50 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
14c60 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49  _SCAN]] <dt>SQLI
14c70 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
14c80 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a  NG_INDEX_SCAN.**
14c90 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
14ca0 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
14cb0 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69  _INDEX_SCAN opti
14cc0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
14cd0 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67  e integer.** arg
14ce0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69  ument which is i
14cf0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
14d00 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72  boolean in order
14d10 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
14d20 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65  sable.** the use
14d30 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
14d40 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61  ices for full ta
14d50 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65  ble scans in the
14d60 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72   query optimizer
14d70 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
14d80 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74  t setting is det
14d90 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68  ermined.** by th
14da0 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f  e [SQLITE_ALLOW_
14db0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
14dc0 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  CAN] compile-tim
14dd0 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20  e option, or is 
14de0 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20  "on".** if that 
14df0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
14e00 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ion is omitted..
14e10 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74  ** The ability t
14e20 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73  o disable the us
14e30 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e  e of covering in
14e40 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74  dices for full t
14e50 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73  able scans.** is
14e60 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e   because some in
14e70 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20  correctly coded 
14e80 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69  legacy applicati
14e90 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e  ons might malfun
14ea0 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68  ction.** when th
14eb0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69  e optimization i
14ec0 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76  s enabled.  Prov
14ed0 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74  iding the abilit
14ee0 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20  y to.** disable 
14ef0 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
14f00 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65   allows the olde
14f10 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61  r, buggy applica
14f20 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72  tion code to wor
14f30 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61  k.** without cha
14f40 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65  nge even with ne
14f50 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
14f60 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  SQLite..**.** [[
14f70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14f80 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f  ACHE]] [[SQLITE_
14f90 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14fa0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
14fb0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61  _CONFIG_PCACHE a
14fc0 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  nd SQLITE_CONFIG
14fd0 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64  _GETPCACHE.** <d
14fe0 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73  d> These options
14ff0 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e   are obsolete an
15000 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  d should not be 
15010 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65  used by new code
15020 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65  ..** They are re
15030 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77  tained for backw
15040 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
15050 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e  ty but are now n
15060 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  o-ops..** </dd>.
15070 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15080 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a  ONFIG_SQLLOG]].*
15090 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
150a0 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64  FIG_SQLLOG.** <d
150b0 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  d>This option is
150c0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
150d0 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d  if sqlite is com
150e0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
150f0 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
15100 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f  _SQLLOG] pre-pro
15110 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66  cessor macro def
15120 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20  ined. The first 
15130 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a  argument should.
15140 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ** be a pointer 
15150 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
15160 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f   type void(*)(vo
15170 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e  id*,sqlite3*,con
15180 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a  st char*, int)..
15190 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68  ** The second sh
151a0 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20  ould be of type 
151b0 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c  (void*). The cal
151c0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
151d0 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a   by the library.
151e0 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61  ** in three sepa
151f0 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63  rate circumstanc
15200 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62  es, identified b
15210 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73  y the value pass
15220 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  ed as the.** fou
15230 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49  rth parameter. I
15240 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
15250 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65  ameter is 0, the
15260 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
15270 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73  onnection.** pas
15280 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
15290 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a  d argument has j
152a0 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e  ust been opened.
152b0 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
152c0 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ent.** points to
152d0 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69   a buffer contai
152e0 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66  ning the name of
152f0 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
15300 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a  se file. If the.
15310 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
15320 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74  ter is 1, then t
15330 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
15340 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20   that the third 
15350 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69  parameter.** poi
15360 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20  nts to has just 
15370 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f  been executed. O
15380 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68  r, if the fourth
15390 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c   parameter is 2,
153a0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e   then.** the con
153b0 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61  nection being pa
153c0 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
153d0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
153e0 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68  being closed. Th
153f0 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
15400 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e  eter is passed N
15410 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65  ULL In this case
15420 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66  .  An example of
15430 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63   using this.** c
15440 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15450 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20  ion can be seen 
15460 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c  in the "test_sql
15470 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69  log.c" source fi
15480 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e  le in.** the can
15490 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f  onical SQLite so
154a0 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a  urce tree.</dd>.
154b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
154c0 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d  ONFIG_MMAP_SIZE]
154d0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
154e0 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
154f0 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f  .** <dd>^SQLITE_
15500 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
15510 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69   takes two 64-bi
15520 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74  t integer (sqlit
15530 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73  e3_int64) values
15540 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65  .** that are the
15550 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69   default mmap si
15560 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65  ze limit (the de
15570 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f  fault setting fo
15580 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61  r.** [PRAGMA mma
15590 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65  p_size]) and the
155a0 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
155b0 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
155c0 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
155d0 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65  t setting can be
155e0 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65   overridden by e
155f0 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
15600 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  nection using.**
15610 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41   either the [PRA
15620 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63  GMA mmap_size] c
15630 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73  ommand, or by us
15640 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ing the.** [SQLI
15650 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
15660 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
15670 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d  .  ^(The maximum
15680 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
15690 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69  ze.** will be si
156a0 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
156b0 20 69 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f   if necessary so
156c0 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f   that it does no
156d0 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20  t exceed the.** 
156e0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78  compile-time max
156f0 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73  imum mmap size s
15700 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
15710 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49  LITE_MAX_MMAP_SI
15720 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ZE] compile-time
15730 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49   option.)^.** ^I
15740 66 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e  f either argumen
15750 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  t to this option
15760 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
15770 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74  en that argument
15780 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74   is.** changed t
15790 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69  o its compile-ti
157a0 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  me default..**.*
157b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
157c0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
157d0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
157e0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
157f0 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54  APSIZE.** <dd>^T
15800 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15810 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
15820 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
15830 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69  vailable if SQLi
15840 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
15850 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69  d for Windows wi
15860 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57  th the [SQLITE_W
15870 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65  IN32_MALLOC] pre
15880 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
15890 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51  .** defined. ^SQ
158a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
158b0 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73  2_HEAPSIZE takes
158c0 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e   a 32-bit unsign
158d0 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  ed integer value
158e0 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69 66 69  .** that specifi
158f0 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73  es the maximum s
15900 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65 61 74  ize of the creat
15910 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b  ed heap..**.** [
15920 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
15930 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a  CACHE_HDRSZ]].**
15940 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15950 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a  IG_PCACHE_HDRSZ.
15960 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
15970 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15980 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61  _HDRSZ option ta
15990 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72  kes a single par
159a0 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ameter which.** 
159b0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
159c0 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77  an integer and w
159d0 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20  rites into that 
159e0 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62  integer the numb
159f0 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62  er of extra.** b
15a00 79 74 65 73 20 70 65 72 20 70 61 67 65 20 72 65  ytes per page re
15a10 71 75 69 72 65 64 20 66 6f 72 20 65 61 63 68 20  quired for each 
15a20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f  page in [SQLITE_
15a30 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
15a40 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74  ]..** The amount
15a50 20 6f 66 20 65 78 74 72 61 20 73 70 61 63 65 20   of extra space 
15a60 72 65 71 75 69 72 65 64 20 63 61 6e 20 63 68 61  required can cha
15a70 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  nge depending on
15a80 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a   the compiler,.*
15a90 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72  * target platfor
15aa0 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65  m, and SQLite ve
15ab0 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  rsion..**.** [[S
15ac0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
15ad0 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  SZ]].** <dt>SQLI
15ae0 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a  TE_CONFIG_PMASZ.
15af0 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
15b00 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20  TE_CONFIG_PMASZ 
15b10 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15b20 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20  ingle parameter 
15b30 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75  which.** is an u
15b40 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
15b50 61 6e 64 20 73 65 74 73 20 74 68 65 20 22 4d 69  and sets the "Mi
15b60 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20  nimum PMA Size" 
15b70 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72  for the multithr
15b80 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20  eaded.** sorter 
15b90 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  to that integer.
15ba0 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69    The default mi
15bb0 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69  nimum PMA Size i
15bc0 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20  s set by the.** 
15bd0 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50  [SQLITE_SORTER_P
15be0 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  MASZ] compile-ti
15bf0 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20  me option.  New 
15c00 74 68 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e  threads are laun
15c10 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20  ched.** to help 
15c20 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74  with sort operat
15c30 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74  ions when multit
15c40 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a  hreaded sorting.
15c50 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75  ** is enabled (u
15c60 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  sing the [PRAGMA
15c70 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e   threads] comman
15c80 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e  d) and the amoun
15c90 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20  t of content.** 
15ca0 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65 78 63  to be sorted exc
15cb0 65 65 64 73 20 74 68 65 20 70 61 67 65 20 73 69  eeds the page si
15cc0 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e  ze times the min
15cd0 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  imum of the.** [
15ce0 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a  PRAGMA cache_siz
15cf0 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74  e] setting and t
15d00 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 20 3c 2f  his value..** </
15d10 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
15d20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
15d30 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a  GLETHREAD  1  /*
15d40 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
15d50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
15d60 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f  LTITHREAD   2  /
15d70 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
15d80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
15d90 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20  ERIALIZED    3  
15da0 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
15db0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15dc0 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20  MALLOC        4 
15dd0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
15de0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
15df0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15e00 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20  G_GETMALLOC     
15e10 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  5  /* sqlite3_me
15e20 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
15e30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15e40 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20  FIG_SCRATCH     
15e50 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    6  /* void*, i
15e60 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
15e70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
15e80 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
15e90 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c      7  /* void*,
15ea0 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
15eb0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15ec0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20  _CONFIG_HEAP    
15ed0 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64        8  /* void
15ee0 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e  *, int nByte, in
15ef0 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  t min */.#define
15f00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
15f10 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20  EMSTATUS     9  
15f20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64  /* boolean */.#d
15f30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15f40 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20  FIG_MUTEX       
15f50 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   10  /* sqlite3_
15f60 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
15f70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15f80 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
15f90 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69       11  /* sqli
15fa0 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
15fb0 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75  s* */./* previou
15fc0 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  sly SQLITE_CONFI
15fd0 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20  G_CHUNKALLOC 12 
15fe0 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75  which is now unu
15ff0 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65  sed. */ .#define
16000 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
16010 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20  OOKASIDE    13  
16020 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  /* int int */.#d
16030 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16040 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20  FIG_PCACHE      
16050 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f   14  /* no-op */
16060 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16070 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
16080 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70      15  /* no-op
16090 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
160a0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20  TE_CONFIG_LOG   
160b0 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46         16  /* xF
160c0 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64  unc, void* */.#d
160d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
160e0 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20  FIG_URI         
160f0 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   17  /* int */.#
16100 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16110 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 20  NFIG_PCACHE2    
16120 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33    18  /* sqlite3
16130 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
16140 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
16150 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
16160 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73  ACHE2   19  /* s
16170 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
16180 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
16190 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
161a0 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
161b0 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20  SCAN 20  /* int 
161c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
161d0 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20  E_CONFIG_SQLLOG 
161e0 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71        21  /* xSq
161f0 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  llog, void* */.#
16200 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16210 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  NFIG_MMAP_SIZE  
16220 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33    22  /* sqlite3
16230 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f  _int64, sqlite3_
16240 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65  int64 */.#define
16250 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
16260 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20 20  IN32_HEAPSIZE   
16270 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42     23  /* int nB
16280 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  yte */.#define S
16290 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
162a0 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20 20 20  CHE_HDRSZ       
162b0 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a   24  /* int *psz
162c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
162d0 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20  TE_CONFIG_PMASZ 
162e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
162f0 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e    /* unsigned in
16300 74 20 73 7a 50 6d 61 20 2a 2f 0a 0a 2f 2a 0a 2a  t szPma */../*.*
16310 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
16320 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
16330 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
16340 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
16350 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
16360 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
16370 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
16380 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
16390 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
163a0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
163b0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
163c0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
163d0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
163e0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
163f0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
16400 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
16410 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
16420 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
16430 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
16440 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
16450 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
16460 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
16470 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
16480 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
16490 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
164a0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
164b0 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
164c0 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
164d0 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
164e0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
164f0 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
16500 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
16510 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
16520 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
16530 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
16540 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
16550 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
16560 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
16570 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
16580 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
16590 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
165a0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
165b0 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
165c0 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
165d0 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
165e0 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
165f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
16600 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
16610 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
16620 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
16630 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
16640 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
16650 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
16660 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
16670 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
16680 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62  er to a memory b
16690 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
166a0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
166b0 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
166c0 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
166d0 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
166e0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
166f0 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
16700 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
16710 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
16720 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
16730 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
16740 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
16750 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
16760 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
16770 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
16780 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
16790 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
167a0 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
167b0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
167c0 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
167d0 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
167e0 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
167f0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
16800 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
16810 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
16820 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
16830 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
16840 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
16850 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
16860 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
16870 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
16880 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
16890 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
168a0 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
168b0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
168c0 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
168d0 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
168e0 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
168f0 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
16900 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75   next smaller mu
16910 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28  ltiple of 8.  ^(
16920 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  The lookaside me
16930 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  mory.** configur
16940 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61  ation for a data
16950 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
16960 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e  can only be chan
16970 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a  ged when that.**
16980 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e   connection is n
16990 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  ot currently usi
169a0 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  ng lookaside mem
169b0 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72  ory, or in other
169c0 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74   words.** when t
169d0 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75  he "current valu
169e0 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  e" returned by.*
169f0 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  * [sqlite3_db_st
16a00 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  atus](D,[SQLITE_
16a10 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
16a20 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a  ],...) is zero..
16a30 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
16a40 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
16a50 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
16a60 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e  nfiguration when
16a70 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65   lookaside.** me
16a80 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c  mory is in use l
16a90 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67  eaves the config
16aa0 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65  uration unchange
16ab0 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a  d and returns .*
16ac0 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
16ad0 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  )^</dd>.**.** <d
16ae0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
16af0 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64  G_ENABLE_FKEY</d
16b00 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
16b10 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
16b20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
16b30 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65  able the enforce
16b40 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65  ment of.** [fore
16b50 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
16b60 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f  nts].  There sho
16b70 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
16b80 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
16b90 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
16ba0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
16bb0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
16bc0 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e  to disable FK en
16bd0 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f  forcement,.** po
16be0 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
16bf0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
16c00 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
16c10 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  eave FK enforcem
16c20 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ent.** unchanged
16c30 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
16c40 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
16c50 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
16c60 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
16c70 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
16c80 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
16c90 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63  hether FK enforc
16ca0 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20  ement is off or 
16cb0 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  on.** following 
16cc0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
16cd0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16ce0 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
16cf0 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
16d00 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20  ich case the FK 
16d10 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74  enforcement sett
16d20 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
16d30 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
16d40 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
16d50 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
16d60 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a  _TRIGGER</dt>.**
16d70 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
16d80 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
16d90 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
16da0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
16db0 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20  | triggers]..** 
16dc0 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
16dd0 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
16de0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
16df0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16e00 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
16e10 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
16e20 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a  ble triggers,.**
16e30 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
16e40 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20  ble triggers or 
16e50 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
16e60 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e  e the setting un
16e70 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
16e80 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
16e90 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
16ea0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
16eb0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
16ec0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
16ed0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
16ee0 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73  triggers are dis
16ef0 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
16f00 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
16f10 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
16f20 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
16f30 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
16f40 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
16f50 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67  h case the trigg
16f60 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  er setting is no
16f70 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
16f80 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64   </dd>.**.** </d
16f90 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
16fa0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
16fb0 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30  OKASIDE       10
16fc0 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  01  /* void* int
16fd0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
16fe0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16ff0 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20  ENABLE_FKEY     
17000 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74  1002  /* int int
17010 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
17020 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
17030 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30  BLE_TRIGGER  100
17040 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  3  /* int int* *
17050 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
17060 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
17070 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
17080 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a  esult Codes.**.*
17090 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
170a0 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
170b0 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
170c0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
170d0 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
170e0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
170f0 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
17100 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64  ite. ^The extend
17110 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
17120 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
17130 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
17140 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
17150 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20  ibility..*/.int 
17160 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
17170 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
17180 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
17190 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
171a0 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
171b0 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61   Rowid.**.** ^Ea
171c0 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74  ch entry in most
171d0 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28   SQLite tables (
171e0 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48  except for [WITH
171f0 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
17200 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71  s).** has a uniq
17210 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
17220 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
17230 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
17240 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
17250 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
17260 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
17270 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
17280 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
17290 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
172a0 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
172b0 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
172c0 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
172d0 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
172e0 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
172f0 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
17300 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
17310 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
17320 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
17330 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
17340 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
17350 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
17360 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
17370 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
17380 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61  rowid(D) interfa
17390 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
173a0 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a  rowid] of the .*
173b0 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75  * most recent su
173c0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
173d0 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74  ] into a rowid t
173e0 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c  able or [virtual
173f0 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61   table].** on da
17400 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17410 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73  n D..** ^Inserts
17420 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52   into [WITHOUT R
17430 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65  OWID] tables are
17440 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a   not recorded..*
17450 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  * ^If no success
17460 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e  ful [INSERT]s in
17470 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a  to rowid tables.
17480 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
17490 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74  urred on the dat
174a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
174b0 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c   D, .** then sql
174c0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
174d0 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e  _rowid(D) return
174e0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s zero..**.** ^(
174f0 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
17500 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
17510 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e  rigger or within
17520 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
17530 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68  e].** method, th
17540 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
17550 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  will return the 
17560 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
17570 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61  nserted.** row a
17580 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
17590 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
175a0 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73   table method is
175b0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
175c0 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
175d0 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
175e0 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20  le method ends, 
175f0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
17600 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72  ed .** by this r
17610 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74  outine reverts t
17620 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65  o what it was be
17630 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
17640 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74   or virtual.** t
17650 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61  able method bega
17660 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b  n.)^.**.** ^An [
17670 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69  INSERT] that fai
17680 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
17690 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
176a0 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
176b0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
176c0 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
176d0 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
176e0 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
176f0 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68  ** routine.  ^Th
17700 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
17710 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
17720 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
17730 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
17740 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
17750 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
17760 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
17770 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
17780 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
17790 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
177a0 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52  s.  ^(When INSER
177b0 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20  T OR REPLACE.** 
177c0 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
177d0 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
177e0 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
177f0 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
17800 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
17810 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
17820 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
17830 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
17840 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
17850 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
17860 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
17870 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
17880 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
17890 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
178a0 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  ace.)^.**.** ^Fo
178b0 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
178c0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
178d0 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
178e0 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
178f0 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
17900 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
17910 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
17920 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  back..**.** This
17930 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63   function is acc
17940 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73  essible to SQL s
17950 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68  tatements via th
17960 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72  e.** [last_inser
17970 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75  t_rowid() SQL fu
17980 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
17990 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
179a0 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
179b0 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74  ew [INSERT] on t
179c0 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62  he same.** datab
179d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
179e0 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
179f0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
17a00 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  wid()].** functi
17a10 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
17a20 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
17a30 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  he last insert [
17a40 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20  rowid],.** then 
17a50 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
17a60 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
17a70 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
17a80 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64  ()] is.** unpred
17a90 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
17aa0 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
17ab0 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
17ac0 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e  e new.** last in
17ad0 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f  sert [rowid]..*/
17ae0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
17af0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
17b00 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
17b10 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
17b20 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
17b30 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
17b40 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
17b50 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
17b60 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
17b70 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c  f rows modified,
17b80 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20   inserted or.** 
17b90 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d  deleted by the m
17ba0 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
17bb0 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
17bc0 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a  PDATE or DELETE.
17bd0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20  ** statement on 
17be0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
17bf0 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65  nection specifie
17c00 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61  d by the only pa
17c10 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65  rameter..** ^Exe
17c20 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72  cuting any other
17c30 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61   type of SQL sta
17c40 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
17c50 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75 65  modify the value
17c60 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
17c70 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  this function..*
17c80 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67  *.** ^Only chang
17c90 65 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79  es made directly
17ca0 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20   by the INSERT, 
17cb0 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
17cc0 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a   statement are.*
17cd0 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61  * considered - a
17ce0 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73  uxiliary changes
17cf0 20 63 61 75 73 65 64 20 62 79 20 5b 43 52 45 41   caused by [CREA
17d00 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
17d10 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72  ggers], .** [for
17d20 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
17d30 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63  ] or [REPLACE] c
17d40 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
17d50 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75  tion are not cou
17d60 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61  nted..** .** Cha
17d70 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74  nges to a view t
17d80 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70  hat are intercep
17d90 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54  ted by .** [INST
17da0 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c  EAD OF trigger |
17db0 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67   INSTEAD OF trig
17dc0 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f  gers] are not co
17dd0 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75  unted. ^The valu
17de0 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  e .** returned b
17df0 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  y sqlite3_change
17e00 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  s() immediately 
17e10 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c  after an INSERT,
17e20 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44   UPDATE or .** D
17e30 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
17e40 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73  run on a view is
17e50 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e   always zero. On
17e60 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  ly changes made 
17e70 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c  to real .** tabl
17e80 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a  es are counted..
17e90 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65  **.** Things are
17ea0 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65   more complicate
17eb0 64 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33  d if the sqlite3
17ec0 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
17ed0 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74  ion is.** execut
17ee0 65 64 20 77 68 69 6c 65 20 61 20 74 72 69 67 67  ed while a trigg
17ef0 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75  er program is ru
17f00 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20  nning. This may 
17f10 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a  happen if the.**
17f20 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68   program uses th
17f30 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
17f40 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69   function], or i
17f50 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c  f some other cal
17f60 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
17f70 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65  n invokes sqlite
17f80 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72 65  3_changes() dire
17f90 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c  ctly. Essentiall
17fa0 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a  y:.** .** <ul>.*
17fb0 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72  *   <li> ^(Befor
17fc0 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69  e entering a tri
17fd0 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65  gger program the
17fe0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
17ff0 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c  by.**        sql
18000 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66  ite3_changes() f
18010 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64  unction is saved
18020 2e 20 41 66 74 65 72 20 74 68 65 20 74 72 69 67  . After the trig
18030 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20  ger program .** 
18040 20 20 20 20 20 20 20 68 61 73 20 66 69 6e 69 73         has finis
18050 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61  hed, the origina
18060 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f  l value is resto
18070 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20  red.)^.** .**   
18080 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20  <li> ^(Within a 
18090 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
180a0 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44  each INSERT, UPD
180b0 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a  ATE and DELETE .
180c0 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74 65 6d  **        statem
180d0 65 6e 74 20 73 65 74 73 20 74 68 65 20 76 61 6c  ent sets the val
180e0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
180f0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
18100 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e   .**        upon
18110 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e   completion as n
18120 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65  ormal. Of course
18130 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c  , this value wil
18140 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a  l not include .*
18150 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63 68 61  *        any cha
18160 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62  nges performed b
18170 79 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20  y sub-triggers, 
18180 61 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  as the sqlite3_c
18190 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20  hanges() .**    
181a0 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62      value will b
181b0 65 20 73 61 76 65 64 20 61 6e 64 20 72 65 73 74  e saved and rest
181c0 6f 72 65 64 20 61 66 74 65 72 20 65 61 63 68 20  ored after each 
181d0 73 75 62 2d 74 72 69 67 67 65 72 20 68 61 73 20  sub-trigger has 
181e0 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  run.)^.** </ul>.
181f0 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61  ** .** ^This mea
18200 6e 73 20 74 68 61 74 20 69 66 20 74 68 65 20 63  ns that if the c
18210 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
18220 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61  ction (or simila
18230 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79  r) is used.** by
18240 20 74 68 65 20 66 69 72 73 74 20 49 4e 53 45 52   the first INSER
18250 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
18260 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
18270 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
18280 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74  it .** returns t
18290 68 65 20 76 61 6c 75 65 20 61 73 20 73 65 74 20  he value as set 
182a0 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67  when the calling
182b0 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e   statement began
182c0 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
182d0 49 66 20 69 74 20 69 73 20 75 73 65 64 20 62 79  If it is used by
182e0 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73   the second or s
182f0 75 62 73 65 71 75 65 6e 74 20 73 75 63 68 20 73  ubsequent such s
18300 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
18310 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72  a trigger .** pr
18320 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65  ogram, the value
18330 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63   returned reflec
18340 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ts the number of
18350 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62   rows modified b
18360 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f  y the .** previo
18370 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  us INSERT, UPDAT
18380 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  E or DELETE stat
18390 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
183a0 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a   same trigger..*
183b0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
183c0 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
183d0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
183e0 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
183f0 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
18400 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63  gma], and the [c
18410 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
18420 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
18430 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
18440 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
18450 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
18460 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18470 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
18480 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  e3_changes()] is
18490 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
184a0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
184b0 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74  .** is unpredict
184c0 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
184d0 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
184e0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
184f0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
18500 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
18510 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
18520 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20   Modified.**.** 
18530 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
18540 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74 61 6c  eturns the total
18550 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
18560 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69 66 69  inserted, modifi
18570 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64  ed or.** deleted
18580 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52 54 5d   by all [INSERT]
18590 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44  , [UPDATE] or [D
185a0 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
185b0 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a 20 73  s completed.** s
185c0 69 6e 63 65 20 74 68 65 20 64 61 74 61 62 61 73  ince the databas
185d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 61 73  e connection was
185e0 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75 64 69   opened, includi
185f0 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75 74 65  ng those execute
18600 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20  d as.** part of 
18610 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 73  trigger programs
18620 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  . ^Executing any
18630 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
18640 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL statement.** 
18650 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63 74 20  does not affect 
18660 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
18670 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
18680 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e 0a 2a  tal_changes()..*
18690 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 6d  * .** ^Changes m
186a0 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 5b  ade as part of [
186b0 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
186c0 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75 64 65  ons] are include
186d0 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f 75 6e  d in the.** coun
186e0 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d 61 64  t, but those mad
186f0 65 20 61 73 20 70 61 72 74 20 6f 66 20 52 45 50  e as part of REP
18700 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e 74 20  LACE constraint 
18710 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 0a 2a  resolution are.*
18720 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65 73 20  * not. ^Changes 
18730 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
18740 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20 62  re intercepted b
18750 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  y INSTEAD OF tri
18760 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20 6e 6f  ggers .** are no
18770 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a  t counted..** .*
18780 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
18790 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
187a0 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
187b0 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
187c0 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
187d0 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e   the [total_chan
187e0 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
187f0 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
18800 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
18810 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
18820 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
18830 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
18840 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
18850 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
18860 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
18870 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   the value.** re
18880 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64  turned is unpred
18890 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
188a0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
188b0 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  nt sqlite3_total
188c0 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
188d0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
188e0 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
188f0 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
18900 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ery.**.** ^This 
18910 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
18920 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
18930 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
18940 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
18950 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
18960 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
18970 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
18980 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
18990 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
189a0 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
189b0 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
189c0 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
189d0 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
189e0 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
189f0 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
18a00 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
18a10 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
18a20 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
18a30 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
18a40 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
18a50 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
18a60 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
18a70 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
18a80 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
18a90 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
18aa0 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
18ab0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
18ac0 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
18ad0 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
18ae0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
18af0 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
18b00 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
18b10 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
18b20 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
18b30 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
18b40 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
18b50 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
18b60 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
18b70 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
18b80 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
18b90 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
18ba0 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
18bb0 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
18bc0 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
18bd0 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
18be0 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
18bf0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
18c00 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
18c10 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
18c20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
18c30 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
18c40 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
18c50 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
18c60 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
18c70 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
18c80 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
18c90 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
18ca0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
18cb0 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
18cc0 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
18cd0 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
18ce0 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
18cf0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
18d00 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
18d10 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
18d20 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
18d30 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
18d40 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
18d50 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
18d60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
18d70 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
18d80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
18d90 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
18da0 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
18db0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
18dc0 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
18dd0 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
18de0 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
18df0 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
18e00 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
18e10 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
18e20 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
18e30 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
18e40 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
18e50 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
18e60 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
18e70 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
18e80 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
18e90 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
18ea0 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
18eb0 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
18ec0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
18ed0 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
18ee0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
18ef0 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
18f00 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
18f10 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
18f20 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
18f30 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
18f40 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
18f50 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
18f60 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
18f70 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
18f80 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
18f90 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
18fa0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ..**.** If the d
18fb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18fc0 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
18fd0 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
18fe0 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
18ff0 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
19000 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
19010 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20  happen..*/.void 
19020 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
19030 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
19040 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
19050 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
19060 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43  L Statement Is C
19070 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68  omplete.**.** Th
19080 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
19090 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63   useful during c
190a0 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75  ommand-line inpu
190b0 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69  t to determine i
190c0 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  f the.** current
190d0 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20  ly entered text 
190e0 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20  seems to form a 
190f0 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
19100 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20  tement or.** if 
19110 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74  additional input
19120 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72   is needed befor
19130 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65  e sending the te
19140 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74  xt into.** SQLit
19150 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20  e for parsing.  
19160 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
19170 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20  return 1 if the 
19180 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20  input string.** 
19190 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20  appears to be a 
191a0 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61  complete SQL sta
191b0 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74  tement.  ^A stat
191c0 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20  ement is judged 
191d0 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  to be.** complet
191e0 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74  e if it ends wit
191f0 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f  h a semicolon to
19200 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ken and is not a
19210 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20   prefix of a.** 
19220 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41  well-formed CREA
19230 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65  TE TRIGGER state
19240 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f  ment.  ^Semicolo
19250 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65  ns that are embe
19260 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73  dded within.** s
19270 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f  tring literals o
19280 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66  r quoted identif
19290 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d  ier names or com
192a0 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a  ments are not.**
192b0 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b   independent tok
192c0 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61  ens (they are pa
192d0 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20  rt of the token 
192e0 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72  in which they ar
192f0 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61  e.** embedded) a
19300 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63  nd thus do not c
19310 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d  ount as a statem
19320 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ent terminator. 
19330 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20   ^Whitespace.** 
19340 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61  and comments tha
19350 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e  t follow the fin
19360 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65  al semicolon are
19370 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
19380 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
19390 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20  return 0 if the 
193a0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63  statement is inc
193b0 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a  omplete.  ^If a.
193c0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
193d0 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e  tion fails, then
193e0 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73   SQLITE_NOMEM is
193f0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
19400 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
19410 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68   do not parse th
19420 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
19430 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f   thus.** will no
19440 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74  t detect syntact
19450 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74  ically incorrect
19460 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66   SQL..**.** ^(If
19470 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20   SQLite has not 
19480 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64  been initialized
19490 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
194a0 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72  initialize()] pr
194b0 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b  ior .** to invok
194c0 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ing sqlite3_comp
194d0 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71  lete16() then sq
194e0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
194f0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
19500 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
19510 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  y sqlite3_comple
19520 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74  te16().  If that
19530 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
19540 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  fails,.** then t
19550 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
19560 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d  from sqlite3_com
19570 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62  plete16() will b
19580 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65  e non-zero.** re
19590 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
195a0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69  her or not the i
195b0 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70  nput SQL is comp
195c0 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  lete.)^.**.** Th
195d0 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
195e0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20  te3_complete()] 
195f0 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
19600 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
19610 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  -8 string..**.**
19620 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
19630 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
19640 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  6()] must be a z
19650 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
19660 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  * UTF-16 string 
19670 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
19680 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  rder..*/.int sql
19690 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
196a0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
196b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
196c0 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
196d0 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
196e0 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
196f0 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
19700 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
19710 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45  USY Errors.** KE
19720 59 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61  YWORDS: {busy-ha
19730 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20  ndler callback} 
19740 7b 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a  {busy handler}.*
19750 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
19760 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44  3_busy_handler(D
19770 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65  ,X,P) routine se
19780 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
19790 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74  nction X.** that
197a0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
197b0 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  d with argument 
197c0 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  P whenever.** an
197d0 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
197e0 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61 74   to access a dat
197f0 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f  abase table asso
19800 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b  ciated with.** [
19810 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19820 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74  ion] D when anot
19830 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
19840 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68 65   process has the
19850 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a   table locked..*
19860 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75  * The sqlite3_bu
19870 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74  sy_handler() int
19880 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
19890 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b  o implement.** [
198a0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
198b0 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41  eout()] and [PRA
198c0 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
198d0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
198e0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
198f0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51  s NULL, then [SQ
19900 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73  LITE_BUSY].** is
19910 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
19920 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
19930 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
19940 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
19950 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
19960 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
19970 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
19980 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
19990 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
199a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
199b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
199c0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
199d0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
199e0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
199f0 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
19a00 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
19a10 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
19a20 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
19a30 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
19a40 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
19a50 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
19a60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
19a70 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
19a80 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
19a90 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72   been invoked pr
19aa0 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65  eviously for the
19ab0 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76   same locking ev
19ac0 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
19ad0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72   busy callback r
19ae0 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e  eturns 0, then n
19af0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74  o additional att
19b00 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74  empts are made t
19b10 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20  o.** access the 
19b20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51  database and [SQ
19b30 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65  LITE_BUSY] is re
19b40 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65  turned.** to the
19b50 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a   application..**
19b60 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
19b70 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
19b80 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
19b90 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d   attempt.** is m
19ba0 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74 68  ade to access th
19bb0 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74  e database and t
19bc0 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
19bd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
19be0 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
19bf0 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
19c00 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
19c10 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
19c20 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
19c30 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
19c40 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64  on. ^If SQLite d
19c50 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
19c60 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
19c70 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  .** handler coul
19c80 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65  d result in a de
19c90 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
19ca0 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
19cb0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
19cc0 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c  ].** to the appl
19cd0 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20  ication instead 
19ce0 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  of invoking the 
19cf0 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72  .** busy handler
19d00 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
19d10 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
19d20 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
19d30 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
19d40 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
19d50 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
19d60 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
19d70 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
19d80 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
19d90 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
19da0 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
19db0 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
19dc0 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
19dd0 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
19de0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
19df0 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
19e00 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
19e10 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
19e20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
19e30 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
19e40 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
19e50 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
19e60 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
19e70 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
19e80 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
19e90 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
19ea0 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
19eb0 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
19ec0 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
19ed0 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
19ee0 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
19ef0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
19f00 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
19f10 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
19f20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
19f30 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
19f40 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
19f50 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
19f60 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
19f70 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
19f80 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
19f90 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
19fa0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s NULL..**.** ^(
19fb0 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
19fc0 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
19fd0 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
19fe0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
19ff0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a000 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
1a010 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
1a020 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
1a030 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
1a040 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68  ler.)^  ^Note th
1a050 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
1a060 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1a070 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61  ()].** or evalua
1a080 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73  ting [PRAGMA bus
1a090 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c  y_timeout=N] wil
1a0a0 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  l change the.** 
1a0b0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64  busy handler and
1a0c0 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20   thus clear any 
1a0d0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62  previously set b
1a0e0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
1a0f0 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
1a100 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
1a110 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
1a120 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
1a130 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
1a140 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
1a150 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
1a160 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65  andler.  In othe
1a170 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20  r words,.** the 
1a180 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1a190 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20  not reentrant.  
1a1a0 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73  Any such actions
1a1b0 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  .** result in un
1a1c0 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
1a1d0 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20  ..** .** A busy 
1a1e0 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74  handler must not
1a1f0 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
1a200 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1a210 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73  * or [prepared s
1a220 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
1a230 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
1a240 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20  handler..*/.int 
1a250 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1a260 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
1a270 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29  nt(*)(void*,int)
1a280 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1a290 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41   CAPI3REF: Set A
1a2a0 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a   Busy Timeout.**
1a2b0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
1a2c0 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65  e sets a [sqlite
1a2d0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c  3_busy_handler |
1a2e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74   busy handler] t
1a2f0 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f  hat sleeps.** fo
1a300 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d  r a specified am
1a310 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65  ount of time whe
1a320 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63  n a table is loc
1a330 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ked.  ^The handl
1a340 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70  er.** will sleep
1a350 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
1a360 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22  until at least "
1a370 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
1a380 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20   of sleeping.** 
1a390 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64  have accumulated
1a3a0 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61  .  ^After at lea
1a3b0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
1a3c0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
1a3d0 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  ,.** the handler
1a3e0 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68   returns 0 which
1a3f0 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33   causes [sqlite3
1a400 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75  _step()] to retu
1a410 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  rn.** [SQLITE_BU
1a420 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  SY]..**.** ^Call
1a430 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
1a440 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
1a450 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
1a460 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
1a470 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
1a480 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
1a490 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
1a4a0 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
1a4b0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
1a4c0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
1a4d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1a4e0 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69  ction] at any gi
1a4f0 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
1a500 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
1a510 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
1a520 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
1a530 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1a540 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
1a550 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
1a560 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
1a570 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
1a580 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a  is cleared.)^.**
1a590 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
1a5a0 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
1a5b0 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  out].*/.int sqli
1a5c0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1a5d0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
1a5e0 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
1a5f0 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
1a600 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
1a610 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a  nning Queries.**
1a620 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65  .** This is a le
1a630 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74  gacy interface t
1a640 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64  hat is preserved
1a650 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
1a660 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1a670 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74   Use of this int
1a680 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
1a690 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
1a6a0 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c   Definition: A <
1a6b0 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f  b>result table</
1a6c0 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74  b> is memory dat
1a6d0 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61  a structure crea
1a6e0 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73  ted by the.** [s
1a6f0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1a700 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
1a710 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72  A result table r
1a720 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f  ecords the.** co
1a730 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73  mplete query res
1a740 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72  ults from one or
1a750 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a   more queries..*
1a760 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63  *.** The table c
1a770 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20  onceptually has 
1a780 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  a number of rows
1a790 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42   and columns.  B
1a7a0 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62  ut.** these numb
1a7b0 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74  ers are not part
1a7c0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
1a7d0 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68  able itself.  Th
1a7e0 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61  ese.** numbers a
1a7f0 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61  re obtained sepa
1a800 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62  rately.  Let N b
1a810 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1a820 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65  rows.** and M be
1a830 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1a840 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  olumns..**.** A 
1a850 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
1a860 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
1a870 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
1a880 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
1a890 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20  rings..** There 
1a8a0 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d  are (N+1)*M elem
1a8b0 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61  ents in the arra
1a8c0 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20  y.  The first M 
1a8d0 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a  pointers point.*
1a8e0 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  * to zero-termin
1a8f0 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
1a900 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e  t  contain the n
1a910 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ames of the colu
1a920 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61  mns..** The rema
1a930 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c  ining entries al
1a940 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79  l point to query
1a950 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20   results.  NULL 
1a960 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a  values result.**
1a970 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   in NULL pointer
1a980 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  s.  All other va
1a990 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69  lues are in thei
1a9a0 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  r UTF-8 zero-ter
1a9b0 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
1a9c0 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  g representation
1a9d0 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   as returned by 
1a9e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1a9f0 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  text()]..**.** A
1aa00 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69   result table mi
1aa10 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f  ght consist of o
1aa20 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
1aa30 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
1aa40 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
1aa50 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
1aa60 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
1aa70 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1aa80 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
1aa90 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
1aaa0 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
1aab0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
1aac0 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
1aad0 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c  * ^(As an exampl
1aae0 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  e of the result 
1aaf0 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75  table format, su
1ab00 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65  ppose a query re
1ab10 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f  sult.** is as fo
1ab20 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1ab30 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1ab40 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  *        Name   
1ab50 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20       | Age.**   
1ab60 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d       -----------
1ab70 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20  ------------.** 
1ab80 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20         Alice    
1ab90 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20     | 43.**      
1aba0 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20    Bob         | 
1abb0 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e  28.**        Cin
1abc0 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a  dy       | 21.**
1abd0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1abe0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ote>.**.** There
1abf0 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20   are two column 
1ac00 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65  (M==2) and three
1ac10 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54   rows (N==3).  T
1ac20 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  hus the.** resul
1ac30 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e  t table has 8 en
1ac40 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20  tries.  Suppose 
1ac50 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1ac60 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e   is stored.** in
1ac70 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20   an array names 
1ac80 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20  azResult.  Then 
1ac90 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74  azResult holds t
1aca0 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a  his content:.**.
1acb0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1acc0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61  pre>.**        a
1acd0 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d  zResult&#91;0] =
1ace0 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
1acf0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1ad00 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
1ad10 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1ad20 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  91;2] = "Alice";
1ad30 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1ad40 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33  ult&#91;3] = "43
1ad50 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1ad60 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22  esult&#91;4] = "
1ad70 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
1ad80 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20  azResult&#91;5] 
1ad90 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
1ada0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36    azResult&#91;6
1adb0 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
1adc0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1add0 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a  #91;7] = "21";.*
1ade0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1adf0 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
1ae00 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1ae10 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  able() function 
1ae20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72  evaluates one or
1ae30 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c   more.** semicol
1ae40 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c  on-separated SQL
1ae50 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
1ae60 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
1ae70 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69  ed UTF-8.** stri
1ae80 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
1ae90 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
1aea0 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  rns a result tab
1aeb0 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69  le to the.** poi
1aec0 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74  nter given in it
1aed0 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e  s 3rd parameter.
1aee0 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65  .**.** After the
1aef0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73   application has
1af00 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74   finished with t
1af10 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73  he result from s
1af20 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1af30 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70  (),.** it must p
1af40 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74  ass the result t
1af50 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20  able pointer to 
1af60 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1af70 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
1af80 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
1af90 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
1afa0 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
1afb0 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
1afc0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
1afd0 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
1afe0 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
1aff0 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
1b000 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
1b010 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
1b020 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
1b030 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
1b040 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
1b050 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1b060 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
1b070 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1b080 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
1b090 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
1b0a0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1b0b0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
1b0c0 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
1b0d0 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
1b0e0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
1b0f0 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
1b100 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1b110 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
1b120 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
1b130 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
1b140 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
1b150 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
1b160 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
1b170 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
1b180 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
1b190 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
1b1a0 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
1b1b0 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
1b1c0 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
1b1d0 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
1b1e0 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
1b1f0 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
1b200 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
1b210 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
1b220 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
1b230 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20  rrcode()] or.** 
1b240 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1b250 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
1b260 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
1b270 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1b280 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
1b290 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
1b2a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
1b2b0 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
1b2c0 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
1b2d0 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
1b2e0 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
1b2f0 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
1b300 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
1b310 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
1b320 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
1b330 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
1b340 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
1b350 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
1b360 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
1b370 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
1b380 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
1b390 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
1b3a0 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
1b3b0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
1b3c0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1b3d0 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
1b3e0 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
1b3f0 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
1b400 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
1b410 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1b420 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1b430 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73   are work-alikes
1b440 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
1b450 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
1b460 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
1b470 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1b480 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20  brary..** These 
1b490 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74  routines underst
1b4a0 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20  and most of the 
1b4b0 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61  common K&R forma
1b4c0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a  tting options,.*
1b4d0 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69  * plus some addi
1b4e0 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64  tional non-stand
1b4f0 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74  ard formats, det
1b500 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20  ailed below..** 
1b510 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f  Note that some o
1b520 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75  f the more obscu
1b530 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  re formatting op
1b540 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e  tions from recen
1b550 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73  t.** C-library s
1b560 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69  tandards are omi
1b570 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69  tted from this i
1b580 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a  mplementation..*
1b590 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1b5a0 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
1b5b0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1b5c0 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
1b5d0 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
1b5e0 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
1b5f0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
1b600 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
1b610 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
1b620 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1b630 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
1b640 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
1b650 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
1b660 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
1b670 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1b680 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
1b690 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
1b6a0 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
1b6b0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
1b6c0 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
1b6d0 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
1b6e0 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
1b6f0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1b700 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
1b710 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
1b720 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
1b730 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
1b740 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
1b750 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
1b760 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
1b770 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
1b780 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1b790 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
1b7a0 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
1b7b0 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
1b7c0 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
1b7d0 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
1b7e0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
1b7f0 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
1b800 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
1b810 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
1b820 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
1b830 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
1b840 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
1b850 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
1b860 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
1b870 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1b880 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
1b890 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
1b8a0 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
1b8b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
1b8c0 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
1b8d0 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
1b8e0 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
1b8f0 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
1b900 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
1b910 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
1b920 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
1b930 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
1b940 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
1b950 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
1b960 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
1b970 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
1b980 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
1b990 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
1b9a0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
1b9b0 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
1b9c0 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
1b9d0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
1b9e0 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
1b9f0 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
1ba00 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
1ba10 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1ba20 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
1ba30 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
1ba40 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
1ba50 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
1ba60 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
1ba70 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
1ba80 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
1ba90 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
1baa0 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
1bab0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1bac0 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
1bad0 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
1bae0 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
1baf0 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
1bb00 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
1bb10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1bb20 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
1bb30 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
1bb40 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
1bb50 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1bb60 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
1bb70 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
1bb80 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
1bb90 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
1bba0 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
1bbb0 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
1bbc0 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
1bbd0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1bbe0 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
1bbf0 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
1bc00 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
1bc10 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
1bc20 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
1bc30 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
1bc40 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70  "%w" and "%z" op
1bc50 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
1bc60 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
1bc70 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
1bc80 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
1bc90 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  s a nul-terminat
1bca0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
1bcb0 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
1bcc0 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
1bcd0 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
1bce0 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
1bcf0 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
1bd00 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
1bd10 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1bd20 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
1bd30 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
1bd40 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
1bd50 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
1bd60 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
1bd70 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
1bd80 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
1bd90 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
1bda0 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
1bdb0 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
1bdc0 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
1bdd0 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
1bde0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1bdf0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1be00 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
1be10 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
1be20 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1be30 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
1be40 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
1be50 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
1be60 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
1be70 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1be80 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1be90 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1bea0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1beb0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1bec0 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
1bed0 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1bee0 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1bef0 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1bf00 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1bf10 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1bf20 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1bf30 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
1bf40 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
1bf50 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
1bf60 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
1bf70 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
1bf80 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
1bf90 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
1bfa0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1bfb0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1bfc0 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1bfd0 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1bfe0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1bff0 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
1c000 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1c010 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
1c020 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
1c030 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
1c040 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
1c050 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
1c060 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
1c070 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1c080 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1c090 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1c0a0 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
1c0b0 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
1c0c0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1c0d0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
1c0e0 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
1c0f0 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
1c100 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
1c110 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
1c120 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
1c130 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
1c140 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
1c150 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
1c160 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
1c170 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
1c180 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1c190 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
1c1a0 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
1c1b0 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
1c1c0 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
1c1d0 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
1c1e0 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
1c1f0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
1c200 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
1c210 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
1c220 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
1c230 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
1c240 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
1c250 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
1c260 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
1c270 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
1c280 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
1c290 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1c2a0 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1c2b0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1c2c0 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1c2d0 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
1c2e0 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1c2f0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1c300 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1c310 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1c320 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1c330 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1c340 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
1c350 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
1c360 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
1c370 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
1c380 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
1c390 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
1c3a0 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
1c3b0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1c3c0 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72  * ^(The "%w" for
1c3d0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69  matting option i
1c3e0 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65  s like "%q" exce
1c3f0 70 74 20 74 68 61 74 20 69 74 20 65 78 70 65 63  pt that it expec
1c400 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74  ts to.** be cont
1c410 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75  ained within dou
1c420 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65  ble-quotes inste
1c430 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f  ad of single quo
1c440 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65  tes, and it.** e
1c450 73 63 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c  scapes the doubl
1c460 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74 65  e-quote characte
1c470 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
1c480 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a   single-quote.**
1c490 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54   character.)^  T
1c4a0 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69  he "%w" formatti
1c4b0 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74  ng option is int
1c4c0 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79  ended for safely
1c4d0 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61   inserting.** ta
1c4e0 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e  ble and column n
1c4f0 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73  ames into a cons
1c500 74 72 75 63 74 65 64 20 53 51 4c 20 73 74 61 74  tructed SQL stat
1c510 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ement..**.** ^(T
1c520 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
1c530 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
1c540 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
1c550 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
1c560 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
1c570 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
1c580 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
1c590 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
1c5a0 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
1c5b0 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
1c5c0 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
1c5d0 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20  ring.)^.*/.char 
1c5e0 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
1c5f0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
1c600 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1c610 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
1c620 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1c630 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
1c640 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1c650 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
1c660 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1c670 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
1c680 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1c690 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
1c6a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1c6b0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
1c6c0 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
1c6d0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
1c6e0 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
1c6f0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
1c700 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
1c710 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
1c720 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
1c730 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
1c740 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
1c750 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
1c760 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
1c770 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
1c780 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1c790 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
1c7a0 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
1c7b0 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
1c7c0 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
1c7d0 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
1c7e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1c7f0 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
1c800 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1c810 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
1c820 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
1c830 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1c840 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
1c850 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
1c860 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1c870 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
1c880 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
1c890 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
1c8a0 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
1c8b0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1c8c0 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
1c8d0 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
1c8e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1c8f0 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
1c900 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
1c910 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
1c920 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1c930 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
1c940 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
1c950 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b  (N) routine work
1c960 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73  s just like.** s
1c970 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1c980 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
1c990 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34  s an unsigned 64
1c9a0 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73  -bit integer ins
1c9b0 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67  tead.** of a sig
1c9c0 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67  ned 32-bit integ
1c9d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
1c9e0 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
1c9f0 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
1ca00 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
1ca10 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1ca20 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1ca30 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1ca40 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
1ca50 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
1ca60 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
1ca70 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
1ca80 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
1ca90 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
1caa0 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
1cab0 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
1cac0 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
1cad0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
1cae0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1caf0 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
1cb00 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
1cb10 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
1cb20 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
1cb30 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
1cb40 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
1cb50 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
1cb60 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
1cb70 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
1cb80 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
1cb90 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1cba0 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
1cbb0 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
1cbc0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
1cbd0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1cbe0 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
1cbf0 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
1cc00 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
1cc10 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
1cc20 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
1cc30 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
1cc40 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1cc50 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1cc60 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1cc70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1cc80 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e  _realloc(X,N) in
1cc90 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
1cca0 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
1ccb0 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
1ccc0 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  ocation X to be 
1ccd0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1cce0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70  ..** ^If the X p
1ccf0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1cd00 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1cd10 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
1cd20 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
1cd30 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
1cd40 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
1cd50 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1cd60 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  c(N)..** ^If the
1cd70 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   N parameter to 
1cd80 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1cd90 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  X,N) is zero or.
1cda0 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
1cdb0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1cdc0 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
1cdd0 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
1cde0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e  sqlite3_free(X).
1cdf0 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
1ce00 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1ce10 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1ce20 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1ce30 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
1ce40 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
1ce50 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73  e or NULL if ins
1ce60 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
1ce70 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
1ce80 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73  * ^If M is the s
1ce90 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
1cea0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
1ceb0 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
1cec0 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
1ced0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
1cee0 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
1cef0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
1cf00 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
1cf10 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
1cf20 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20  oc(X,N) and the 
1cf30 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1cf40 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
1cf50 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
1cf60 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e  c(X,N) returns N
1cf70 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73  ULL and N is pos
1cf80 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a  itive, then the.
1cf90 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  ** prior allocat
1cfa0 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64  ion is not freed
1cfb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1cfc0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58  ite3_realloc64(X
1cfd0 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77  ,N) interfaces w
1cfe0 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73  orks the same as
1cff0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  .** sqlite3_real
1d000 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20  loc(X,N) except 
1d010 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62  that N is a 64-b
1d020 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
1d030 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ger instead.** o
1d040 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65  f a 32-bit signe
1d050 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  d integer..**.**
1d060 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f   ^If X is a memo
1d070 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72  ry allocation pr
1d080 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
1d090 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1d0a0 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
1d0b0 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
1d0c0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1d0d0 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ), or sqlite3_re
1d0e0 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a  alloc64(), then.
1d0f0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
1d100 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (X) returns the 
1d110 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d  size of that mem
1d120 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ory allocation i
1d130 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65  n bytes..** ^The
1d140 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1d150 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  by sqlite3_msize
1d160 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72  (X) might be lar
1d170 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d  ger than the num
1d180 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20  ber.** of bytes 
1d190 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58  requested when X
1d1a0 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20   was allocated. 
1d1b0 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c   ^If X is a NULL
1d1c0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a   pointer then.**
1d1d0 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1d1e0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20  ) returns zero. 
1d1f0 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20   If X points to 
1d200 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69  something that i
1d210 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67  s not.** the beg
1d220 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79  inning of memory
1d230 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20   allocation, or 
1d240 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20  if it points to 
1d250 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61  a formerly.** va
1d260 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  lid memory alloc
1d270 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e  ation that has n
1d280 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74  ow been freed, t
1d290 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1d2a0 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d  .** of sqlite3_m
1d2b0 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66  size(X) is undef
1d2c0 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c  ined and possibl
1d2d0 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
1d2e0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
1d2f0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1d300 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74  _malloc(), sqlit
1d310 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a  e3_realloc(),.**
1d320 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1d330 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  4(), and sqlite3
1d340 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20  _realloc64().** 
1d350 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
1d360 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
1d370 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
1d380 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62  , or to a.** 4 b
1d390 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20  yte boundary if 
1d3a0 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59  the [SQLITE_4_BY
1d3b0 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f  TE_ALIGNED_MALLO
1d3c0 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  C] compile-time.
1d3d0 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ** option is use
1d3e0 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69  d..**.** In SQLi
1d3f0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
1d400 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77   and 3.5.1, it w
1d410 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64  as possible to d
1d420 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c  efine.** the SQL
1d430 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f  ITE_OMIT_MEMORY_
1d440 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68  ALLOCATION which
1d450 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65   would cause the
1d460 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70   built-in.** imp
1d470 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
1d480 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  hese routines to
1d490 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68   be omitted.  Th
1d4a0 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  at capability.**
1d4b0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72   is no longer pr
1d4c0 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75  ovided.  Only bu
1d4d0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1d4e0 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20  locators can be 
1d4f0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  used..**.** Prio
1d500 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
1d510 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20  ion 3.7.10, the 
1d520 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  Windows OS inter
1d530 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65  face layer calle
1d540 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  d.** the system 
1d550 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1d560 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
1d570 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
1d580 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
1d590 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
1d5a0 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
1d5b0 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
1d5c0 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
1d5d0 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
1d5e0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1d5f0 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
1d600 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
1d610 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
1d620 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64  rs were detected
1d630 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65  , but.** they we
1d640 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
1d650 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
1d660 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
1d670 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
1d680 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
1d690 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  OMEM]..**.** The
1d6a0 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
1d6b0 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
1d6c0 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
1d6d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
1d6e0 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
1d6f0 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
1d700 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
1d710 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
1d720 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
1d730 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1d740 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1d750 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
1d760 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
1d770 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
1d780 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1d790 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
1d7a0 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
1d7b0 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
1d7c0 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
1d7d0 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
1d7e0 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
1d7f0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
1d800 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1d810 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  oc()]..*/.void *
1d820 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
1d830 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
1d840 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69  e3_malloc64(sqli
1d850 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69  te3_uint64);.voi
1d860 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
1d870 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
1d880 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
1d890 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73  alloc64(void*, s
1d8a0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
1d8b0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
1d8c0 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65  e(void*);.sqlite
1d8d0 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  3_uint64 sqlite3
1d8e0 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a  _msize(void*);..
1d8f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d900 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
1d910 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
1d920 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
1d930 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
1d940 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
1d950 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
1d960 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
1d970 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1d980 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1d990 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
1d9a0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
1d9b0 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
1d9c0 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
1d9d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1d9e0 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
1d9f0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1da00 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1da10 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1da20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1da30 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
1da40 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
1da50 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
1da60 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
1da70 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1da80 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1da90 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
1daa0 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
1dab0 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
1dac0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1dad0 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
1dae0 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1daf0 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
1db00 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
1db10 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1db20 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1db30 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
1db40 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1db50 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
1db60 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
1db70 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
1db80 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
1db90 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1dba0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
1dbb0 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
1dbc0 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
1dbd0 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
1dbe0 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
1dbf0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
1dc00 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1dc10 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
1dc20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
1dc30 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
1dc40 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
1dc50 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
1dc60 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1dc70 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
1dc80 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
1dc90 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
1dca0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1dcb0 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
1dcc0 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
1dcd0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
1dce0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1dcf0 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
1dd00 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1dd10 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
1dd20 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74   reset..*/.sqlit
1dd30 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1dd40 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
1dd50 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  d);.sqlite3_int6
1dd60 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1dd70 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
1dd80 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
1dd90 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
1dda0 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
1ddb0 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
1ddc0 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
1ddd0 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
1dde0 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
1ddf0 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
1de00 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
1de10 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
1de20 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
1de30 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
1de40 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
1de50 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
1de60 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
1de70 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
1de80 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
1de90 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
1dea0 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
1deb0 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
1dec0 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
1ded0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
1dee0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
1def0 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
1df00 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
1df10 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
1df20 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
1df30 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
1df40 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
1df50 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
1df60 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
1df70 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e  o buffer P..** ^
1df80 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20  The P parameter 
1df90 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  can be a NULL po
1dfa0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  inter..**.** ^If
1dfb0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
1dfc0 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69  s not been previ
1dfd0 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20  ously called or 
1dfe0 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a  if the previous.
1dff0 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65  ** call had N le
1e000 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61  ss than one or a
1e010 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
1e020 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52  r P, then the PR
1e030 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20  NG is.** seeded 
1e040 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
1e050 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74   obtained from t
1e060 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
1e070 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20  ethod of.** the 
1e080 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1e090 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
1e0a0 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75   ^If the previou
1e0b0 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  s call to this r
1e0c0 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20  outine had an N 
1e0d0 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64  of 1 or more and
1e0e0 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50   a.** non-NULL P
1e0f0 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f   then the pseudo
1e100 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
1e110 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
1e120 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
1e130 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
1e140 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
1e150 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
1e160 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20  method..*/.void 
1e170 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
1e180 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
1e190 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
1e1a0 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
1e1b0 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
1e1c0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
1e1d0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
1e1e0 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f  gisters an autho
1e1f0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
1e200 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
1e210 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1e220 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
1e230 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
1e240 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
1e250 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1e260 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1e270 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
1e280 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
1e290 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
1e2a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1e2b0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1e2c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e2d0 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
1e2e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1e2f0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
1e300 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
1e310 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20   ^At various.** 
1e320 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
1e330 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
1e340 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
1e350 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
1e360 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
1e370 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
1e380 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1e390 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1e3a0 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
1e3b0 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
1e3c0 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65  e allowed.  ^The
1e3d0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1e3e0 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
1e3f0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
1e400 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  ] to allow the a
1e410 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
1e420 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
1e430 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
1e440 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
1e450 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
1e460 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
1e470 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
1e480 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
1e490 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
1e4a0 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
1e4b0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
1e4c0 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
1e4d0 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68  n error.  ^If th
1e4e0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1e4f0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
1e500 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
1e510 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
1e520 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
1e530 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
1e540 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
1e550 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e560 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
1e570 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
1e580 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
1e590 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
1e5a0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
1e5b0 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
1e5c0 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
1e5d0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1e5e0 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
1e5f0 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
1e600 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
1e610 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68  is ok.  ^When th
1e620 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1e630 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
1e640 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
1e650 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1e660 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
1e670 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
1e680 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
1e690 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
1e6a0 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
1e6b0 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
1e6c0 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
1e6d0 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20   denied. .**.** 
1e6e0 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
1e6f0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1e700 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1e710 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
1e720 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
1e730 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
1e740 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1e750 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e  r() interface. ^
1e760 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1e770 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63  eter.** to the c
1e780 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1e790 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f  teger [SQLITE_CO
1e7a0 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65  PY | action code
1e7b0 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
1e7c0 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c  .** the particul
1e7d0 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  ar action to be 
1e7e0 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65  authorized. ^The
1e7f0 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
1e800 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
1e810 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1e820 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
1e830 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1e840 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
1e850 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
1e860 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
1e870 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
1e880 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  zed..**.** ^If t
1e890 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
1e8a0 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a  s [SQLITE_READ].
1e8b0 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  ** and the callb
1e8c0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1e8d0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
1e8e0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
1e8f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61  d statement] sta
1e900 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
1e910 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74  ucted to substit
1e920 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61  ute.** a NULL va
1e930 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
1e940 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
1e950 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
1e960 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66  .** been read if
1e970 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
1e980 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20   been returned. 
1e990 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   The [SQLITE_IGN
1e9a0 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63  ORE].** return c
1e9b0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
1e9c0 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  ny an untrusted 
1e9d0 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69  user access to i
1e9e0 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c  ndividual.** col
1e9f0 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e  umns of a table.
1ea00 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
1ea10 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
1ea20 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
1ea30 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1ea40 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
1ea50 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
1ea60 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
1ea70 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
1ea80 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
1ea90 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
1eaa0 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
1eab0 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
1eac0 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
1ead0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
1eae0 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
1eaf0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
1eb00 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
1eb10 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1eb20 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
1eb30 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
1eb40 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
1eb50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1eb60 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
1eb70 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
1eb80 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
1eb90 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
1eba0 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
1ebb0 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
1ebc0 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
1ebd0 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
1ebe0 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
1ebf0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
1ec00 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
1ec10 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
1ec20 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
1ec30 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
1ec40 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
1ec50 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
1ec60 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
1ec70 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
1ec80 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
1ec90 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
1eca0 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
1ecb0 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
1ecc0 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
1ecd0 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
1ece0 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
1ecf0 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
1ed00 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
1ed10 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
1ed20 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
1ed30 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
1ed40 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
1ed50 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
1ed60 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
1ed70 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
1ed80 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
1ed90 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
1eda0 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
1edb0 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
1edc0 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
1edd0 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
1ede0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1edf0 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
1ee00 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
1ee10 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
1ee20 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
1ee30 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
1ee40 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
1ee50 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
1ee60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61  ..**.** ^(Only a
1ee70 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
1ee80 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
1ee90 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
1eea0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
1eeb0 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
1eec0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
1eed0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
1eee0 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
1eef0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e  previous call.)^
1ef00 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61    ^Disable the a
1ef10 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
1ef20 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
1ef30 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
1ef40 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
1ef50 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
1ef60 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
1ef70 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ef80 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
1ef90 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
1efa0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
1efb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1efc0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1efd0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1efe0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
1eff0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
1f000 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1f010 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1f020 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
1f030 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
1f040 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
1f050 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
1f060 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
1f070 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
1f080 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ^When [sqlite3_p
1f090 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
1f0a0 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
1f0b0 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
1f0c0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
1f0d0 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72  ght be re-prepar
1f0e0 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
1f0f0 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
1f100 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
1f110 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
1f120 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
1f130 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
1f140 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
1f150 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1f160 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
1f170 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
1f180 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1f190 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  ]..**.** ^Note t
1f1a0 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
1f1b0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1f1c0 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
1f1d0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
1f1e0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
1f1f0 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
1f200 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
1f210 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
1f220 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
1f230 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
1f240 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75  lite3_step()], u
1f250 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74  nless.** as stat
1f260 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ed in the previo
1f270 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71  us paragraph, sq
1f280 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76  lite3_step() inv
1f290 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  okes.** sqlite3_
1f2a0 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20  prepare_v2() to 
1f2b0 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74  reprepare a stat
1f2c0 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63  ement after a sc
1f2d0 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  hema change..*/.
1f2e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
1f2f0 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
1f300 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
1f310 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
1f320 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1f330 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
1f340 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1f350 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
1f360 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
1f370 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
1f380 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
1f390 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
1f3a0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1f3b0 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
1f3c0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1f3d0 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
1f3e0 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
1f3f0 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
1f400 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
1f410 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
1f420 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
1f430 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1f440 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
1f450 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
1f460 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
1f470 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
1f480 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
1f490 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
1f4a0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
1f4b0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ation..**.** Not
1f4c0 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47  e that SQLITE_IG
1f4d0 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65  NORE is also use
1f4e0 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74  d as a [conflict
1f4f0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65   resolution mode
1f500 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72  ].** returned fr
1f510 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
1f520 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74  vtab_on_conflict
1f530 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
1f540 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f550 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
1f560 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
1f570 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
1f580 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
1f590 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
1f5a0 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
1f5b0 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
1f5c0 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
1f5d0 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
1f5e0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
1f5f0 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
1f600 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
1f610 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1f620 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
1f630 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
1f640 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
1f650 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
1f660 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
1f670 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
1f680 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
1f690 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
1f6a0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
1f6b0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
1f6c0 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
1f6d0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
1f6e0 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
1f6f0 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
1f700 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
1f710 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
1f720 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
1f730 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1f740 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
1f750 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
1f760 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
1f770 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
1f780 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
1f790 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
1f7a0 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
1f7b0 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
1f7c0 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1f7d0 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
1f7e0 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
1f7f0 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
1f800 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
1f810 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
1f820 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
1f830 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1f840 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54   parameter.  ^(T
1f850 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
1f860 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
1f870 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1f880 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1f890 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
1f8a0 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
1f8b0 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
1f8c0 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20  le.)^  ^The 6th 
1f8d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1f8e0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1f8f0 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
1f900 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
1f910 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
1f920 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
1f930 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
1f940 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
1f950 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
1f960 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
1f970 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
1f980 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
1f990 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
1f9a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f9b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f9c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
1f9d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
1f9e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
1f9f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1fa00 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
1fa10 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
1fa20 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1fa30 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1fa40 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1fa50 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
1fa60 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
1fa70 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1fa80 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1fa90 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1faa0 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
1fab0 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
1fac0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1fad0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1fae0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1faf0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
1fb00 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1fb10 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1fb20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1fb30 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1fb40 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
1fb50 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1fb60 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1fb70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1fb80 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1fb90 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
1fba0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1fbb0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1fbc0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1fbd0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
1fbe0 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
1fbf0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1fc00 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1fc10 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1fc20 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
1fc30 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
1fc40 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1fc50 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1fc60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1fc70 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
1fc80 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
1fc90 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1fca0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1fcb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1fcc0 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
1fcd0 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
1fce0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1fcf0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1fd00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1fd10 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
1fd20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
1fd30 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1fd40 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1fd50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1fd60 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
1fd70 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
1fd80 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1fd90 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1fda0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1fdb0 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
1fdc0 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
1fdd0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1fde0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1fdf0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1fe00 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
1fe10 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
1fe20 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1fe30 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1fe40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1fe50 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
1fe60 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
1fe70 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1fe80 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1fe90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1fea0 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
1feb0 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
1fec0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1fed0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1fee0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1fef0 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
1ff00 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
1ff10 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1ff20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1ff30 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
1ff40 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
1ff50 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
1ff60 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1ff70 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1ff80 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
1ff90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
1ffa0 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
1ffb0 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
1ffc0 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
1ffd0 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
1ffe0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
1fff0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
20000 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
20010 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
20020 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
20030 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
20040 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
20050 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20060 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20070 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
20080 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
20090 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
200a0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
200b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
200c0 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
200d0 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
200e0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
200f0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
20100 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20110 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
20120 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
20130 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
20140 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20150 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20160 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
20170 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
20180 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
20190 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
201a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
201b0 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
201c0 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
201d0 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
201e0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
201f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20200 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
20210 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
20220 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
20230 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
20240 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20250 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
20260 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
20270 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
20280 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20290 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
202a0 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
202b0 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
202c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
202d0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
202e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
202f0 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
20300 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
20310 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
20320 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
20330 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
20340 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
20350 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
20360 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
20370 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
20380 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
20390 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
203a0 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
203b0 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
203c0 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
203d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
203e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
203f0 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
20400 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69  er used */.#defi
20410 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53  ne SQLITE_RECURS
20420 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33  IVE            3
20430 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  3   /* NULL     
20440 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
20450 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a         */../*.**
20460 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
20470 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
20480 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
20490 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
204a0 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
204b0 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  k functions that
204c0 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72   can be used for
204d0 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20  .** tracing and 
204e0 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78  profiling the ex
204f0 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73  ecution of SQL s
20500 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
20510 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
20520 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
20530 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
20540 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
20550 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74   at.** various t
20560 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c  imes when an SQL
20570 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65   statement is be
20580 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69  ing run by [sqli
20590 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
205a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61  ^The sqlite3_tra
205b0 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ce() callback is
205c0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
205d0 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20  UTF-8 rendering 
205e0 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74  of the.** SQL st
205f0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20  atement text as 
20600 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
20610 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75  rst begins execu
20620 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74  ting..** ^(Addit
20630 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72  ional sqlite3_tr
20640 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20  ace() callbacks 
20650 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61  might occur.** a
20660 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64  s each triggered
20670 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65   subprogram is e
20680 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c  ntered.  The cal
20690 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67  lbacks for trigg
206a0 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61  ers.** contain a
206b0 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65   UTF-8 SQL comme
206c0 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  nt that identifi
206d0 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29  es the trigger.)
206e0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ^.**.** The [SQL
206f0 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c  ITE_TRACE_SIZE_L
20700 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  IMIT] compile-ti
20710 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  me option can be
20720 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a   used to limit.*
20730 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  * the length of 
20740 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  [bound parameter
20750 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74  ] expansion in t
20760 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c  he output of sql
20770 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a  ite3_trace()..**
20780 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
20790 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
207a0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
207b0 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
207c0 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
207d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
207e0 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70  inishes.  ^The p
207f0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
20800 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
20810 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
20820 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
20830 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
20840 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
20850 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
20860 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
20870 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66   run.  ^The prof
20880 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ile callback.** 
20890 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73  time is in units
208a0 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c   of nanoseconds,
208b0 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72   however the cur
208c0 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
208d0 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63  ion.** is only c
208e0 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73  apable of millis
208f0 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e  econd resolution
20900 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73   so the six leas
20910 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a  t significant.**
20920 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74   digits in the t
20930 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c  ime are meaningl
20940 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72  ess.  Future ver
20950 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a  sions of SQLite.
20960 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65  ** might provide
20970 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74   greater resolut
20980 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69  ion on the profi
20990 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54  ler callback.  T
209a0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  he.** sqlite3_pr
209b0 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  ofile() function
209c0 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65   is considered e
209d0 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
209e0 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f  is.** subject to
209f0 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
20a00 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
20a10 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  Lite..*/.void *s
20a20 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
20a30 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
20a40 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
20a50 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
20a60 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
20a70 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74  NTAL void *sqlit
20a80 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
20a90 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
20aa0 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
20ab0 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
20ac0 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
20ad0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20ae0 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
20af0 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  ss Callbacks.**.
20b00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
20b10 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
20b20 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,N,X,P) interf
20b30 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63  ace causes the c
20b40 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
20b50 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f  ion X to be invo
20b60 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
20b70 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
20b80 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
20b90 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
20ba0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
20bb0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
20bc0 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f  _get_table()] fo
20bd0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
20be0 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20  nnection D.  An 
20bf0 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
20c00 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
20c10 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
20c20 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
20c30 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
20c40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61  .**.** ^The para
20c50 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65  meter P is passe
20c60 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
20c70 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
20c80 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62  to the .** callb
20c90 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20  ack function X. 
20ca0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
20cb0 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69  N is the approxi
20cc0 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a  mate number of .
20cd0 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68  ** [virtual mach
20ce0 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73  ine instructions
20cf0 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75  ] that are evalu
20d00 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63  ated between suc
20d10 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63  cessive.** invoc
20d20 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61  ations of the ca
20d30 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e  llback X.  ^If N
20d40 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e   is less than on
20d50 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72  e then the progr
20d60 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69  ess.** handler i
20d70 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  s disabled..**.*
20d80 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  * ^Only a single
20d90 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
20da0 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64  r may be defined
20db0 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72   at one time per
20dc0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
20dd0 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69  nnection]; setti
20de0 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73  ng a new progres
20df0 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c  s handler cancel
20e00 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65  s the.** old one
20e10 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61  .  ^Setting para
20e20 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20  meter X to NULL 
20e30 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f  disables the pro
20e40 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
20e50 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20  * ^The progress 
20e60 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20  handler is also 
20e70 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74  disabled by sett
20e80 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65  ing N to a value
20e90 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e   less.** than 1.
20ea0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  .**.** ^If the p
20eb0 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
20ec0 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
20ed0 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  o, the operation
20ee0 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
20ef0 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
20f00 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
20f10 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
20f20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
20f30 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73  on a GUI progres
20f40 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  s dialog box..**
20f50 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
20f60 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
20f70 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
20f80 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
20f90 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
20fa0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20fb0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
20fc0 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
20fd0 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
20fe0 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
20ff0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
21000 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
21010 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
21020 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
21030 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
21040 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
21050 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
21060 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f  agraph..**.*/.vo
21070 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
21080 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
21090 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
210a0 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
210b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
210c0 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
210d0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
210e0 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  tion.**.** ^Thes
210f0 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20  e routines open 
21100 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
21110 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69  se file as speci
21120 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
21130 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
21140 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65  t. ^The filename
21150 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74   argument is int
21160 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d  erpreted as UTF-
21170 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  8 for.** sqlite3
21180 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
21190 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e  te3_open_v2() an
211a0 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74  d as UTF-16 in t
211b0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a  he native byte.*
211c0 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  * order for sqli
211d0 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28  te3_open16(). ^(
211e0 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  A [database conn
211f0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69  ection] handle i
21200 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74  s usually.** ret
21210 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20  urned in *ppDb, 
21220 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72  even if an error
21230 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e   occurs.  The on
21240 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20  ly exception is 
21250 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74  that.** if SQLit
21260 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  e is unable to a
21270 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74  llocate memory t
21280 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69  o hold the [sqli
21290 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20  te3] object,.** 
212a0 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77  a NULL will be w
212b0 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44  ritten into *ppD
212c0 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70  b instead of a p
212d0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
212e0 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63  qlite3].** objec
212f0 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61  t.)^ ^(If the da
21300 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
21310 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64   (and/or created
21320 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20  ) successfully, 
21330 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  then.** [SQLITE_
21340 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  OK] is returned.
21350 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b    Otherwise an [
21360 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
21370 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a  eturned.)^ ^The.
21380 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
21390 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  sg()] or [sqlite
213a0 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f  3_errmsg16()] ro
213b0 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73  utines can be us
213c0 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20  ed to obtain.** 
213d0 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75  an English langu
213e0 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20  age description 
213f0 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c  of the error fol
21400 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65  lowing a failure
21410 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
21420 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  e sqlite3_open()
21430 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
21440 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
21450 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55  coding will be U
21460 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73  TF-8 for databas
21470 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  es created using
21480 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
21490 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
214a0 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64  en_v2().  ^The d
214b0 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20  efault encoding 
214c0 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a  for databases.**
214d0 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 73   created using s
214e0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20  qlite3_open16() 
214f0 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69  will be UTF-16 i
21500 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
21510 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57  e order..**.** W
21520 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e  hether or not an
21530 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
21540 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c  en it is opened,
21550 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73   resources.** as
21560 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
21570 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
21580 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73  ection] handle s
21590 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65  hould be release
215a0 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20  d by.** passing 
215b0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
215c0 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20  lose()] when it 
215d0 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71  is no longer req
215e0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  uired..**.** The
215f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21600 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72  () interface wor
21610 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f  ks like sqlite3_
21620 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74  open().** except
21630 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73   that it accepts
21640 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
21650 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61  parameters for a
21660 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f  dditional contro
21670 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65  l.** over the ne
21680 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
21690 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c  ction.  ^(The fl
216a0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
216b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
216c0 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f  _v2() can take o
216d0 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c  ne of.** the fol
216e0 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c  lowing three val
216f0 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  ues, optionally 
21700 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68  combined with th
21710 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  e .** [SQLITE_OP
21720 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51  EN_NOMUTEX], [SQ
21730 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
21740 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
21750 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c  EN_SHAREDCACHE],
21760 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
21770 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20  _PRIVATECACHE], 
21780 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  and/or [SQLITE_O
21790 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29  PEN_URI] flags:)
217a0 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ^.**.** <dl>.** 
217b0 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
217c0 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74  EN_READONLY]</dt
217d0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
217e0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
217f0 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64  in read-only mod
21800 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62  e.  If the datab
21810 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  ase does not.** 
21820 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61  already exist, a
21830 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  n error is retur
21840 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ned.</dd>)^.**.*
21850 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f  * ^(<dt>[SQLITE_
21860 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c  OPEN_READWRITE]<
21870 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
21880 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
21890 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
218a0 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f  nd writing if po
218b0 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69  ssible, or readi
218c0 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68  ng.** only if th
218d0 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20  e file is write 
218e0 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65  protected by the
218f0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
21900 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a  m.  In either.**
21910 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61   case the databa
21920 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20  se must already 
21930 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65  exist, otherwise
21940 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74   an error is ret
21950 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  urned.</dd>)^.**
21960 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
21970 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
21980 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
21990 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  _CREATE]</dt>.**
219a0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
219b0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
219c0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
219d0 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61  ing, and is crea
219e0 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65  ted if.** it doe
219f0 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78  s not already ex
21a00 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65  ist. This is the
21a10 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69   behavior that i
21a20 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f  s always used fo
21a30 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
21a40 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
21a50 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e  open16().</dd>)^
21a60 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </dl>.**.** 
21a70 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
21a80 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
21a90 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  open_v2() is not
21aa0 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63   one of the.** c
21ab0 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77  ombinations show
21ac0 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c  n above optional
21ad0 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
21ae0 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54   other.** [SQLIT
21af0 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
21b00 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20  | SQLITE_OPEN_* 
21b10 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  bits].** then th
21b20 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
21b30 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
21b40 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  If the [SQLITE_O
21b50 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61  PEN_NOMUTEX] fla
21b60 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74  g is set, then t
21b70 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
21b80 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20  ection.** opens 
21b90 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72  in the multi-thr
21ba0 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
21bb0 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20  ode] as long as 
21bc0 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61  the single-threa
21bd0 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f  d.** mode has no
21be0 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f  t been set at co
21bf0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
21c00 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74  art-time.  ^If t
21c10 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
21c20 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c  EN_FULLMUTEX] fl
21c30 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74  ag is set then t
21c40 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
21c50 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20  ection opens.** 
21c60 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  in the serialize
21c70 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
21c80 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65  e] unless single
21c90 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70  -thread was.** p
21ca0 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74  reviously select
21cb0 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  ed at compile-ti
21cc0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
21cd0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
21ce0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
21cf0 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20  HE] flag causes 
21d00 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
21d10 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  nection to be.**
21d20 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65   eligible to use
21d30 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d   [shared cache m
21d40 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73  ode], regardless
21d50 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
21d60 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  ot shared.** cac
21d70 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73  he is enabled us
21d80 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  ing [sqlite3_ena
21d90 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65  ble_shared_cache
21da0 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53  ()].  ^The.** [S
21db0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
21dc0 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  TECACHE] flag ca
21dd0 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
21de0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
21df0 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61  not.** participa
21e00 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61  te in [shared ca
21e10 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69  che mode] even i
21e20 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e  f it is enabled.
21e30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
21e40 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
21e50 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21e60 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ) is the name of
21e70 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
21e80 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  _vfs] object tha
21e90 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70  t defines the op
21ea0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
21eb0 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a  nterface that.**
21ec0 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
21ed0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
21ee0 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68  uld use.  ^If th
21ef0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
21f00 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  er is.** a NULL 
21f10 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
21f20 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
21f30 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
21f40 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   used..**.** ^If
21f50 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
21f60 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65   ":memory:", the
21f70 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
21f80 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79  porary in-memory
21f90 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
21fa0 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20  created for the 
21fb0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68  connection.  ^Th
21fc0 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  is in-memory dat
21fd0 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73  abase will vanis
21fe0 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61  h when.** the da
21ff0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22000 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75  n is closed.  Fu
22010 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
22020 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a   SQLite might.**
22030 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64   make use of add
22040 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20  itional special 
22050 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62  filenames that b
22060 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a  egin with the ":
22070 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  " character..** 
22080 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  It is recommende
22090 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61  d that when a da
220a0 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
220b0 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65  actually does be
220c0 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a  gin with.** a ":
220d0 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20  " character you 
220e0 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68  should prefix th
220f0 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20  e filename with 
22100 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20  a pathname such 
22110 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76  as.** "./" to av
22120 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a  oid ambiguity..*
22130 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
22140 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74  ename is an empt
22150 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61  y string, then a
22160 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
22170 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64  ary.** on-disk d
22180 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20  atabase will be 
22190 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20  created.  ^This 
221a0 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65  private database
221b0 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f   will be.** auto
221c0 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
221d0 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65  d as soon as the
221e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
221f0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a  tion is closed..
22200 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
22210 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33  names in sqlite3
22220 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52  _open()]] <h3>UR
22230 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e  I Filenames</h3>
22240 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20  .**.** ^If [URI 
22250 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70  filename] interp
22260 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
22270 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c  led, and the fil
22280 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
22290 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66  * begins with "f
222a0 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20  ile:", then the 
222b0 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65  filename is inte
222c0 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49  rpreted as a URI
222d0 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61  . ^URI.** filena
222e0 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
222f0 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20  n is enabled if 
22300 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
22310 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a  _URI] flag is.**
22320 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72   set in the four
22330 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
22340 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
22350 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a  , or if it has.*
22360 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67  * been enabled g
22370 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68  lobally using th
22380 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  e [SQLITE_CONFIG
22390 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74  _URI] option wit
223a0 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  h the.** [sqlite
223b0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68  3_config()] meth
223c0 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51  od or by the [SQ
223d0 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f  LITE_USE_URI] co
223e0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
223f0 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69  n..** As of SQLi
22400 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37  te version 3.7.7
22410 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69  , URI filename i
22420 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
22430 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62   turned off.** b
22440 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66  y default, but f
22450 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
22460 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65  f SQLite might e
22470 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61  nable URI filena
22480 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61  me.** interpreta
22490 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e  tion by default.
224a0 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65    See "[URI file
224b0 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69  names]" for addi
224c0 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
224d0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49  ation..**.** URI
224e0 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70   filenames are p
224f0 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20  arsed according 
22500 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66  to RFC 3986. ^If
22510 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e   the URI contain
22520 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74  s an.** authorit
22530 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20  y, then it must 
22540 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70  be either an emp
22550 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65  ty string or the
22560 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63   string .** "loc
22570 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65  alhost". ^If the
22580 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f   authority is no
22590 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  t an empty strin
225a0 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22  g or "localhost"
225b0 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69  , an .** error i
225c0 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68  s returned to th
225d0 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66  e caller. ^The f
225e0 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e  ragment componen
225f0 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a  t of a URI, if .
22600 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69  ** present, is i
22610 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  gnored..**.** ^S
22620 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70  QLite uses the p
22630 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ath component of
22640 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20   the URI as the 
22650 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b  name of the disk
22660 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63   file.** which c
22670 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61  ontains the data
22680 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61  base. ^If the pa
22690 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  th begins with a
226a0 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20   '/' character, 
226b0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69  .** then it is i
226c0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e  nterpreted as an
226d0 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20   absolute path. 
226e0 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65  ^If the path doe
226f0 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20  s not begin .** 
22700 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e  with a '/' (mean
22710 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74  ing that the aut
22720 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69  hority section i
22730 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74  s omitted from t
22740 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20  he URI).** then 
22750 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65  the path is inte
22760 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c  rpreted as a rel
22770 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20  ative path. .** 
22780 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68  ^(On windows, th
22790 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e  e first componen
227a0 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65  t of an absolute
227b0 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64   path .** is a d
227c0 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69  rive specificati
227d0 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29  on (e.g. "C:").)
227e0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55  ^.**.** [[core U
227f0 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  RI query paramet
22800 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65  ers]].** The que
22810 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
22820 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69  a URI may contai
22830 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
22840 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  t are interprete
22850 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53  d.** either by S
22860 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72  QLite itself, or
22870 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73   by a [VFS | cus
22880 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  tom VFS implemen
22890 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69  tation]..** SQLi
228a0 74 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74  te and its built
228b0 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65  -in [VFSes] inte
228c0 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c  rpret the.** fol
228d0 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72  lowing query par
228e0 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ameters:.**.** <
228f0 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  ul>.**   <li> <b
22900 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22  >vfs</b>: ^The "
22910 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d  vfs" parameter m
22920 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70  ay be used to sp
22930 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f  ecify the name o
22940 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f  f.**     a VFS o
22950 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69  bject that provi
22960 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e  des the operatin
22970 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61  g system interfa
22980 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a  ce that should.*
22990 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f  *     be used to
229a0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
229b0 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73  base file on dis
229c0 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69  k. ^If this opti
229d0 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20  on is set to.** 
229e0 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72      an empty str
229f0 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20  ing the default 
22a00 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73  VFS object is us
22a10 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20  ed. ^Specifying 
22a20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20  an unknown.**   
22a30 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f    VFS is an erro
22a40 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f  r. ^If sqlite3_o
22a50 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
22a60 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74   and the vfs opt
22a70 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72  ion is.**     pr
22a80 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20  esent, then the 
22a90 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79  VFS specified by
22aa0 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65   the option take
22ab0 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65  s precedence ove
22ac0 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c  r.**     the val
22ad0 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
22ae0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
22af0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
22b00 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
22b10 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e  <li> <b>mode</b>
22b20 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72  : ^(The mode par
22b30 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
22b40 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22  t to either "ro"
22b50 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22  , "rw",.**     "
22b60 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79  rwc", or "memory
22b70 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f  ". Attempting to
22b80 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f   set it to any o
22b90 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a  ther value is.**
22ba0 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e       an error)^.
22bb0 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f   .**     ^If "ro
22bc0 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20  " is specified, 
22bd0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
22be0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
22bf0 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20  read-only .**   
22c00 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61    access, just a
22c10 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  s if the [SQLITE
22c20 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20  _OPEN_READONLY] 
22c30 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65  flag had been se
22c40 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20  t in the .**    
22c50 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
22c60 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
22c70 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f  v2(). ^If the mo
22c80 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  de option is set
22c90 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22   to .**     "rw"
22ca0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
22cb0 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f  ase is opened fo
22cc0 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75  r read-write (bu
22cd0 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a  t not create) .*
22ce0 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73  *     access, as
22cf0 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   if SQLITE_OPEN_
22d00 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e  READWRITE (but n
22d10 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ot SQLITE_OPEN_C
22d20 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20  REATE) had .**  
22d30 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61     been set. ^Va
22d40 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75  lue "rwc" is equ
22d50 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
22d60 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20  ng both .**     
22d70 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
22d80 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45  WRITE and SQLITE
22d90 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e  _OPEN_CREATE.  ^
22da0 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
22db0 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74  on is.**     set
22dc0 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65   to "memory" the
22dd0 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d  n a pure [in-mem
22de0 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68  ory database] th
22df0 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a  at never reads.*
22e00 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20  *     or writes 
22e10 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65  from disk is use
22e20 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72  d. ^It is an err
22e30 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20  or to specify a 
22e40 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20  value for.**    
22e50 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65   the mode parame
22e60 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73  ter that is less
22e70 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61   restrictive tha
22e80 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64  n that specified
22e90 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66   by.**     the f
22ea0 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74  lags passed in t
22eb0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
22ec0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
22ed0 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
22ee0 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f   <li> <b>cache</
22ef0 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70  b>: ^The cache p
22f00 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
22f10 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73  set to either "s
22f20 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20  hared" or.**    
22f30 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74   "private". ^Set
22f40 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72  ting it to "shar
22f50 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e  ed" is equivalen
22f60 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
22f70 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
22f80 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
22f90 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73  bit in the flags
22fa0 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
22fb0 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74   to.**     sqlit
22fc0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53  e3_open_v2(). ^S
22fd0 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65  etting the cache
22fe0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70   parameter to "p
22ff0 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20  rivate" is .**  
23000 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f     equivalent to
23010 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c   setting the SQL
23020 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
23030 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20  CACHE bit..**   
23040 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70    ^If sqlite3_op
23050 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
23060 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20  and the "cache" 
23070 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65  parameter is pre
23080 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61  sent in.**     a
23090 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69   URI filename, i
230a0 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64  ts value overrid
230b0 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20  es any behavior 
230c0 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74  requested by set
230d0 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49  ting.**     SQLI
230e0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
230f0 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f  ACHE or SQLITE_O
23100 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
23110 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69  flag..**.**  <li
23120 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e  > <b>psow</b>: ^
23130 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74  The psow paramet
23140 65 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65  er indicates whe
23150 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a  ther or not the.
23160 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66  **     [powersaf
23170 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f  e overwrite] pro
23180 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f  perty does or do
23190 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20  es not apply to 
231a0 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61  the.**     stora
231b0 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63  ge media on whic
231c0 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  h the database f
231d0 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a  ile resides..**.
231e0 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f  **  <li> <b>nolo
231f0 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c  ck</b>: ^The nol
23200 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ock parameter is
23210 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
23220 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
23230 20 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64    which if set d
23240 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63  isables file loc
23250 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b  king in rollback
23260 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20   journal modes. 
23270 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20   This.**     is 
23280 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73  useful for acces
23290 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20  sing a database 
232a0 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20  on a filesystem 
232b0 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  that does not.**
232c0 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63       support loc
232d0 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20  king.  Caution: 
232e0 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   Database corrup
232f0 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c  tion might resul
23300 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20  t if two.**     
23310 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65  or more processe
23320 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73  s write to the s
23330 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  ame database and
23340 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73   any one of thos
23350 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73  e.**     process
23360 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31  es uses nolock=1
23370 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
23380 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20  >immutable</b>: 
23390 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70  ^The immutable p
233a0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f  arameter is a bo
233b0 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20  olean query.**  
233c0 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61     parameter tha
233d0 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  t indicates that
233e0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
233f0 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a  le is stored on.
23400 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79  **     read-only
23410 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69   media.  ^When i
23420 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c  mmutable is set,
23430 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
23440 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20  that the.**     
23450 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61  database file ca
23460 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c  nnot be changed,
23470 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65   even by a proce
23480 73 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a  ss with higher.*
23490 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c  *     privilege,
234a0 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61   and so the data
234b0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72  base is opened r
234c0 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c  ead-only and all
234d0 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20   locking.**     
234e0 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63  and change detec
234f0 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64  tion is disabled
23500 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74  .  Caution: Sett
23510 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c  ing the immutabl
23520 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74  e.**     propert
23530 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  y on a database 
23540 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69  file that does i
23550 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61  n fact change ca
23560 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20  n result.**     
23570 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65  in incorrect que
23580 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f  ry results and/o
23590 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  r [SQLITE_CORRUP
235a0 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20  T] errors..**   
235b0 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c    See also: [SQL
235c0 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
235d0 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a  BLE]..**       .
235e0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
235f0 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
23600 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20  known parameter 
23610 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d  in the query com
23620 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
23630 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72  is not an.** err
23640 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  or.  Future vers
23650 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
23660 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20  ight understand 
23670 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79  additional query
23680 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
23690 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72   See "[query par
236a0 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65  ameters with spe
236b0 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20  cial meaning to 
236c0 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20  SQLite]" for.** 
236d0 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
236e0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  mation..**.** [[
236f0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
23700 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20  mples]] <h3>URI 
23710 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
23720 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61  s</h3>.**.** <ta
23730 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61  ble border="1" a
23740 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c  lign=center cell
23750 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74  padding=5>.** <t
23760 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e  r><th> URI filen
23770 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74  ames <th> Result
23780 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  s.** <tr><td> fi
23790 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  le:data.db <td> 
237a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
237b0 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
237c0 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
237d0 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ent directory..*
237e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
237f0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
23800 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20  db<br>.**       
23810 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f     file:///home/
23820 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
23830 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
23840 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f  ile://localhost/
23850 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
23860 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20  b <br> <td> .** 
23870 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
23880 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
23890 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
238a0 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  .db"..** <tr><td
238b0 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61  > file://darksta
238c0 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  r/home/fred/data
238d0 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
238e0 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
238f0 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f  "darkstar" is no
23900 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61  t a recognized a
23910 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72  uthority..** <tr
23920 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74  ><td style="whit
23930 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e  e-space:nowrap">
23940 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
23950 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e  le:///C:/Documen
23960 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69  ts%20and%20Setti
23970 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70  ngs/fred/Desktop
23980 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20  /data.db.**     
23990 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c  <td> Windows onl
239a0 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65  y: Open the file
239b0 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72   "data.db" on fr
239c0 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20  ed's desktop on 
239d0 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  drive.**        
239e0 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20    C:. Note that 
239f0 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67  the %20 escaping
23a00 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65   in this example
23a10 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79   is not strictly
23a20 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65   .**          ne
23a30 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20  cessary - space 
23a40 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62  characters can b
23a50 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79  e used literally
23a60 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
23a70 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a  URI filenames..*
23a80 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
23a90 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26  data.db?mode=ro&
23aa0 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74  cache=private <t
23ab0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
23ac0 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e  Open file "data.
23ad0 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
23ae0 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72  nt directory for
23af0 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73   read-only acces
23b00 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52  s..**          R
23b10 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
23b20 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
23b30 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73  ed-cache mode is
23b40 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20   enabled by.**  
23b50 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c          default,
23b60 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63   use a private c
23b70 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ache..** <tr><td
23b80 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
23b90 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e  d/data.db?vfs=un
23ba0 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a  ix-dotfile <td>.
23bb0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
23bc0 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
23bd0 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20  d/data.db". Use 
23be0 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
23bf0 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a  "unix-dotfile".*
23c00 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
23c10 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69  uses dot-files i
23c20 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78  n place of posix
23c30 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e   advisory lockin
23c40 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  g..** <tr><td> f
23c50 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
23c60 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a  =readonly <td> .
23c70 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
23c80 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22  rror. "readonly"
23c90 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20   is not a valid 
23ca0 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22  option for the "
23cb0 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e  mode" parameter.
23cc0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a  .** </table>.**.
23cd0 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69  ** ^URI hexadeci
23ce0 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
23cf0 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73  nces (%HH) are s
23d00 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20  upported within 
23d10 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20  the path and.** 
23d20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
23d30 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78   of a URI. A hex
23d40 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
23d50 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74  sequence consist
23d60 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e  s of a.** percen
23d70 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66  t sign - "%" - f
23d80 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74  ollowed by exact
23d90 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d  ly two hexadecim
23da0 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70  al digits .** sp
23db0 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65  ecifying an octe
23dc0 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65  t value. ^Before
23dd0 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65   the path or que
23de0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
23df0 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61   a.** URI filena
23e00 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  me are interpret
23e10 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63  ed, they are enc
23e20 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
23e30 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78   and all .** hex
23e40 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
23e50 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63  sequences replac
23e60 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62  ed by a single b
23e70 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  yte containing t
23e80 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64  he.** correspond
23e90 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68  ing octet. If th
23ea0 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72  is process gener
23eb0 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20  ates an invalid 
23ec0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a  UTF-8 encoding,.
23ed0 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ** the results a
23ee0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
23ef0 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
23f00 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
23f10 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
23f20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
23f30 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
23f40 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
23f50 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
23f60 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
23f70 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
23f80 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
23f90 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
23fa0 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
23fb0 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
23fc0 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
23fd0 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
23fe0 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
23ff0 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
24000 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
24010 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
24020 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
24030 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62  n_v2()..**.** <b
24040 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
24050 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c   Runtime users:<
24060 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61  /b>  The tempora
24070 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73  ry directory mus
24080 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f  t be set.** prio
24090 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c  r to calling sql
240a0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
240b0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
240c0 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61  .  Otherwise, va
240d0 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65  rious.** feature
240e0 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74  s that require t
240f0 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72  he use of tempor
24100 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61  ary files may fa
24110 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  il..**.** See al
24120 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d  so: [sqlite3_tem
24130 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a  p_directory].*/.
24140 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
24150 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
24160 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
24170 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
24180 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
24190 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
241a0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
241b0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
241c0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
241d0 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
241e0 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
241f0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
24200 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
24210 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
24220 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
24230 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
24240 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
24250 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
24260 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
24270 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
24280 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
24290 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
242a0 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
242b0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
242c0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
242d0 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
242e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
242f0 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
24300 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
24310 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
24320 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
24330 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
24340 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
24350 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
24360 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  meters.**.** The
24370 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72  se are utility r
24380 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20  outines, useful 
24390 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
243a0 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
243b0 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ck.** to see if 
243c0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
243d0 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
243e0 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
243f0 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
24400 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
24410 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
24420 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65  alue of that que
24430 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
24440 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20  .** If F is the 
24450 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
24460 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  e pointer passed
24470 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28   into the xOpen(
24480 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20  ) method of .** 
24490 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  a VFS implementa
244a0 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c  tion when the fl
244b0 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
244c0 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65   xOpen() has one
244d0 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20   or .** more of 
244e0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
244f0 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _URI] or [SQLITE
24500 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62  _OPEN_MAIN_DB] b
24510 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50  its set and.** P
24520 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
24530 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  the query parame
24540 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  ter, then.** sql
24550 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
24560 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
24570 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
24580 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20   P.** parameter 
24590 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20  if it exists or 
245a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
245b0 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  f P does not app
245c0 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65  ear as a .** que
245d0 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ry parameter on 
245e0 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75  F.  If P is a qu
245f0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  ery parameter of
24600 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70   F.** has no exp
24610 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65  licit value, the
24620 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
24630 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
24640 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  urns.** a pointe
24650 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  r to an empty st
24660 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
24670 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
24680 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
24690 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ne assumes that 
246a0 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a  P is a boolean.*
246b0 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  * parameter and 
246c0 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
246d0 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63   or false (0) ac
246e0 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76  cording to the v
246f0 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54  alue.** of P.  T
24700 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
24710 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
24720 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72  utine returns tr
24730 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a  ue (1) if the.**
24740 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20   value of query 
24750 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
24760 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72  ne of "yes", "tr
24770 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20  ue", or "on" in 
24780 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69  any.** case or i
24790 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
247a0 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  ns with a non-ze
247b0 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  ro number.  The 
247c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
247d0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
247e0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
247f0 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65  false (0) if the
24800 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65   value of.** que
24810 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
24820 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22  s one of "no", "
24830 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22  false", or "off"
24840 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a   in any case or.
24850 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ** if the value 
24860 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75  begins with a nu
24870 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20  meric zero.  If 
24880 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79  P is not a query
24890 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  .** parameter on
248a0 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c   F or if the val
248b0 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20  ue of P is does 
248c0 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66  not match any of
248d0 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74   the.** above, t
248e0 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
248f0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
24900 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a  eturns (B!=0)..*
24910 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
24920 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44  _uri_int64(F,P,D
24930 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72  ) routine conver
24940 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ts the value of 
24950 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62  P into a.** 64-b
24960 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
24970 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68  r and returns th
24980 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44  at integer, or D
24990 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a   if P does not.*
249a0 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65  * exist.  If the
249b0 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73   value of P is s
249c0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
249d0 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20  han an integer, 
249e0 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20  then.** zero is 
249f0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  returned..** .**
24a00 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20   If F is a NULL 
24a10 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71  pointer, then sq
24a20 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
24a30 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
24a40 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c   NULL and.** sql
24a50 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
24a60 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
24a70 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20  B.  If F is not 
24a80 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
24a90 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64  nd.** is not a d
24aa0 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74  atabase file pat
24ab0 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68  hname pointer th
24ac0 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64  at SQLite passed
24ad0 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a   into the xOpen.
24ae0 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74  ** VFS method, t
24af0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
24b00 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
24b10 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
24b20 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e  d probably.** un
24b30 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f  desirable..*/.co
24b40 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
24b50 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
24b60 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
24b70 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61  ename, const cha
24b80 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20  r *zParam);.int 
24b90 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
24ba0 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ean(const char *
24bb0 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61  zFile, const cha
24bc0 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62  r *zParam, int b
24bd0 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65  Default);.sqlite
24be0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
24bf0 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20  uri_int64(const 
24c00 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61  char*, const cha
24c10 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
24c20 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  4);.../*.** CAPI
24c30 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
24c40 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
24c50 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
24c60 74 20 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33  t recent sqlite3
24c70 5f 2a 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f  _* API call asso
24c80 63 69 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20  ciated with .** 
24c90 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
24ca0 74 69 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20  tion] D failed, 
24cb0 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
24cc0 5f 65 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65  _errcode(D) inte
24cd0 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73  rface.** returns
24ce0 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65   the numeric [re
24cf0 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65  sult code] or [e
24d00 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
24d10 6f 64 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a  ode] for that.**
24d20 20 41 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66   API call..** If
24d30 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
24d40 20 41 50 49 20 63 61 6c 6c 20 77 61 73 20 73 75   API call was su
24d50 63 63 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 65  ccessful,.** the
24d60 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
24d70 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
24d80 65 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64  errcode() is und
24d90 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  efined..** ^The 
24da0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
24db0 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e  _errcode().** in
24dc0 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20 73  terface is the s
24dd0 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74 20  ame except that 
24de0 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
24df0 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e  s the .** [exten
24e00 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
24e10 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e   even when exten
24e20 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
24e30 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
24e40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
24e50 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e  ite3_errmsg() an
24e60 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  d sqlite3_errmsg
24e70 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c  16() return Engl
24e80 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20  ish-language.** 
24e90 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72 69  text that descri
24ea0 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61  bes the error, a
24eb0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
24ec0 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74  r UTF-16 respect
24ed0 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  ively..** ^(Memo
24ee0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
24ef0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
24f00 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
24f10 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68  nternally..** Th
24f20 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
24f30 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77  es not need to w
24f40 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65 69  orry about freei
24f50 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a  ng the result..*
24f60 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65  * However, the e
24f70 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68  rror string migh
24f80 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  t be overwritten
24f90 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   or deallocated 
24fa0 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  by.** subsequent
24fb0 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20   calls to other 
24fc0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
24fd0 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a   functions.)^.**
24fe0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
24ff0 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72 66  _errstr() interf
25000 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
25010 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
25020 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65   text.** that de
25030 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65 73  scribes the [res
25040 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54  ult code], as UT
25050 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  F-8..** ^(Memory
25060 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
25070 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
25080 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
25090 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d  ernally.** and m
250a0 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64  ust not be freed
250b0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
250c0 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ion)^..**.** Whe
250d0 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
250e0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
250f0 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20  ] is in use, it 
25100 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20  might be the.** 
25110 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f  case that a seco
25120 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  nd error occurs 
25130 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68  on a separate th
25140 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a  read in between.
25150 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74  ** the time of t
25160 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61  he first error a
25170 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  nd the call to t
25180 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e  hese interfaces.
25190 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61  .** When that ha
251a0 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e  ppens, the secon
251b0 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  d error will be 
251c0 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74  reported since t
251d0 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hese.** interfac
251e0 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74  es always report
251f0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
25200 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f   result.  To avo
25210 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68  id.** this, each
25220 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61   thread can obta
25230 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65  in exclusive use
25240 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
25250 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
25260 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b  ** by invoking [
25270 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
25280 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ter]([sqlite3_db
25290 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f  _mutex](D)) befo
252a0 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  re beginning.** 
252b0 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76  to use D and inv
252c0 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
252d0 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c  utex_leave]([sql
252e0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
252f0 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20  )) after.** all 
25300 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74  calls to the int
25310 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68  erfaces listed h
25320 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65  ere are complete
25330 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  d..**.** If an i
25340 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
25350 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
25360 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
25370 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
25380 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
25390 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
253a0 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
253b0 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
253c0 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
253d0 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
253e0 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
253f0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72  /.int sqlite3_er
25400 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
25410 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  b);.int sqlite3_
25420 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
25430 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63  (sqlite3 *db);.c
25440 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
25450 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65  e3_errmsg(sqlite
25460 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  3*);.const void 
25470 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
25480 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  6(sqlite3*);.con
25490 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
254a0 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f  _errstr(int);../
254b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
254c0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
254d0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
254e0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
254f0 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
25500 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
25510 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
25520 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
25530 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
25540 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
25550 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
25560 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
25570 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
25580 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
25590 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
255a0 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
255b0 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
255c0 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
255d0 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
255e0 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
255f0 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
25600 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
25610 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
25620 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
25630 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
25640 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
25650 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
25660 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
25670 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
25680 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
25690 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
256a0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
256b0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
256c0 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
256d0 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
256e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
256f0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
25700 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
25710 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
25720 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
25730 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
25740 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
25750 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
25760 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
25770 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
25780 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
25790 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
257a0 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
257b0 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
257c0 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
257d0 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
257e0 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
257f0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
25800 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
25810 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
25820 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
25830 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
25840 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
25850 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a  ime Limits.**.**
25860 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
25870 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
25880 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
25890 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
258a0 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
258b0 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
258c0 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
258d0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
258e0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
258f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25900 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
25910 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
25920 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
25930 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
25940 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
25950 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
25960 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
25970 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
25980 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
25990 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
259a0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
259b0 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
259c0 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
259d0 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
259e0 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
259f0 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
25a00 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
25a10 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
25a20 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
25a30 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
25a40 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
25a50 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
25a60 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
25a70 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
25a80 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
25a90 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
25aa0 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
25ab0 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
25ac0 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
25ad0 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
25ae0 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
25af0 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
25b00 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
25b10 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
25b20 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
25b30 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
25b40 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
25b50 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
25b60 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
25b70 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
25b80 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
25b90 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
25ba0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
25bb0 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
25bc0 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
25bd0 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
25be0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
25bf0 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
25c00 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
25c10 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
25c20 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
25c30 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
25c40 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
25c50 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
25c60 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
25c70 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
25c80 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
25c90 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
25ca0 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
25cb0 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
25cc0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
25cd0 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
25ce0 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
25cf0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
25d00 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
25d10 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
25d20 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
25d30 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
25d40 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
25d50 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
25d60 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
25d70 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
25d80 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
25d90 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
25da0 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
25db0 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
25dc0 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
25dd0 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
25de0 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
25df0 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
25e00 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
25e10 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
25e20 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
25e30 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
25e40 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
25e50 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
25e60 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
25e70 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
25e80 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
25e90 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
25ea0 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
25eb0 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
25ec0 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
25ed0 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
25ee0 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
25ef0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
25f00 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
25f10 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
25f20 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
25f30 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
25f40 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
25f50 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
25f60 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
25f70 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
25f80 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
25f90 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
25fa0 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
25fb0 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
25fc0 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
25fd0 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
25fe0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
25ff0 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ses..*/.int sqli
26000 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
26010 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
26020 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
26030 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
26040 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
26050 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ies.** KEYWORDS:
26060 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79   {limit category
26070 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f  } {*limit catego
26080 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
26090 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
260a0 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f  ne various perfo
260b0 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a  rmance limits.**
260c0 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77   that can be low
260d0 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  ered at run-time
260e0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
260f0 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
26100 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65   synopsis of the
26110 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
26120 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
26130 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  is shown below..
26140 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** Additional in
26150 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61  formation is ava
26160 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74  ilable at [limit
26170 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51  s | Limits in SQ
26180 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  Lite]..**.** <dl
26190 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  >.** [[SQLITE_LI
261a0 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  MIT_LENGTH]] ^(<
261b0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
261c0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
261d0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
261e0 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
261f0 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
26200 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73  le row, in bytes
26210 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  .<dd>)^.**.** [[
26220 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
26230 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
26240 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
26250 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
26260 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
26270 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
26280 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
26290 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
262a0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
262b0 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74  T_COLUMN]] ^(<dt
262c0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
262d0 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
262e0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
262f0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
26300 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
26310 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
26320 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
26330 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
26340 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
26350 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
26360 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
26370 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
26380 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
26390 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
263a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
263b0 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
263c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
263d0 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
263e0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
263f0 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
26400 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
26410 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29  xpression.</dd>)
26420 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
26430 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
26440 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53  SELECT]] ^(<dt>S
26450 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
26460 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
26470 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26480 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
26490 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
264a0 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
264b0 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
264c0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
264d0 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e  VDBE_OP]] ^(<dt>
264e0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
264f0 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
26500 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
26510 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
26520 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
26530 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
26540 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
26550 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
26560 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69  tement.  This li
26570 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65  mit is not curre
26580 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64  ntly.** enforced
26590 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69  , though that mi
265a0 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20  ght be added in 
265b0 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
265c0 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
265d0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
265e0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
265f0 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c  NCTION_ARG]] ^(<
26600 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26610 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74  FUNCTION_ARG</dt
26620 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
26630 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
26640 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75  rguments on a fu
26650 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  nction.</dd>)^.*
26660 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
26670 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e  MIT_ATTACHED]] ^
26680 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
26690 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
266a0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
266b0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54  um number of [AT
266c0 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20  TACH | attached 
266d0 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64  databases].)^</d
266e0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
266f0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
26700 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a  TERN_LENGTH]].**
26710 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
26720 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
26730 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
26740 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
26750 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
26760 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
26770 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a  o the [LIKE] or.
26780 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  ** [GLOB] operat
26790 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ors.</dd>)^.**.*
267a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
267b0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
267c0 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
267d0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
267e0 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
267f0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
26800 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66   index number of
26810 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d   any [parameter]
26820 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
26830 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ment.)^.**.** [[
26840 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
26850 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  GGER_DEPTH]] ^(<
26860 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26870 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64  TRIGGER_DEPTH</d
26880 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
26890 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72  ximum depth of r
268a0 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69  ecursion for tri
268b0 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ggers.</dd>)^.**
268c0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
268d0 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
268e0 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  S]] ^(<dt>SQLITE
268f0 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48  _LIMIT_WORKER_TH
26900 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  READS</dt>.** <d
26910 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
26920 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72  mber of auxiliar
26930 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73  y worker threads
26940 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a   that a single.*
26950 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
26960 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74  ement] may start
26970 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
26980 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
26990 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
269a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
269b0 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
269c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
269d0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
269e0 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
269f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
26a00 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
26a10 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
26a20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
26a30 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
26a40 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
26a50 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
26a60 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
26a70 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
26a80 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
26a90 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
26aa0 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
26ab0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
26ac0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
26ad0 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
26ae0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
26af0 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
26b00 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
26b10 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
26b20 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
26b30 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
26b40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
26b50 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
26b60 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
26b70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
26b80 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
26b90 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
26ba0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
26bb0 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
26bc0 41 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31  ADS           11
26bd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26be0 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53  : Compiling An S
26bf0 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
26c00 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73  KEYWORDS: {SQL s
26c10 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65  tatement compile
26c20 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63  r}.**.** To exec
26c30 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79  ute an SQL query
26c40 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20  , it must first 
26c50 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  be compiled into
26c60 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20   a byte-code.** 
26c70 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e  program using on
26c80 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
26c90 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  nes..**.** The f
26ca0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22  irst argument, "
26cb0 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62  db", is a [datab
26cc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
26cd0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a  obtained from a.
26ce0 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73  ** prior success
26cf0 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ful call to [sql
26d00 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
26d10 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
26d20 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
26d30 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65  _open16()].  The
26d40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
26d50 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61  tion must not ha
26d60 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a  ve been closed..
26d70 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
26d80 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c   argument, "zSql
26d90 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d  ", is the statem
26da0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
26db0 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61  ed, encoded.** a
26dc0 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f  s either UTF-8 o
26dd0 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73  r UTF-16.  The s
26de0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
26df0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
26e00 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74  pare_v2().** int
26e10 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d  erfaces use UTF-
26e20 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  8, and sqlite3_p
26e30 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73  repare16() and s
26e40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
26e50 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46  _v2().** use UTF
26e60 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  -16..**.** ^If t
26e70 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e  he nByte argumen
26e80 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  t is negative, t
26e90 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
26ea0 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69   up to the.** fi
26eb0 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
26ec0 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69  tor. ^If nByte i
26ed0 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e  s positive, then
26ee0 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75   it is the.** nu
26ef0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65  mber of bytes re
26f00 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e  ad from zSql.  ^
26f10 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f  If nByte is zero
26f20 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72  , then no prepar
26f30 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
26f40 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a  is generated..**
26f50 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b   If the caller k
26f60 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75  nows that the su
26f70 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
26f80 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
26f90 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69   then.** there i
26fa0 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72  s a small perfor
26fb0 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
26fc0 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42  to passing an nB
26fd0 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68  yte parameter th
26fe0 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  at.** is the num
26ff0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
27000 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
27010 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69   <i>including</i
27020 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72  >.** the nul-ter
27030 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  minator..**.** ^
27040 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74  If pzTail is not
27050 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61   NULL then *pzTa
27060 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f  il is made to po
27070 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
27080 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68   byte.** past th
27090 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72  e end of the fir
270a0 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
270b0 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65   in zSql.  These
270c0 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a   routines only.*
270d0 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69  * compile the fi
270e0 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  rst statement in
270f0 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69   zSql, so *pzTai
27100 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  l is left pointi
27110 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65  ng to.** what re
27120 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64  mains uncompiled
27130 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74  ..**.** ^*ppStmt
27140 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
27150 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20  g to a compiled 
27160 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27170 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65  ent] that can be
27180 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69  .** executed usi
27190 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
271a0 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20  ()].  ^If there 
271b0 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70  is an error, *pp
271c0 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74  Stmt is set.** t
271d0 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65  o NULL.  ^If the
271e0 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74   input text cont
271f0 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20  ains no SQL (if 
27200 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20  the input is an 
27210 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20  empty.** string 
27220 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68  or a comment) th
27230 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65  en *ppStmt is se
27240 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68  t to NULL..** Th
27250 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64  e calling proced
27260 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ure is responsib
27270 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20  le for deleting 
27280 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20  the compiled.** 
27290 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73  SQL statement us
272a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
272b0 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69  alize()] after i
272c0 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  t has finished w
272d0 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d  ith it..** ppStm
272e0 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c  t may not be NUL
272f0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63  L..**.** ^On suc
27300 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65  cess, the sqlite
27310 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69  3_prepare() fami
27320 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72  ly of routines r
27330 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
27340 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20  ];.** otherwise 
27350 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
27360 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
27370 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  ** The sqlite3_p
27380 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20  repare_v2() and 
27390 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
273a0 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  6_v2() interface
273b0 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65  s are.** recomme
273c0 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77  nded for all new
273d0 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74   programs. The t
273e0 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61  wo older interfa
273f0 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64  ces are retained
27400 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64  .** for backward
27410 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c  s compatibility,
27420 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69   but their use i
27430 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a  s discouraged..*
27440 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69  * ^In the "v2" i
27450 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70  nterfaces, the p
27460 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27470 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74  t.** that is ret
27480 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69  urned (the [sqli
27490 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
274a0 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70  ) contains a cop
274b0 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67  y of the.** orig
274c0 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54  inal SQL text. T
274d0 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b  his causes the [
274e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
274f0 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
27500 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74  behave different
27510 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73  ly in three ways
27520 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20  :.**.** <ol>.** 
27530 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
27540 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
27550 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64  changes, instead
27560 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53   of returning [S
27570 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73  QLITE_SCHEMA] as
27580 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73   it.** always us
27590 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74  ed to do, [sqlit
275a0 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20  e3_step()] will 
275b0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
275c0 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a  compile the SQL.
275d0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ** statement and
275e0 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61   try to run it a
275f0 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73  gain. As many as
27600 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48   [SQLITE_MAX_SCH
27610 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65  EMA_RETRY].** re
27620 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72  tries will occur
27630 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
27640 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20  step() gives up 
27650 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65  and returns an e
27660 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  rror..** </li>.*
27670 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68  *.** <li>.** ^Wh
27680 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  en an error occu
27690 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  rs, [sqlite3_ste
276a0 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  p()] will return
276b0 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61   one of the deta
276c0 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  iled.** [error c
276d0 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64  odes] or [extend
276e0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e  ed error codes].
276f0 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65    ^The legacy be
27700 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a  havior was that.
27710 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
27720 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72  ()] would only r
27730 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20  eturn a generic 
27740 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72  [SQLITE_ERROR] r
27750 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e  esult code.** an
27760 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
27770 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20  n would have to 
27780 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61  make a second ca
27790 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ll to [sqlite3_r
277a0 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72  eset()].** in or
277b0 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20  der to find the 
277c0 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65  underlying cause
277d0 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e   of the problem.
277e0 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70   With the "v2" p
277f0 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66  repare.** interf
27800 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c  aces, the underl
27810 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20  ying reason for 
27820 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74  the error is ret
27830 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
27840 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a  y..** </li>.**.*
27850 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68  * <li>.** ^If th
27860 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
27870 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d   bound to [param
27880 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61  eter | host para
27890 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a  meter] in the .*
278a0 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d  * WHERE clause m
278b0 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
278c0 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  he choice of que
278d0 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74  ry plan for a st
278e0 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e  atement,.** then
278f0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
27900 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
27910 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c  ally recompiled,
27920 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64   as if there had
27930 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65   been .** a sche
27940 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68  ma change, on th
27950 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65  e first  [sqlite
27960 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66  3_step()] call f
27970 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61  ollowing any cha
27980 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  nge.** to the [s
27990 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
279a0 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20   | bindings] of 
279b0 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d  that [parameter]
279c0 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69  . .** ^The speci
279d0 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45  fic value of WHE
279e0 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d  RE-clause [param
279f0 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c  eter] might infl
27a00 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68  uence the .** ch
27a10 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
27a20 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  an if the parame
27a30 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d  ter is the left-
27a40 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b  hand side of a [
27a50 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f  LIKE].** or [GLO
27a60 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69  B] operator or i
27a70 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
27a80 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61  is compared to a
27a90 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e  n indexed column
27aa0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c  .** and the [SQL
27ab0 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33  ITE_ENABLE_STAT3
27ac0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
27ad0 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ption is enabled
27ae0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  ..** </li>.** </
27af0 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ol>.*/.int sqlit
27b00 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
27b10 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
27b20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
27b30 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
27b40 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
27b50 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
27b60 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
27b70 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
27b80 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
27b90 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
27ba0 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
27bb0 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
27bc0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
27bd0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
27be0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
27bf0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
27c00 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
27c10 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
27c20 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
27c30 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
27c40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
27c50 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
27c60 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
27c70 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
27c80 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
27c90 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
27ca0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
27cb0 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
27cc0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
27cd0 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
27ce0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
27cf0 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
27d00 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
27d10 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
27d20 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
27d30 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
27d40 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
27d50 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
27d60 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
27d70 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
27d80 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
27d90 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
27da0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
27db0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
27dc0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
27dd0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
27de0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
27df0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
27e00 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
27e10 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
27e20 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
27e30 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
27e40 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
27e50 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
27e60 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
27e70 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
27e80 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
27e90 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
27ea0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
27eb0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
27ec0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
27ed0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
27ee0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
27ef0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
27f00 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
27f10 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
27f20 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
27f30 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
27f40 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
27f50 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
27f60 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
27f70 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
27f80 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
27f90 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
27fa0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
27fb0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
27fc0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
27fd0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
27fe0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
27ff0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
28000 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
28010 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28020 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
28030 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e  ment SQL.**.** ^
28040 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
28050 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
28060 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63  trieve a saved c
28070 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69  opy of the origi
28080 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  nal.** SQL text 
28090 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61  used to create a
280a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
280b0 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74  ment] if that st
280c0 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63  atement was.** c
280d0 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
280e0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
280f0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
28100 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
28110 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  6_v2()]..*/.cons
28120 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
28130 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
28140 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
28150 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
28160 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
28170 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20  tatement Writes 
28180 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a  The Database.**.
28190 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
281a0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29  stmt_readonly(X)
281b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
281c0 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
281d0 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  o) if.** and onl
281e0 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72  y if the [prepar
281f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20  ed statement] X 
28200 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20  makes no direct 
28210 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68  changes to.** th
28220 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
28230 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
28240 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
28250 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
28260 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
28270 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75  ns] or.** [virtu
28280 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74  al tables] might
28290 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
282a0 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20  base indirectly 
282b0 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74  as a side effect
282c0 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .  .** ^(For exa
282d0 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c  mple, if an appl
282e0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20  ication defines 
282f0 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c  a function "eval
28300 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c  ()" that .** cal
28310 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ls [sqlite3_exec
28320 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  ()], then the fo
28330 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74  llowing SQL stat
28340 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63  ement would.** c
28350 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
28360 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20  se file through 
28370 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a  side-effects:.**
28380 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
28390 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45  <pre>.**    SELE
283a0 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20  CT eval('DELETE 
283b0 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74  FROM t1') FROM t
283c0 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  2;.** </pre></bl
283d0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
283e0 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20  But because the 
283f0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
28400 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nt does not chan
28410 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
28420 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79  file.** directly
28430 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  , sqlite3_stmt_r
28440 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20  eadonly() would 
28450 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75  still return tru
28460 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e  e.)^.**.** ^Tran
28470 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20  saction control 
28480 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20  statements such 
28490 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d  as [BEGIN], [COM
284a0 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d  MIT], [ROLLBACK]
284b0 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d  ,.** [SAVEPOINT]
284c0 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20  , and [RELEASE] 
284d0 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74  cause sqlite3_st
284e0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
284f0 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a   return true,.**
28500 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65   since the state
28510 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73  ments themselves
28520 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   do not actually
28530 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
28540 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68  base but.** rath
28550 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20  er they control 
28560 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68  the timing of wh
28570 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65  en other stateme
28580 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a  nts modify the .
28590 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54  ** database.  ^T
285a0 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20  he [ATTACH] and 
285b0 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65  [DETACH] stateme
285c0 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a  nts also cause.*
285d0 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
285e0 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
285f0 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20  urn true since, 
28600 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74  while those stat
28610 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65  ements.** change
28620 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
28630 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  on of a database
28640 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65   connection, the
28650 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a  y do not make .*
28660 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  * changes to the
28670 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
28680 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f  database files o
28690 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20 73  n disk..*/.int s
286a0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
286b0 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  only(sqlite3_stm
286c0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
286d0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
286e0 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70 61  rmine If A Prepa
286f0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61  red Statement Ha
28700 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a  s Been Reset.**.
28710 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28720 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74  stmt_busy(S) int
28730 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
28740 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69  rue (non-zero) i
28750 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  f the.** [prepar
28760 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
28770 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64  has been stepped
28780 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75   at least once u
28790 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
287a0 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68  3_step(S)] but h
287b0 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f  as not run to co
287c0 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20  mpletion and/or 
287d0 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e  has not .** been
287e0 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71   reset using [sq
287f0 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e  lite3_reset(S)].
28800 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
28810 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69  tmt_busy(S).** i
28820 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
28830 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61   false if S is a
28840 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
28850 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a  If S is not a .*
28860 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  * NULL pointer a
28870 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e  nd is not a poin
28880 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b  ter to a valid [
28890 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
288a0 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74  nt].** object, t
288b0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
288c0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
288d0 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73  d probably undes
288e0 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  irable..**.** Th
288f0 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
28900 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62   be used in comb
28910 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33  ination [sqlite3
28920 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a  _next_stmt()].**
28930 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70   to locate all p
28940 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28950 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ts associated wi
28960 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a  th a database .*
28970 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  * connection tha
28980 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66  t are in need of
28990 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54   being reset.  T
289a0 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c  his can be used,
289b0 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  .** for example,
289c0 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72   in diagnostic r
289d0 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63  outines to searc
289e0 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a  h for prepared .
289f0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  ** statements th
28a00 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61  at are holding a
28a10 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65   transaction ope
28a20 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
28a30 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69  3_stmt_busy(sqli
28a40 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
28a50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
28a60 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
28a70 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
28a80 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
28a90 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
28aa0 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
28ab0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
28ac0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
28ad0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
28ae0 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
28af0 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
28b00 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
28b10 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
28b20 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
28b30 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
28b40 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
28b50 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
28b60 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
28b70 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
28b80 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
28b90 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
28ba0 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
28bb0 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
28bc0 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
28bd0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
28be0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
28bf0 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
28c00 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
28c10 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
28c20 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
28c30 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
28c40 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
28c50 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
28c60 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
28c70 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
28c80 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
28c90 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
28ca0 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
28cb0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
28cc0 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
28cd0 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
28ce0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
28cf0 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
28d00 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
28d10 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
28d20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
28d30 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
28d40 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
28d50 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
28d60 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
28d70 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20  ex is held.  An 
28d80 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
28d90 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
28da0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
28db0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
28dc0 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
28dd0 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
28de0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
28df0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
28e00 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
28e10 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
28e20 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
28e30 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
28e40 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
28e50 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
28e60 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
28e70 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
28e80 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
28e90 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
28ea0 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
28eb0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
28ec0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
28ed0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
28ee0 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
28ef0 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
28f00 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
28f10 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
28f20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
28f30 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
28f40 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
28f50 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
28f60 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
28f70 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
28f80 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
28f90 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
28fa0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
28fb0 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
28fc0 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
28fd0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
28fe0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
28ff0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
29000 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
29010 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
29020 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
29030 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
29040 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
29050 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
29060 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
29070 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
29080 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
29090 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
290a0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
290b0 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
290c0 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
290d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
290e0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
290f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
29100 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
29110 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
29120 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
29130 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
29140 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
29150 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
29160 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
29170 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
29180 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
29190 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
291a0 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
291b0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
291c0 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
291d0 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
291e0 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
291f0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
29200 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
29210 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
29220 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
29230 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
29240 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
29250 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
29260 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
29270 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
29280 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
29290 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
292a0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
292b0 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
292c0 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
292d0 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
292e0 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
292f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
29300 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
29310 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
29320 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
29330 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
29340 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
29350 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
29360 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
29370 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
29380 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
29390 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
293a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
293b0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
293c0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
293d0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
293e0 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
293f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
29400 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
29410 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
29420 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
29430 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
29440 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
29450 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
29460 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
29470 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
29480 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
29490 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
294a0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
294b0 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
294c0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
294d0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
294e0 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
294f0 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
29500 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
29510 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
29520 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
29530 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a  r binding}.**.**
29540 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
29550 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
29560 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
29570 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
29580 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
29590 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
295a0 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
295b0 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
295c0 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
295d0 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
295e0 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
295f0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
29600 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
29610 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
29620 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
29630 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
29640 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
29650 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
29660 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
29670 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
29680 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
29690 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
296a0 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72  meric identifier
296b0 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  .)^  ^The values
296c0 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72   of these.** par
296d0 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
296e0 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
296f0 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22  eter names" or "
29700 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29  SQL parameters")
29710 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75  .** can be set u
29720 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
29730 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
29740 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  es defined here.
29750 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
29760 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
29770 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
29780 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
29790 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
297a0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
297b0 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
297c0 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
297d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
297e0 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
297f0 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ariants..**.** ^
29800 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
29810 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
29820 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
29830 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
29840 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  .** ^The leftmos
29850 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
29860 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
29870 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61  1.  ^When the sa
29880 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20  me named.** SQL 
29890 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
298a0 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
298b0 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
298c0 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
298d0 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
298e0 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
298f0 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
29900 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65  ce..** ^The inde
29910 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
29920 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
29930 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
29940 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
29950 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
29960 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
29970 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65  ired.  ^The inde
29980 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
29990 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
299a0 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
299b0 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75  ** ^The NNN valu
299c0 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
299d0 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
299e0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
299f0 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
29a00 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
29a10 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
29a20 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
29a30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
29a40 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
29a50 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
29a60 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
29a70 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
29a80 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
29a90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
29aa0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
29ab0 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f  nd_text16().** o
29ac0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  r sqlite3_bind_b
29ad0 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20  lob() is a NULL 
29ae0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
29af0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
29b00 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20  r.** is ignored 
29b10 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73 75  and the end resu
29b20 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  lt is the same a
29b30 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  s sqlite3_bind_n
29b40 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ull()..**.** ^(I
29b50 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73  n those routines
29b60 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75   that have a fou
29b70 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74  rth argument, it
29b80 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a  s value is the.*
29b90 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  * number of byte
29ba0 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  s in the paramet
29bb0 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72  er.  To be clear
29bc0 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74  : the value is t
29bd0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
29be0 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20  <u>bytes</u> in 
29bf0 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74  the value, not t
29c00 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
29c10 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49  racters.)^.** ^I
29c20 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
29c30 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
29c40 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
29c50 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
29c60 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67  xt16().** is neg
29c70 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
29c80 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74  length of the st
29c90 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e  ring is.** the n
29ca0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 75  umber of bytes u
29cb0 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a  p to the first z
29cc0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  ero terminator..
29cd0 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  ** If the fourth
29ce0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
29cf0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
29d00 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  ) is negative, t
29d10 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76  hen.** the behav
29d20 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
29d30 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65  ..** If a non-ne
29d40 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61  gative fourth pa
29d50 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69  rameter is provi
29d60 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ded to sqlite3_b
29d70 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72  ind_text().** or
29d80 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
29d90 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65  xt16() or sqlite
29da0 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
29db0 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72  then.** that par
29dc0 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 74  ameter must be t
29dd0 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a  he byte offset.*
29de0 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20  * where the NUL 
29df0 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64  terminator would
29e00 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20   occur assuming 
29e10 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65 20  the string were 
29e20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65  NUL.** terminate
29e30 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
29e40 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 20  haracters occur 
29e50 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73 20  at byte offsets 
29e60 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68  less than .** th
29e70 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66  e value of the f
29e80 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
29e90 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69  then the resulti
29ea0 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20  ng string value 
29eb0 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  will.** contain 
29ec0 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20  embedded NULs.  
29ed0 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78  The result of ex
29ee0 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76  pressions involv
29ef0 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77  ing strings.** w
29f00 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
29f10 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
29f20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
29f30 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
29f40 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67   BLOB and string
29f50 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61   binding interfa
29f60 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74  ces.** is a dest
29f70 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
29f80 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
29f90 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
29fa0 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
29fb0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
29fc0 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63  t.  ^The destruc
29fd0 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a  tor is called.**
29fe0 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
29ff0 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
2a000 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61  g even if the ca
2a010 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66  ll to bind API f
2a020 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ails..** ^If the
2a030 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2a040 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61  is.** the specia
2a050 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  l value [SQLITE_
2a060 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51  STATIC], then SQ
2a070 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
2a080 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  t the.** informa
2a090 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69  tion is in stati
2a0a0 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  c, unmanaged spa
2a0b0 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  ce and does not 
2a0c0 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64  need to be freed
2a0d0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66  ..** ^If the fif
2a0e0 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  th argument has 
2a0f0 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  the value [SQLIT
2a100 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
2a110 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  en.** SQLite mak
2a120 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  es its own priva
2a130 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64  te copy of the d
2a140 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  ata immediately,
2a150 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73   before.** the s
2a160 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2a170 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e  routine returns.
2a180 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74  .**.** ^The sixt
2a190 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
2a1a0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2a1b0 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20  4() must be one 
2a1c0 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  of.** [SQLITE_UT
2a1d0 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  F8], [SQLITE_UTF
2a1e0 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46  16], [SQLITE_UTF
2a1f0 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  16BE], or [SQLIT
2a200 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f  E_UTF16LE].** to
2a210 20 73 70 65 63 69 66 79 20 74 68 65 20 65 6e 63   specify the enc
2a220 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78  oding of the tex
2a230 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70  t in the third p
2a240 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a  arameter.  If.**
2a250 20 74 68 65 20 73 69 78 74 68 20 61 72 67 75 6d   the sixth argum
2a260 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
2a270 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73 20  ind_text64() is 
2a280 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
2a290 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73  * allowed values
2a2a0 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72   shown above, or
2a2b0 20 69 66 20 74 68 65 20 74 65 78 74 20 65 6e 63   if the text enc
2a2c0 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
2a2d0 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65  nt.** from the e
2a2e0 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65  ncoding specifie
2a2f0 64 20 62 79 20 74 68 65 20 73 69 78 74 68 20 70  d by the sixth p
2a300 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74  arameter, then t
2a310 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69  he behavior.** i
2a320 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2a330 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2a340 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20  bind_zeroblob() 
2a350 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20  routine binds a 
2a360 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e  BLOB of length N
2a370 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c   that.** is fill
2a380 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20  ed with zeroes. 
2a390 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65   ^A zeroblob use
2a3a0 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74  s a fixed amount
2a3b0 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a   of memory.** (j
2a3c0 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74  ust an integer t
2a3d0 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29  o hold its size)
2a3e0 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65 69   while it is bei
2a3f0 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a  ng processed..**
2a400 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69   Zeroblobs are i
2a410 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65  ntended to serve
2a420 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73   as placeholders
2a430 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65   for BLOBs whose
2a440 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c  .** content is l
2a450 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73 69  ater written usi
2a460 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ng.** [sqlite3_b
2a470 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65  lob_open | incre
2a480 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d  mental BLOB I/O]
2a490 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41   routines..** ^A
2a4a0 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65 20   negative value 
2a4b0 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62  for the zeroblob
2a4c0 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65   results in a ze
2a4d0 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a  ro-length BLOB..
2a4e0 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66  **.** ^If any of
2a4f0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2a500 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61  d_*() routines a
2a510 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  re called with a
2a520 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
2a530 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72   for the [prepar
2a540 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72  ed statement] or
2a550 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65 64   with a prepared
2a560 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77   statement for w
2a570 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hich.** [sqlite3
2a580 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65 65  _step()] has bee
2a590 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65  n called more re
2a5a0 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c  cently than [sql
2a5b0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a  ite3_reset()],.*
2a5c0 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20  * then the call 
2a5d0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
2a5e0 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66  ITE_MISUSE].  If
2a5f0 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e   any sqlite3_bin
2a600 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  d_().** routine 
2a610 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72 65  is passed a [pre
2a620 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a630 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20 66   that has been f
2a640 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a  inalized, the.**
2a650 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
2a660 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
2a670 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
2a680 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e   ^Bindings are n
2a690 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74 68  ot cleared by th
2a6a0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
2a6b0 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20  ()] routine..** 
2a6c0 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  ^Unbound paramet
2a6d0 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  ers are interpre
2a6e0 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ted as NULL..**.
2a6f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2a700 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20  bind_* routines 
2a710 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
2a720 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72  K] on success or
2a730 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f   an.** [error co
2a740 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20  de] if anything 
2a750 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e  goes wrong..** ^
2a760 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20  [SQLITE_TOOBIG] 
2a770 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
2a780 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66  d if the size of
2a790 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f   a string or BLO
2a7a0 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d  B.** exceeds lim
2a7b0 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b  its imposed by [
2a7c0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
2a7d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
2a7e0 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c  GTH]) or.** [SQL
2a7f0 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e  ITE_MAX_LENGTH].
2a800 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e  .** ^[SQLITE_RAN
2a810 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  GE] is returned 
2a820 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
2a830 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74  .** index is out
2a840 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51   of range.  ^[SQ
2a850 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72  LITE_NOMEM] is r
2a860 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f  eturned if mallo
2a870 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a  c() fails..**.**
2a880 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2a890 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2a8a0 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20  er_count()],.** 
2a8b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2a8c0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
2a8d0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
2a8e0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2a8f0 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
2a900 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
2a910 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a920 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
2a930 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
2a940 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
2a950 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34  ite3_bind_blob64
2a960 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a970 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2a980 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
2a990 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
2a9a0 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a            void(*
2a9b0 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
2a9c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
2a9d0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
2a9e0 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
2a9f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2aa00 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
2aa10 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
2aa20 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2aa30 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
2aa40 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
2aa50 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
2aa60 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
2aa70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2aa80 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
2aa90 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
2aaa0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e  e3_stmt*,int,con
2aab0 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69  st char*,int,voi
2aac0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
2aad0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
2aae0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
2aaf0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2ab00 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
2ab10 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2ab20 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2ab30 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt64(sqlite3_stm
2ab40 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
2ab50 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  har*, sqlite3_ui
2ab60 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
2ab70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
2ab80 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75  oid(*)(void*), u
2ab90 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63  nsigned char enc
2aba0 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71 6c 69  oding);.int sqli
2abb0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
2abc0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2abd0 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
2abe0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2abf0 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
2ac00 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2ac10 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
2ac20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ac30 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50   Number Of SQL P
2ac40 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
2ac50 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61  ^This routine ca
2ac60 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e  n be used to fin
2ac70 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
2ac80 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d  [SQL parameters]
2ac90 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72  .** in a [prepar
2aca0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
2acb0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61  SQL parameters a
2acc0 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65  re tokens of the
2acd0 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f  .** form "?", "?
2ace0 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24  NNN", ":AAA", "$
2acf0 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20  AAA", or "@AAA" 
2ad00 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a  that serve as.**
2ad10 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
2ad20 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72  r values that ar
2ad30 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2ad40 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a  blob | bound].**
2ad50 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
2ad60 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69  rs at a later ti
2ad70 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  me..**.** ^(This
2ad80 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c   routine actuall
2ad90 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e  y returns the in
2ada0 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65  dex of the large
2adb0 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a  st (rightmost).*
2adc0 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72  * parameter. For
2add0 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70   all forms excep
2ade0 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c  t ?NNN, this wil
2adf0 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20  l correspond to 
2ae00 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2ae10 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65   unique paramete
2ae20 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65  rs.  If paramete
2ae30 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66  rs of the ?NNN f
2ae40 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a  orm are used,.**
2ae50 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61   there may be ga
2ae60 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29  ps in the list.)
2ae70 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
2ae80 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2ae90 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2aea0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
2aeb0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2aec0 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
2aed0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2aee0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2aef0 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
2af00 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2af10 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2af20 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2af30 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
2af40 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72  A Host Parameter
2af50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2af60 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2af70 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74  er_name(P,N) int
2af80 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
2af90 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * the name of th
2afa0 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61  e N-th [SQL para
2afb0 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70  meter] in the [p
2afc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2afd0 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70  t] P..** ^(SQL p
2afe0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
2aff0 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
2b000 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
2b010 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
2b020 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
2b030 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
2b040 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
2b050 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
2b060 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
2b070 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
2b080 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
2b090 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
2b0a0 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
2b0b0 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
2b0c0 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29  rt of the name.)
2b0d0 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73  ^.** ^Parameters
2b0e0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
2b0f0 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f   without a follo
2b100 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76  wing integer hav
2b110 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64  e no name.** and
2b120 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f   are referred to
2b130 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f   as "nameless" o
2b140 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  r "anonymous par
2b150 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20  ameters"..**.** 
2b160 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20  ^The first host 
2b170 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
2b180 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74   index of 1, not
2b190 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   0..**.** ^If th
2b1a0 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74  e value N is out
2b1b0 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
2b1c0 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74  the N-th paramet
2b1d0 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
2b1e0 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
2b1f0 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20  returned.  ^The 
2b200 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2b210 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20  is.** always in 
2b220 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65  UTF-8 encoding e
2b230 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64  ven if the named
2b240 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a   parameter was.*
2b250 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65  * originally spe
2b260 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36  cified as UTF-16
2b270 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   in [sqlite3_pre
2b280 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  pare16()] or.** 
2b290 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b2a0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
2b2b0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2b2c0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2b2d0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
2b2e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2b2f0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
2b300 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2b310 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2b320 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63  r_index()]..*/.c
2b330 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2b340 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2b350 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
2b360 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
2b370 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
2b380 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
2b390 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
2b3a0 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  ame.**.** ^Retur
2b3b0 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  n the index of a
2b3c0 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
2b3d0 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
2b3e0 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76   ^The.** index v
2b3f0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
2b400 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73   suitable for us
2b410 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  e as the second.
2b420 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
2b430 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2b440 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2b450 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20  )].  ^A zero.** 
2b460 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
2b470 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
2b480 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
2b490 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a  ^The parameter.*
2b4a0 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67  * name must be g
2b4b0 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76  iven in UTF-8 ev
2b4c0 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e  en if the origin
2b4d0 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  al statement.** 
2b4e0 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f  was prepared fro
2b4f0 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73  m UTF-16 text us
2b500 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
2b510 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
2b520 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2b530 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2b540 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2b550 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2b560 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2b570 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
2b580 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2b590 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2b5a0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
2b5b0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2b5c0 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
2b5d0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
2b5e0 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
2b5f0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
2b600 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
2b610 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2b620 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61  nt.**.** ^Contra
2b630 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
2b640 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
2b650 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
2b660 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
2b670 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
2b680 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
2b690 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
2b6a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2b6b0 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74  * ^Use this rout
2b6c0 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
2b6d0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
2b6e0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
2b6f0 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
2b700 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
2b710 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2b720 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
2b730 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
2b740 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
2b750 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d   ^Return the num
2b760 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2b770 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
2b780 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2b790 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2b7a0 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20  atement]. ^This 
2b7b0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2b7c0 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e  0 if pStmt is an
2b7d0 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
2b7e0 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  t that does not 
2b7f0 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72  return data (for
2b800 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44   example an [UPD
2b810 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ATE])..**.** See
2b820 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2b830 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  data_count()].*/
2b840 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2b850 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
2b860 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2b870 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b880 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
2b890 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
2b8a0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2b8b0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
2b8c0 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
2b8d0 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
2b8e0 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
2b8f0 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
2b900 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2b910 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2b920 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a  column_name().**
2b930 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2b940 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2b950 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2b960 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  d UTF-8 string.*
2b970 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
2b980 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65  lumn_name16() re
2b990 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2b9a0 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2b9b0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
2b9c0 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72  tring.  ^The fir
2b9d0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2b9e0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2b9f0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
2ba00 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
2ba10 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2ba20 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  nt. ^The second 
2ba30 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2ba40 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
2ba50 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  r.  ^The leftmos
2ba60 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
2ba70 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er 0..**.** ^The
2ba80 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2ba90 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
2baa0 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
2bab0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2bac0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
2bad0 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
2bae0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2baf0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
2bb00 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
2bb10 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
2bb20 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
2bb30 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
2bb40 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
2bb50 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
2bb60 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
2bb70 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
2bb80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bb90 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
2bba0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2bbb0 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
2bbc0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lumn..**.** ^If 
2bbd0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2bbe0 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
2bbf0 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
2bc00 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
2bc10 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
2bc20 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
2bc30 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
2bc40 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
2bc50 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
2bc60 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2bc70 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2bc80 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
2bc90 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
2bca0 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
2bcb0 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
2bcc0 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
2bcd0 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
2bce0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
2bcf0 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
2bd00 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2bd10 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
2bd20 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
2bd30 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
2bd40 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
2bd50 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
2bd60 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2bd70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2bd80 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2bd90 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20  , int N);.const 
2bda0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2bdb0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
2bdc0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
2bdd0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2bde0 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
2bdf0 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
2be00 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  sult.**.** ^Thes
2be10 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
2be20 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
2be30 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61  termine the data
2be40 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
2be50 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  .** table column
2be60 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69   that is the ori
2be70 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75  gin of a particu
2be80 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  lar result colum
2be90 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d  n in.** [SELECT]
2bea0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
2beb0 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
2bec0 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
2bed0 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
2bee0 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
2bef0 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
2bf00 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
2bf10 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61  g.  ^The _databa
2bf20 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
2bf30 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
2bf40 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
2bf50 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
2bf60 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
2bf70 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
2bf80 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
2bf90 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
2bfa0 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68  umn name..** ^Th
2bfb0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2bfc0 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
2bfd0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2bfe0 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
2bff0 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
2c000 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2c010 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
2c020 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2c030 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
2c040 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
2c050 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
2c060 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2c070 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
2c080 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
2c090 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
2c0a0 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
2c0b0 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
2c0c0 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
2c0d0 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ding..**.** ^The
2c0e0 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
2c0f0 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
2c100 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
2c110 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
2c120 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
2c130 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
2c140 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2c150 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  nt to these inte
2c160 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65  rfaces is a [pre
2c170 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c180 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  ..** ^These func
2c190 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
2c1a0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
2c1b0 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
2c1c0 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
2c1d0 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
2c1e0 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
2c1f0 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
2c200 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  n argument..** ^
2c210 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
2c220 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30  lumn is column 0
2c230 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
2c240 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  nes..**.** ^If t
2c250 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
2c260 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
2c270 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
2c280 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73  pression or.** s
2c290 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
2c2a0 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
2c2b0 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
2c2c0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
2c2d0 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20  eturn.** NULL.  
2c2e0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d  ^These routine m
2c2f0 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e  ight also return
2c300 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72   NULL if a memor
2c310 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
2c320 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e  or.** occurs.  ^
2c330 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
2c340 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
2c350 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
2c360 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2c370 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68  .** or column th
2c380 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
2c390 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
2c3a0 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
2c3b0 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74   ^As with all ot
2c3c0 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
2c3d0 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d   those whose nam
2c3e0 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22  es end with "16"
2c3f0 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
2c400 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
2c410 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  s and the other 
2c420 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2c430 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54   UTF-8..**.** ^T
2c440 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
2c450 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
2c460 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
2c470 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
2c480 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
2c490 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
2c4a0 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
2c4b0 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a  sor symbol..**.*
2c4c0 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
2c4d0 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
2c4e0 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
2c4f0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
2c500 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
2c510 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c520 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
2c530 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
2c540 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2c550 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
2c560 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
2c570 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
2c580 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
2c590 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2c5a0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2c5b0 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
2c5c0 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
2c5d0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b  * for the same [
2c5e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c5f0 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
2c600 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20  olumn.** at the 
2c610 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
2c620 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
2c630 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e  ndefined..*/.con
2c640 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2c650 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
2c660 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2c670 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2c680 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2c690 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2c6a0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2c6b0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
2c6c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2c6d0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
2c6e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2c6f0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2c700 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
2c710 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
2c720 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
2c730 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2c740 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
2c750 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2c760 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2c770 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2c780 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
2c790 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2c7a0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
2c7b0 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
2c7c0 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
2c7d0 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
2c7e0 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61  * ^(The first pa
2c7f0 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
2c800 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c810 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
2c820 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
2c830 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
2c840 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
2c850 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
2c860 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
2c870 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
2c880 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
2c890 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
2c8a0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
2c8b0 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
2c8c0 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
2c8d0 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
2c8e0 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
2c8f0 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68  .)^  ^If the Nth
2c900 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2c910 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
2c920 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
2c930 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
2c940 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
2c950 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
2c960 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2c970 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
2c980 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a  F-8 encoded..**.
2c990 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
2c9a0 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
2c9b0 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
2c9c0 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
2c9d0 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
2c9e0 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
2c9f0 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
2ca00 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
2ca10 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
2ca20 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
2ca30 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
2ca40 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
2ca50 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
2ca60 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
2ca70 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
2ca80 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
2ca90 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
2caa0 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
2cab0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
2cac0 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  i==0).)^.**.** ^
2cad0 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
2cae0 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
2caf0 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62  ing.  ^So just b
2cb00 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
2cb10 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
2cb20 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
2cb30 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
2cb40 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
2cb50 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
2cb60 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
2cb70 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
2cb80 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
2cb90 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
2cba0 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
2cbb0 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
2cbc0 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e  c not static.  ^
2cbd0 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
2cbe0 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
2cbf0 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
2cc00 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
2cc10 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
2cc20 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
2cc30 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  es..*/.const cha
2cc40 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2cc50 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
2cc60 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
2cc70 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2cc80 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
2cc90 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
2cca0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
2ccb0 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
2ccc0 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
2ccd0 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  ent.**.** After 
2cce0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2ccf0 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
2cd00 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65  prepared using e
2cd10 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
2cd20 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2cd30 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2cd40 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f  are16_v2()] or o
2cd50 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ne of the legacy
2cd60 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
2cd70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2cd80 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
2cd90 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69  repare16()], thi
2cda0 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75  s function.** mu
2cdb0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
2cdc0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
2cdd0 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73  o evaluate the s
2cde0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
2cdf0 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74  The details of t
2ce00 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
2ce10 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
2ce20 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65  ) interface depe
2ce30 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  nd.** on whether
2ce40 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
2ce50 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  as prepared usin
2ce60 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22  g the newer "v2"
2ce70 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73   interface.** [s
2ce80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2ce90 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
2cea0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2ceb0 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c  ] or the older l
2cec0 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
2ced0 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ce [sqlite3_prep
2cee0 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
2cef0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2cf00 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
2cf10 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e  e.** new "v2" in
2cf20 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
2cf30 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61  mended for new a
2cf40 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20  pplications but 
2cf50 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
2cf60 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e  terface will con
2cf70 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70  tinue to be supp
2cf80 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  orted..**.** ^In
2cf90 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2cfa0 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72  rface, the retur
2cfb0 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20  n value will be 
2cfc0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42  either [SQLITE_B
2cfd0 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  USY],.** [SQLITE
2cfe0 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
2cff0 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52  ROW], [SQLITE_ER
2d000 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROR], or [SQLITE
2d010 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69  _MISUSE]..** ^Wi
2d020 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
2d030 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68  rface, any of th
2d040 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20  e other [result 
2d050 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78  codes] or.** [ex
2d060 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
2d070 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65  des] might be re
2d080 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a  turned as well..
2d090 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42  **.** ^[SQLITE_B
2d0a0 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USY] means that 
2d0b0 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
2d0c0 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74  ine was unable t
2d0d0 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a  o acquire the.**
2d0e0 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20   database locks 
2d0f0 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69  it needs to do i
2d100 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65  ts job.  ^If the
2d110 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
2d120 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f  [COMMIT].** or o
2d130 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66  ccurs outside of
2d140 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
2d150 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79  nsaction, then y
2d160 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65  ou can retry the
2d170 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  .** statement.  
2d180 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
2d190 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49   is not a [COMMI
2d1a0 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69  T] and occurs wi
2d1b0 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69  thin an.** expli
2d1c0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
2d1d0 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
2d1e0 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
2d1f0 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
2d200 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
2d210 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f  *.** ^[SQLITE_DO
2d220 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
2d230 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
2d240 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
2d250 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
2d260 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
2d270 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
2d280 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
2d290 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
2d2a0 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
2d2b0 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
2d2c0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2d2d0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
2d2e0 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
2d2f0 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
2d300 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
2d310 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20  .** ^If the SQL 
2d320 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20  statement being 
2d330 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73  executed returns
2d340 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20   any data, then 
2d350 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20  [SQLITE_ROW].** 
2d360 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68  is returned each
2d370 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20   time a new row 
2d380 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79  of data is ready
2d390 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
2d3a0 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72  by the.** caller
2d3b0 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79  . The values may
2d3c0 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69   be accessed usi
2d3d0 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61  ng the [column a
2d3e0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
2d3f0 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ..** sqlite3_ste
2d400 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67  p() is called ag
2d410 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20  ain to retrieve 
2d420 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20  the next row of 
2d430 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  data..**.** ^[SQ
2d440 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e  LITE_ERROR] mean
2d450 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d  s that a run-tim
2d460 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73  e error (such as
2d470 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a   a constraint.**
2d480 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20   violation) has 
2d490 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74  occurred.  sqlit
2d4a0 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
2d4b0 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
2d4c0 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56  gain on.** the V
2d4d0 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74  M. More informat
2d4e0 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64  ion may be found
2d4f0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
2d500 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
2d510 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67  ** ^With the leg
2d520 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61  acy interface, a
2d530 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
2d540 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65  rror code (for e
2d550 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49  xample,.** [SQLI
2d560 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
2d570 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
2d580 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
2d590 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
2d5a0 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
2d5b0 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
2d5c0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2d5d0 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
2d5e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2d5f0 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
2d600 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
2d610 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
2d620 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
2d630 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
2d640 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2d650 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
2d660 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
2d670 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
2d680 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
2d690 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
2d6a0 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
2d6b0 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72   called on a [pr
2d6c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d6d0 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
2d6e0 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
2d6f0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
2d700 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
2d710 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20  one that had.** 
2d720 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
2d730 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
2d740 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
2d750 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
2d760 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
2d770 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
2d780 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2d790 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
2d7a0 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
2d7b0 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
2d7c0 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
2d7d0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72   time..**.** For
2d7e0 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66   all versions of
2d7f0 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e   SQLite up to an
2d800 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e  d including 3.6.
2d810 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a  23.1, a call to.
2d820 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2d830 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65  t()] was require
2d840 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
2d850 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20  step() returned 
2d860 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65  anything.** othe
2d870 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
2d880 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73  OW] before any s
2d890 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
2d8a0 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  tion of.** sqlit
2d8b0 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c  e3_step().  Fail
2d8c0 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65  ure to reset the
2d8d0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2d8e0 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  ent using .** [s
2d8f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2d900 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  would result in 
2d910 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  an [SQLITE_MISUS
2d920 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a  E] return from.*
2d930 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2d940 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72  .  But after ver
2d950 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73  sion 3.6.23.1, s
2d960 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65  qlite3_step() be
2d970 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b  gan.** calling [
2d980 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2d990 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
2d9a0 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61  n this circumsta
2d9b0 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68  nce rather.** th
2d9c0 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  an returning [SQ
2d9d0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54  LITE_MISUSE].  T
2d9e0 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69  his is not consi
2d9f0 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62  dered a compatib
2da00 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62  ility.** break b
2da10 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69  ecause any appli
2da20 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72  cation that ever
2da30 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c   receives an SQL
2da40 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72  ITE_MISUSE error
2da50 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79  .** is broken by
2da60 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
2da70 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
2da80 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c  UTORESET] compil
2da90 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a  e-time option.**
2daa0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2dab0 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61  restore the lega
2dac0 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  cy behavior..**.
2dad0 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
2dae0 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
2daf0 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
2db00 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71  nterface, the sq
2db10 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20  lite3_step().** 
2db20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72  API always retur
2db30 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72  ns a generic err
2db40 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45  or code, [SQLITE
2db50 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69  _ERROR], followi
2db60 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20  ng any.** error 
2db70 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2db80 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51  TE_BUSY] and [SQ
2db90 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59  LITE_MISUSE].  Y
2dba0 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20  ou must call.** 
2dbb0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2dbc0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
2dbd0 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64  nalize()] in ord
2dbe0 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f  er to find one o
2dbf0 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  f the.** specifi
2dc00 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
2dc10 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63  that better desc
2dc20 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e  ribes the error.
2dc30 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61  .** We admit tha
2dc40 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66  t this is a goof
2dc50 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70  y design.  The p
2dc60 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20  roblem has been 
2dc70 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  fixed.** with th
2dc80 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2dc90 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72  .  If you prepar
2dca0 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51  e all of your SQ
2dcb0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
2dcc0 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
2dcd0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2dce0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2dcf0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2dd00 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68  instead.** of th
2dd10 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
2dd20 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
2dd30 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2dd40 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  e16()] interface
2dd50 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d  s,.** then the m
2dd60 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
2dd70 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
2dd80 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
2dd90 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
2dda0 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
2ddb0 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  of the "v2" inte
2ddc0 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
2ddd0 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nded..*/.int sql
2dde0 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
2ddf0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2de00 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
2de10 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2de20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a  a result set.**.
2de30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2de40 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e  data_count(P) in
2de50 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2de60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
2de70 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20  lumns in the.** 
2de80 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
2de90 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
2dea0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2deb0 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20  ment] P..** ^If 
2dec0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ded0 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61  nt P does not ha
2dee0 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79  ve results ready
2def0 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76   to return.** (v
2df00 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ia calls to the 
2df10 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2df20 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f  int | sqlite3_co
2df30 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20  lumn_*()] of.** 
2df40 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e  interfaces) then
2df50 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2df60 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30  unt(P) returns 0
2df70 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2df80 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2df90 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74  routine also ret
2dfa0 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61  urns 0 if P is a
2dfb0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2dfc0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2dfd0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
2dfe0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
2dff0 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  f the previous c
2e000 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2e010 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
2e020 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  rned [SQLITE_DON
2e030 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  E].  ^The sqlite
2e040 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a  3_data_count(P).
2e050 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e  ** will return n
2e060 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69  on-zero if previ
2e070 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ous call to [sql
2e080 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
2e090 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54  turned.** [SQLIT
2e0a0 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69  E_ROW], except i
2e0b0 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68  n the case of th
2e0c0 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d  e [PRAGMA increm
2e0d0 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a  ental_vacuum].**
2e0e0 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73   where it always
2e0f0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69   returns zero si
2e100 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66  nce each step of
2e110 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70   that multi-step
2e120 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72  .** pragma retur
2e130 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  ns 0 columns of 
2e140 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  data..**.** See 
2e150 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63  also: [sqlite3_c
2e160 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a  olumn_count()].*
2e170 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61  /.int sqlite3_da
2e180 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  ta_count(sqlite3
2e190 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2e1a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e1b0 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61  Fundamental Data
2e1c0 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  types.** KEYWORD
2e1d0 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
2e1e0 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c  *.** ^(Every val
2e1f0 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
2e200 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
2e210 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
2e220 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
2e230 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
2e240 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
2e250 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
2e260 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2e270 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
2e280 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
2e290 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
2e2a0 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
2e2b0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
2e2c0 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65   are codes for e
2e2d0 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70  ach of those typ
2e2e0 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  es..**.** Note t
2e2f0 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hat the SQLITE_T
2e300 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73  EXT constant was
2e310 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51   also used in SQ
2e320 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a  Lite version 2.*
2e330 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65  * for a complete
2e340 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61  ly different mea
2e350 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20  ning.  Software 
2e360 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
2e370 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74  st both.** SQLit
2e380 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  e version 2 and 
2e390 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
2e3a0 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49   should use SQLI
2e3b0 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a  TE3_TEXT, not.**
2e3c0 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
2e3d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2e3e0 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
2e3f0 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
2e400 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2e410 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
2e420 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
2e430 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
2e440 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
2e450 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
2e460 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
2e470 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
2e480 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
2e490 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
2e4a0 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
2e4b0 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65  EF: Result Value
2e4c0 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a  s From A Query.*
2e4d0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c  * KEYWORDS: {col
2e4e0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
2e4f0 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ions}.**.** Thes
2e500 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20  e routines form 
2e510 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22  the "result set"
2e520 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
2e530 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2e540 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
2e550 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e  tion about a sin
2e560 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
2e570 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73  e current.** res
2e580 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65  ult row of a que
2e590 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63  ry.  ^In every c
2e5a0 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72  ase the first ar
2e5b0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
2e5c0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70  ter.** to the [p
2e5d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e5e0 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67  t] that is being
2e5f0 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20   evaluated (the 
2e600 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a  [sqlite3_stmt*].
2e610 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75  ** that was retu
2e620 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  rned from [sqlit
2e630 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2e640 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76   or one of its v
2e650 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20  ariants).** and 
2e660 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
2e670 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
2e680 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66   of the column f
2e690 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61  or which informa
2e6a0 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
2e6b0 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65  e returned. ^The
2e6c0 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
2e6d0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2e6e0 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78  et has the index
2e6f0 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62   0..** ^The numb
2e700 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2e710 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20   the result can 
2e720 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
2e730 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2e740 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e  column_count()].
2e750 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
2e760 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
2e770 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70   not currently p
2e780 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20  oint to a valid 
2e790 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a  row, or if the.*
2e7a0 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69  * column index i
2e7b0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
2e7c0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e  the result is un
2e7d0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73  defined..** Thes
2e7e0 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f  e routines may o
2e7f0 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
2e800 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  en the most rece
2e810 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
2e820 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
2e830 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  as returned [SQL
2e840 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69  ITE_ROW] and nei
2e850 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
2e860 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73  _reset()] nor [s
2e870 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2e880 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  )] have been cal
2e890 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79  led subsequently
2e8a0 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74  ..** If any of t
2e8b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
2e8c0 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  e called after [
2e8d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2e8e0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2e8f0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  finalize()] or a
2e900 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
2e910 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
2e920 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20  ed.** something 
2e930 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2e940 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73  TE_ROW], the res
2e950 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2e960 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  ed..** If [sqlit
2e970 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
2e980 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2e990 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2e9a0 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63  lize()].** are c
2e9b0 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66  alled from a dif
2e9c0 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68  ferent thread wh
2e9d0 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  ile any of these
2e9e0 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
2e9f0 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74   pending, then t
2ea00 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
2ea10 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2ea20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
2ea30 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
2ea40 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ne returns the.*
2ea50 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
2ea60 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
2ea70 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
2ea80 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
2ea90 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
2eaa0 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75  lumn.  ^The retu
2eab0 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
2eac0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
2ead0 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
2eae0 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
2eaf0 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
2eb00 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
2eb10 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76  TE_NULL].  The v
2eb20 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
2eb30 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2eb40 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
2eb50 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
2eb60 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65  no type.** conve
2eb70 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
2eb80 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65  rred as describe
2eb90 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20  d below.  After 
2eba0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
2ebb0 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n,.** the value 
2ebc0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2ebd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2ebe0 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
2ebf0 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
2ec00 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
2ec10 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
2ec20 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
2ec30 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
2ec40 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
2ec50 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
2ec60 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
2ec70 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
2ec80 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
2ec90 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
2eca0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
2ecb0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2ecc0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2ecd0 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
2ece0 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
2ecf0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2ed00 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
2ed10 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
2ed20 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63  column_bytes() c
2ed30 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
2ed40 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61  tring to UTF-8 a
2ed50 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
2ed60 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2ed70 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
2ed80 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
2ed90 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
2eda0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2edb0 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  tes() uses.** [s
2edc0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2edd0 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
2ede0 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
2edf0 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72  F-8 string and r
2ee00 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
2ee10 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2ee20 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2ee30 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2ee40 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
2ee50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ee60 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  es() returns zer
2ee70 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  o..**.** ^If the
2ee80 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
2ee90 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  B or UTF-16 stri
2eea0 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
2eeb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2eec0 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  16().** routine 
2eed0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2eee0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2eef0 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
2ef00 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2ef10 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38  esult is a UTF-8
2ef20 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
2ef30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2ef40 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a  es16() converts.
2ef50 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
2ef60 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e   UTF-16 and then
2ef70 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2ef80 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
2ef90 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2efa0 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
2efb0 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
2efc0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2efd0 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
2efe0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
2eff0 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
2f000 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20  lue to a UTF-16 
2f010 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2f020 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
2f030 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2f040 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
2f050 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
2f060 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
2f070 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2f080 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
2f090 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  .**.** ^The valu
2f0a0 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
2f0b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f0c0 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20  ytes()] and .** 
2f0d0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2f0e0 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f  bytes16()] do no
2f0f0 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65  t include the ze
2f100 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61  ro terminators a
2f110 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20  t the end.** of 
2f120 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f  the string.  ^Fo
2f130 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76  r clarity: the v
2f140 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
2f150 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
2f160 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
2f170 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d [sqlite3_colum
2f180 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65  n_bytes16()] are
2f190 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
2f1a0 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  * bytes in the s
2f1b0 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e  tring, not the n
2f1c0 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
2f1d0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69  ers..**.** ^Stri
2f1e0 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
2f1f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f200 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ext() and sqlite
2f210 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2f220 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79  ),.** even empty
2f230 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c   strings, are al
2f240 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
2f250 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  ated.  ^The retu
2f260 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d  rn.** value from
2f270 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f280 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72  blob() for a zer
2f290 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73  o-length BLOB is
2f2a0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2f2b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65  .**.** ^The obje
2f2c0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ct returned by [
2f2d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2f2e0 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a  alue()] is an.**
2f2f0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2f300 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2f310 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65  ect.  An unprote
2f320 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2f330 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79  ue object.** may
2f340 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
2f350 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  th [sqlite3_bind
2f360 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
2f370 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2f380 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
2f390 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
2f3a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2f3b0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2f3c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2f3d0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
2f3e0 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
2f3f0 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
2f400 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
2f410 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
2f420 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
2f430 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
2f440 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
2f450 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2f460 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68  ytes()], then th
2f470 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2f480 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
2f490 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74  hese routines at
2f4a0 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74  tempt to convert
2f4b0 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65   the value where
2f4c0 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e   appropriate.  ^
2f4d0 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
2f4e0 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  if the internal 
2f4f0 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69  representation i
2f500 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65  s FLOAT and a te
2f510 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  xt result.** is 
2f520 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69  requested, [sqli
2f530 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2f540 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
2f550 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68  ly to perform th
2f560 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e.** conversion 
2f570 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
2f580 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  ^(The following 
2f590 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68  table details th
2f5a0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a  e conversions.**
2f5b0 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65   that are applie
2f5c0 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d:.**.** <blockq
2f5d0 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
2f5e0 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
2f5f0 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c  tr><th> Internal
2f600 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65  <br>Type <th> Re
2f610 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20  quested<br>Type 
2f620 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e  <th>  Conversion
2f630 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
2f640 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e   NULL    <td> IN
2f650 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73  TEGER   <td> Res
2f660 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e  ult is 0.** <tr>
2f670 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2f680 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2f690 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a  > Result is 0.0.
2f6a0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2f6b0 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  L    <td>   TEXT
2f6c0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
2f6d0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2f6e0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
2f6f0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
2f700 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
2f710 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
2f720 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
2f730 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46  INTEGER  <td>  F
2f740 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
2f750 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65  vert from intege
2f760 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74  r to float.** <t
2f770 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2f780 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2f790 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
2f7a0 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67  ing of the integ
2f7b0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
2f7c0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42  NTEGER  <td>   B
2f7d0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
2f7e0 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58   as INTEGER->TEX
2f7f0 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  T.** <tr><td>  F
2f800 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOAT   <td> INTE
2f810 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
2f820 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
2f830 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2f840 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2f850 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
2f860 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
2f870 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
2f880 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
2f890 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  LOB    <td> [CAS
2f8a0 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74  T] to BLOB.** <t
2f8b0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2f8c0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2f8d0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
2f8e0 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
2f8f0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
2f900 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b   FLOAT    <td> [
2f910 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a  CAST] to REAL.**
2f920 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
2f930 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2f940 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
2f950 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2f960 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
2f970 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
2f980 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
2f990 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2f9a0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2f9b0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52  <td> [CAST] to R
2f9c0 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EAL.** <tr><td> 
2f9d0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
2f9e0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
2f9f0 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
2fa00 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
2fa10 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
2fa20 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
2fa30 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76  * The table abov
2fa40 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63  e makes referenc
2fa50 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20  e to standard C 
2fa60 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e  library function
2fa70 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20  s atoi().** and 
2fa80 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20  atof().  SQLite 
2fa90 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20  does not really 
2faa0 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69  use these functi
2fab0 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73  ons.  It has its
2fac0 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65  .** own equivale
2fad0 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74  nt internal rout
2fae0 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28  ines.  The atoi(
2faf0 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d  ) and atof() nam
2fb00 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69  es are.** used i
2fb10 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20  n the table for 
2fb20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61  brevity and beca
2fb30 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d  use they are fam
2fb40 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a  iliar to most.**
2fb50 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a   C programmers..
2fb60 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2fb70 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
2fb80 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
2fb90 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
2fba0 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
2fbb0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2fbc0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
2fbd0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2fbe0 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
2fbf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2fc00 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
2fc10 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
2fc20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
2fc30 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
2fc40 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
2fc50 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
2fc60 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
2fc70 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
2fc80 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2fc90 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
2fca0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2fcb0 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
2fcc0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
2fcd0 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
2fce0 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
2fcf0 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
2fd00 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
2fd10 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
2fd20 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
2fd30 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2fd40 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
2fd50 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
2fd60 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2fd70 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
2fd80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2fd90 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
2fda0 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
2fdb0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
2fdc0 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
2fdd0 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
2fde0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2fdf0 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
2fe00 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
2fe10 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
2fe20 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
2fe30 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
2fe40 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
2fe50 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
2fe60 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
2fe70 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
2fe80 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
2fe90 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
2fea0 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
2feb0 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
2fec0 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
2fed0 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
2fee0 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
2fef0 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
2ff00 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
2ff10 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2ff20 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
2ff30 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
2ff40 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c  r references wil
2ff50 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
2ff60 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
2ff70 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
2ff80 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
2ff90 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
2ffa0 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
2ffb0 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a  ometimes they.**
2ffc0 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c   are not possibl
2ffd0 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
2ffe0 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
2fff0 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
30000 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ted..**.** The s
30010 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73  afest and easies
30020 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f  t to remember po
30030 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b  licy is to invok
30040 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
30050 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  .** in one of th
30060 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73  e following ways
30070 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
30080 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
30090 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f  umn_text() follo
300a0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
300b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
300c0 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
300d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
300e0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
300f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
30100 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
30110 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
30120 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65  text16() followe
30130 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
30140 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c  umn_bytes16()</l
30150 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
30160 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
30170 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
30180 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
30190 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69  _text(),.** sqli
301a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
301b0 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ), or sqlite3_co
301c0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
301d0 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
301e0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20   result.** into 
301f0 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d  the desired form
30200 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
30210 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30220 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  ytes() or.** sql
30230 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
30240 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68  s16() to find th
30250 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
30260 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
30270 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71  x calls.** to sq
30280 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30290 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  t() or sqlite3_c
302a0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
302b0 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  h calls to.** sq
302c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
302d0 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e  es16(), and do n
302e0 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ot mix calls to 
302f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
30300 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20  ext16().** with 
30310 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
30320 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
30330 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e  .**.** ^The poin
30340 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
30350 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
30360 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
30370 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
30380 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
30390 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
303a0 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
303b0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
303c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
303d0 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
303e0 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  d.  ^The memory 
303f0 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
30400 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
30410 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
30420 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
30430 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70   Do <b>not</b> p
30440 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
30450 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
30460 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
30470 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
30480 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
30490 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a  )], etc. into.**
304a0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
304b0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20  ]..**.** ^(If a 
304c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
304d0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
304e0 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61  uring the evalua
304f0 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  tion of any.** o
30500 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
30510 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75  , a default valu
30520 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  e is returned.  
30530 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
30540 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74  e.** is either t
30550 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68  he integer 0, th
30560 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  e floating point
30570 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20   number 0.0, or 
30580 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
30590 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63  r.  Subsequent c
305a0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
305b0 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c  _errcode()] will
305c0 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
305d0 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a  TE_NOMEM].)^.*/.
305e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
305f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
30600 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30610 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
30620 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
30630 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  es(sqlite3_stmt*
30640 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
30650 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30660 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
30670 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
30680 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
30690 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73  _column_double(s
306a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
306b0 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
306c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28  ite3_column_int(
306d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
306e0 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
306f0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
30700 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c  column_int64(sql
30710 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
30720 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  iCol);.const uns
30730 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
30740 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
30750 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30760 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
30770 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
30780 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69  lumn_text16(sqli
30790 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
307a0 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
307b0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
307c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
307d0 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
307e0 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63  value *sqlite3_c
307f0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69  olumn_value(sqli
30800 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
30810 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Col);../*.** CAP
30820 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41  I3REF: Destroy A
30830 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
30840 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
30850 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
30860 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  nalize() functio
30870 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64  n is called to d
30880 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65  elete a [prepare
30890 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
308a0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
308b0 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
308c0 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
308d0 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20   encountered no 
308e0 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20  errors.** or if 
308f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
30900 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c   never been eval
30910 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69  uated, then sqli
30920 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72  te3_finalize() r
30930 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45  eturns.** SQLITE
30940 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  _OK.  ^If the mo
30950 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
30960 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e  tion of statemen
30970 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  t S failed, then
30980 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  .** sqlite3_fina
30990 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20  lize(S) returns 
309a0 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  the appropriate 
309b0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a  [error code] or.
309c0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  ** [extended err
309d0 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
309e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
309f0 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65  alize(S) routine
30a00 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
30a10 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
30a20 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63  ng.** the life c
30a30 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65  ycle of [prepare
30a40 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a  d statement] S:.
30a50 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d  ** before statem
30a60 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76  ent S is ever ev
30a70 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a  aluated, after.*
30a80 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61  * one or more ca
30a90 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
30aa0 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74  reset()], or aft
30ab0 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74  er any call.** t
30ac0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
30ad0 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  )] regardless of
30ae0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
30af0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
30b00 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65  s.** completed e
30b10 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  xecution..**.** 
30b20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65  ^Invoking sqlite
30b30 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20  3_finalize() on 
30b40 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
30b50 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
30b60 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  op..**.** The ap
30b70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66  plication must f
30b80 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70  inalize every [p
30b90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30ba0 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61  t] in order to a
30bb0 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65  void.** resource
30bc0 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61   leaks.  It is a
30bd0 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20   grievous error 
30be0 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
30bf0 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73  ion to try to us
30c00 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20  e.** a prepared 
30c10 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
30c20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
30c30 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20  lized.  Any use 
30c40 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a  of a prepared.**
30c50 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
30c60 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
30c70 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c  alized can resul
30c80 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  t in undefined a
30c90 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  nd.** undesirabl
30ca0 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20  e behavior such 
30cb0 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64  as segfaults and
30cc0 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e   heap corruption
30cd0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
30ce0 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
30cf0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
30d00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30d10 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
30d20 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
30d30 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ct.**.** The sql
30d40 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
30d50 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
30d60 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
30d70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
30d80 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
30d90 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
30da0 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
30db0 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
30dc0 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d   ^Any SQL statem
30dd0 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68  ent variables th
30de0 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f  at had values bo
30df0 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e  und to them usin
30e00 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
30e10 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
30e20 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41  lite3_bind_*() A
30e30 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72  PI] retain their
30e40 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20   values..** Use 
30e50 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
30e60 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65  indings()] to re
30e70 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73  set the bindings
30e80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
30e90 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
30ea0 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
30eb0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
30ec0 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62  tatement] S.** b
30ed0 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
30ee0 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
30ef0 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ram..**.** ^If t
30f00 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
30f10 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
30f20 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
30f30 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
30f40 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
30f50 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
30f60 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
30f70 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c  ],.** or if [sql
30f80 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
30f90 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
30fa0 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
30fb0 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  .** then [sqlite
30fc0 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
30fd0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
30fe0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
30ff0 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
31000 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
31010 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
31020 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31030 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
31040 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
31050 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
31060 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
31070 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
31080 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
31090 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
310a0 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
310b0 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
310c0 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
310d0 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33   of any [sqlite3
310e0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69  _bind_blob|bindi
310f0 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65  ngs] on the [pre
31100 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31110 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74   S..*/.int sqlit
31120 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33  e3_reset(sqlite3
31130 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
31140 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31150 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69  Create Or Redefi
31160 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73  ne SQL Functions
31170 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
31180 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
31190 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45   routines}.** KE
311a0 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
311b0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
311c0 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45   function}.** KE
311d0 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
311e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
311f0 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
31200 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
31210 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79  ns (collectively
31220 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74   known as "funct
31230 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
31240 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75  tines").** are u
31250 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66  sed to add SQL f
31260 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
31270 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64  egates or to red
31280 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69  efine the behavi
31290 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e  or.** of existin
312a0 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  g SQL functions 
312b0 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  or aggregates.  
312c0 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65  The only differe
312d0 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20  nces between.** 
312e0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
312f0 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f  re the text enco
31300 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f  ding expected fo
31310 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  r.** the second 
31320 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e  parameter (the n
31330 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ame of the funct
31340 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65  ion being create
31350 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72  d).** and the pr
31360 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63  esence or absenc
31370 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f  e of a destructo
31380 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a  r callback for.*
31390 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
313a0 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a  n data pointer..
313b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
313c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
313d0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
313e0 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68  ection] to which
313f0 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63   the SQL.** func
31400 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64  tion is to be ad
31410 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70  ded.  ^If an app
31420 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f  lication uses mo
31430 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61  re than one data
31440 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
31450 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74  on then applicat
31460 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
31470 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62  functions must b
31480 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61  e added.** to ea
31490 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
314a0 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c  ection separatel
314b0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  y..**.** ^The se
314c0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
314d0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
314e0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
314f0 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a  o be created or.
31500 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e  ** redefined.  ^
31510 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  The length of th
31520 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65  e name is limite
31530 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69  d to 255 bytes i
31540 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70  n a UTF-8.** rep
31550 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63  resentation, exc
31560 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65  lusive of the ze
31570 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro-terminator.  
31580 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e  ^Note that the n
31590 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69  ame.** length li
315a0 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20  mit is in UTF-8 
315b0 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61  bytes, not chara
315c0 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36  cters nor UTF-16
315d0 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e   bytes.  .** ^An
315e0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65  y attempt to cre
315f0 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  ate a function w
31600 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d  ith a longer nam
31610 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74  e.** will result
31620 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   in [SQLITE_MISU
31630 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e  SE] being return
31640 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  ed..**.** ^The t
31650 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28  hird parameter (
31660 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20  nArg).** is the 
31670 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
31680 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c  nts that the SQL
31690 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
316a0 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e  aggregate takes.
316b0 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65   ^If this parame
316c0 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ter is -1, then 
316d0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
316e0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
316f0 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75   may take any nu
31700 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
31710 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  s between 0 and 
31720 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74  the limit.** set
31730 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   by [sqlite3_lim
31740 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  it]([SQLITE_LIMI
31750 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29  T_FUNCTION_ARG])
31760 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a  .  If the third.
31770 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ** parameter is 
31780 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20  less than -1 or 
31790 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37  greater than 127
317a0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
317b0 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e  or is.** undefin
317c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
317d0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c  ourth parameter,
317e0 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69   eTextRep, speci
317f0 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51  fies what.** [SQ
31800 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74  LITE_UTF8 | text
31810 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20   encoding] this 
31820 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65  SQL function pre
31830 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20  fers for.** its 
31840 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65  parameters.  The
31850 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
31860 75 6c 64 20 73 65 74 20 74 68 69 73 20 70 61 72  uld set this par
31870 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51  ameter to.** [SQ
31880 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66  LITE_UTF16LE] if
31890 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d   the function im
318a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76  plementation inv
318b0 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  okes .** [sqlite
318c0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
318d0 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c  ()] on an input,
318e0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
318f0 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69  6BE] if the.** i
31900 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
31910 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76  vokes [sqlite3_v
31920 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d  alue_text16be()]
31930 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72   on an input, or
31940 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
31950 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76  6] if [sqlite3_v
31960 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69  alue_text16()] i
31970 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49  s used, or [SQLI
31980 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65  TE_UTF8].** othe
31990 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d  rwise.  ^The sam
319a0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d  e SQL function m
319b0 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
319c0 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
319d0 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65  using.** differe
319e0 6e 74 20 70 72 65 66 65 72 72 65 64 20 74 65 78  nt preferred tex
319f0 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74  t encodings, wit
31a00 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c  h different impl
31a10 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a  ementations for.
31a20 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67  ** each encoding
31a30 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69  ..** ^When multi
31a40 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
31a50 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
31a60 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
31a70 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
31a80 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
31a90 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
31aa0 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
31ab0 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
31ac0 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rsion..**.** ^Th
31ad0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
31ae0 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c  er may optionall
31af0 79 20 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b  y be ORed with [
31b00 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
31b10 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e  STIC].** to sign
31b20 61 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e 63  al that the func
31b30 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73  tion will always
31b40 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65   return the same
31b50 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a   result given.**
31b60 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73   the same inputs
31b70 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65   within a single
31b80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
31b90 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69   Most SQL functi
31ba0 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72  ons are.** deter
31bb0 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62  ministic.  The b
31bc0 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28  uilt-in [random(
31bd0 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  )] SQL function 
31be0 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  is an example of
31bf0 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74   a.** function t
31c00 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72  hat is not deter
31c10 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53  ministic.  The S
31c20 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e  QLite query plan
31c30 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a  ner is able to.*
31c40 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69  * perform additi
31c50 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f  onal optimizatio
31c60 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73  ns on determinis
31c70 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73  tic functions, s
31c80 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20  o use.** of the 
31c90 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e  [SQLITE_DETERMIN
31ca0 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72  ISTIC] flag is r
31cb0 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65  ecommended where
31cc0 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a   possible..**.**
31cd0 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72   ^(The fifth par
31ce0 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
31cf0 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
31d00 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
31d10 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75  ion of the.** fu
31d20 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
31d30 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
31d40 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71  ointer using [sq
31d50 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
31d60 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  )].)^.**.** ^The
31d70 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20   sixth, seventh 
31d80 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d  and eighth param
31d90 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
31da0 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
31db0 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
31dc0 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
31dd0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
31de0 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
31df0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
31e00 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c  gregate. ^A scal
31e10 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
31e20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
31e30 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
31e40 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
31e50 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70  ack only; NULL p
31e60 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20  ointers must be 
31e70 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53  passed as the xS
31e80 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a  tep and xFinal.*
31e90 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41  * parameters. ^A
31ea0 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
31eb0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
31ec0 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
31ed0 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20  ion of xStep.** 
31ee0 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
31ef0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74  ULL pointer must
31f00 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78   be passed for x
31f10 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65  Func. ^To delete
31f20 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20   an existing.** 
31f30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  SQL function or 
31f40 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20  aggregate, pass 
31f50 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f  NULL pointers fo
31f60 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
31f70 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
31f80 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  s..**.** ^(If th
31f90 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  e ninth paramete
31fa0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
31fb0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
31fc0 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a  ) is not NULL,.*
31fd0 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73  * then it is des
31fe0 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20  tructor for the 
31ff0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
32000 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68   pointer. .** Th
32010 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
32020 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
32030 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c   function is del
32040 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20  eted, either by 
32050 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61  being.** overloa
32060 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20  ded or when the 
32070 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32080 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a  ion closes.)^.**
32090 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
320a0 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64   is also invoked
320b0 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a   if the call to.
320c0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
320d0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
320e0 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20  fails..** ^When 
320f0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63  the destructor c
32100 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74  allback of the t
32110 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  enth parameter i
32120 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a  s invoked, it.**
32130 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e   is passed a sin
32140 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
32150 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ch is a copy of 
32160 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
32170 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72  data .** pointer
32180 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66   which was the f
32190 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  ifth parameter t
321a0 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
321b0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a  _function_v2()..
321c0 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72  **.** ^It is per
321d0 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
321e0 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
321f0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
32200 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
32210 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
32220 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
32230 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
32240 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
32250 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
32260 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
32270 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
32280 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75    ^SQLite will u
32290 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
322a0 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f  entation that mo
322b0 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
322c0 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
322d0 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
322e0 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
322f0 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d    ^A function im
32300 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
32310 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  h a non-negative
32320 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74  .** nArg paramet
32330 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d  er is a better m
32340 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
32350 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
32360 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65  ion with.** a ne
32370 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41  gative nArg.  ^A
32380 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
32390 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65  the preferred te
323a0 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d  xt encoding.** m
323b0 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62  atches the datab
323c0 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
323d0 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63  a better.** matc
323e0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
323f0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
32400 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
32410 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74  t.  .** ^A funct
32420 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
32430 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
32440 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46  e is between UTF
32450 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65  16le and UTF16be
32460 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20  .** is a closer 
32470 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
32480 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
32490 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
324a0 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65  nce is.** betwee
324b0 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36  n UTF8 and UTF16
324c0 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69  ..**.** ^Built-i
324d0 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  n functions may 
324e0 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79  be overloaded by
324f0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
32500 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
32510 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70  ns..**.** ^An ap
32520 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32530 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65  d function is pe
32540 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20  rmitted to call 
32550 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
32560 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77  interfaces.  How
32570 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73  ever, such calls
32580 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f   must not.** clo
32590 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
325a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66  connection nor f
325b0 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74  inalize or reset
325c0 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a   the prepared.**
325d0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68   statement in wh
325e0 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ich the function
325f0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
32600 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
32610 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73  te_function(.  s
32620 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
32630 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
32640 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
32650 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
32660 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
32670 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
32680 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
32690 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
326a0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
326b0 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
326c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
326d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
326e0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
326f0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
32700 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
32710 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
32720 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  on16(.  sqlite3 
32730 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  *db,.  const voi
32740 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
32750 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
32760 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
32770 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
32780 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
32790 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
327a0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
327b0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
327c0 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
327d0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
327e0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
327f0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
32800 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
32810 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
32820 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a  te_function_v2(.
32830 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
32840 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
32850 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
32860 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
32870 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
32880 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
32890 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
328a0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
328b0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
328c0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
328d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
328e0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
328f0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
32900 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
32910 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  text*),.  void(*
32920 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
32930 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
32940 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69  REF: Text Encodi
32950 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ngs.**.** These 
32960 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20  constant define 
32970 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68  integer codes th
32980 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65  at represent the
32990 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74   various.** text
329a0 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f   encodings suppo
329b0 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  rted by SQLite..
329c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
329d0 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20  E_UTF8          
329e0 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d   1    /* IMP: R-
329f0 33 37 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23  37514-35566 */.#
32a00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
32a10 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 20 20  F16LE        2  
32a20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37    /* IMP: R-0337
32a30 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65 66 69  1-37637 */.#defi
32a40 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42  ne SQLITE_UTF16B
32a50 45 20 20 20 20 20 20 20 20 33 20 20 20 20 2f 2a  E        3    /*
32a60 20 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33 34   IMP: R-51971-34
32a70 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  154 */.#define S
32a80 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
32a90 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
32aa0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
32ab0 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
32ac0 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
32ad0 20 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72      5    /* Depr
32ae0 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e  ecated */.#defin
32af0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
32b00 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
32b10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
32b20 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
32b30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32b40 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73  : Function Flags
32b50 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
32b60 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 4f 52  stants may be OR
32b70 65 64 20 74 6f 67 65 74 68 65 72 20 77 69 74 68  ed together with
32b80 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
32b90 5f 55 54 46 38 20 7c 20 70 72 65 66 65 72 72 65  _UTF8 | preferre
32ba0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  d text encoding]
32bb0 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61   as the fourth a
32bc0 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73  rgument.** to [s
32bd0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
32be0 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69  nction()], [sqli
32bf0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32c00 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
32c10 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32c20 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a  function_v2()]..
32c30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
32c40 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 20  E_DETERMINISTIC 
32c50 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20     0x800../*.** 
32c60 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63  CAPI3REF: Deprec
32c70 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ated Functions.*
32c80 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a  * DEPRECATED.**.
32c90 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
32ca0 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74  ns are [deprecat
32cb0 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74  ed].  In order t
32cc0 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61  o maintain.** ba
32cd0 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
32ce0 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72  ility with older
32cf0 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e   code, these fun
32d00 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
32d10 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72  .** to be suppor
32d20 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ted.  However, n
32d30 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
32d40 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20  should avoid.** 
32d50 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65  the use of these
32d60 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20   functions.  To 
32d70 65 6e 63 6f 75 72 61 67 65 20 70 72 6f 67 72 61  encourage progra
32d80 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69 64 0a 2a  mmers to avoid.*
32d90 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * these function
32da0 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f 74 20 65  s, we will not e
32db0 78 70 6c 61 69 6e 20 77 68 61 74 20 74 68 65 79  xplain what they
32dc0 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20   do..*/.#ifndef 
32dd0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52  SQLITE_OMIT_DEPR
32de0 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45  ECATED.SQLITE_DE
32df0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
32e00 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
32e10 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ount(sqlite3_con
32e20 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  text*);.SQLITE_D
32e30 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
32e40 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71  lite3_expired(sq
32e50 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
32e60 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
32e70 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e  int sqlite3_tran
32e80 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  sfer_bindings(sq
32e90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c  lite3_stmt*, sql
32ea0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
32eb0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
32ec0 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61  nt sqlite3_globa
32ed0 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b  l_recover(void);
32ee0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
32ef0 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  ED void sqlite3_
32f00 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76  thread_cleanup(v
32f10 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  oid);.SQLITE_DEP
32f20 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
32f30 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
32f40 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73  (void(*)(void*,s
32f50 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74  qlite3_int64,int
32f60 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  ),.             
32f70 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73           void*,s
32f80 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23  qlite3_int64);.#
32f90 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
32fa0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67  I3REF: Obtaining
32fb0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61   SQL Function Pa
32fc0 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a  rameter Values.*
32fd0 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75  *.** The C-langu
32fe0 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  age implementati
32ff0 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69  on of SQL functi
33000 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
33010 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20  es uses.** this 
33020 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65  set of interface
33030 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63   routines to acc
33040 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65  ess the paramete
33050 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74  r values on.** t
33060 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61  he function or a
33070 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ggregate..**.** 
33080 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73  The xFunc (for s
33090 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29  calar functions)
330a0 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61   or xStep (for a
330b0 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d  ggregates) param
330c0 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c  eters.** to [sql
330d0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
330e0 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
330f0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33100 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66  tion16()].** def
33110 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  ine callbacks th
33120 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65  at implement the
33130 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
33140 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a  nd aggregates..*
33150 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65  * The 3rd parame
33160 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c  ter to these cal
33170 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72  lbacks is an arr
33180 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
33190 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20  o.** [protected 
331a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
331b0 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69  bjects.  There i
331c0 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76  s one [sqlite3_v
331d0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72  alue] object for
331e0 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74  .** each paramet
331f0 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75  er to the SQL fu
33200 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72  nction.  These r
33210 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
33220 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76   to.** extract v
33230 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b  alues from the [
33240 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
33250 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  bjects..**.** Th
33260 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
33270 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f  k only with [pro
33280 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
33290 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
332a0 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
332b0 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69   use these routi
332c0 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f  nes on an [unpro
332d0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
332e0 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  alue].** object 
332f0 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66  results in undef
33300 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
33310 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
33320 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c  ines work just l
33330 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ike the correspo
33340 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63  nding [column ac
33350 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a  cess functions].
33360 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 74  ** except that t
33370 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
33380 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f  ke a single [pro
33390 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
333a0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
333b0 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
333c0 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  of a [sqlite3_st
333d0 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
333e0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
333f0 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
33400 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
33410 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
33420 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
33430 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  a UTF-16 string.
33440 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
33450 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
33460 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
33470 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
33480 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
33490 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
334a0 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20  alue_text16le() 
334b0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78  interfaces.** ex
334c0 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72  tract UTF-16 str
334d0 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69  ings as big-endi
334e0 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e  an and little-en
334f0 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
33500 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  y..**.** ^(The s
33510 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
33520 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
33530 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
33540 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
33550 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
33560 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
33570 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
33580 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
33590 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
335a0 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
335b0 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
335c0 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
335d0 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
335e0 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
335f0 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
33600 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
33610 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74  r.** words, if t
33620 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74  he value is a st
33630 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20  ring that looks 
33640 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a  like a number).*
33650 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65  * then the conve
33660 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
33670 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ed.  Otherwise n
33680 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
33690 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  urs..** The [SQL
336a0 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
336b0 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
336c0 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
336d0 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c  rned.)^.**.** Pl
336e0 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75  ease pay particu
336f0 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f  lar attention to
33700 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74   the fact that t
33710 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72  he pointer retur
33720 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
33730 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
33740 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
33750 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
33760 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
33770 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
33780 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
33790 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
337a0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
337b0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
337c0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
337d0 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
337e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
337f0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
33800 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
33810 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ()]..**.** These
33820 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
33830 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
33840 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
33850 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
33860 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
33870 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ed the [sqlite3_
33880 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65  value*] paramete
33890 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  rs..*/.const voi
338a0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
338b0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
338c0 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
338d0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
338e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
338f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
33900 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
33910 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c  3_value*);.doubl
33920 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
33930 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76  double(sqlite3_v
33940 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
33950 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71  te3_value_int(sq
33960 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 73  lite3_value*);.s
33970 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
33980 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34  ite3_value_int64
33990 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
339a0 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
339b0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
339c0 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74 65  alue_text(sqlite
339d0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
339e0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
339f0 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69  alue_text16(sqli
33a00 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
33a10 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
33a20 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
33a30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
33a40 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
33a50 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
33a60 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6be(sqlite3_valu
33a70 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
33a80 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
33a90 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
33aa0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
33ab0 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69  umeric_type(sqli
33ac0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
33ad0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
33ae0 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
33af0 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a  unction Context.
33b00 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61  **.** Implementa
33b10 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61  tions of aggrega
33b20 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  te SQL functions
33b30 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75   use this.** rou
33b40 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  tine to allocate
33b50 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72   memory for stor
33b60 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e  ing their state.
33b70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
33b80 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74  t time the sqlit
33b90 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
33ba0 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
33bb0 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20  e is called .** 
33bc0 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
33bd0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
33be0 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ion, SQLite.** a
33bf0 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65  llocates N of me
33c00 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74  mory, zeroes out
33c10 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e   that memory, an
33c20 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  d returns a poin
33c30 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65  ter.** to the ne
33c40 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65  w memory. ^On se
33c50 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
33c60 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ent calls to.** 
33c70 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
33c80 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20  e_context() for 
33c90 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
33ca0 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
33cb0 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d  ance,.** the sam
33cc0 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75  e buffer is retu
33cd0 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61  rned.  Sqlite3_a
33ce0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
33cf0 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a  () is normally.*
33d00 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f  * called once fo
33d10 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  r each invocatio
33d20 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63  n of the xStep c
33d30 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e  allback and then
33d40 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d   one.** last tim
33d50 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61  e when the xFina
33d60 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  l callback is in
33d70 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e  voked.  ^(When n
33d80 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20  o rows match.** 
33d90 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65  an aggregate que
33da0 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20  ry, the xStep() 
33db0 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
33dc0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
33dd0 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  on.** implementa
33de0 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61  tion is never ca
33df0 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28  lled and xFinal(
33e00 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63  ) is called exac
33e10 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20  tly once..** In 
33e20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c  those cases, sql
33e30 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
33e40 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62  ontext() might b
33e50 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  e called for the
33e60 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66  .** first time f
33e70 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61  rom within xFina
33e80 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  l().)^.**.** ^Th
33e90 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
33ea0 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
33eb0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
33ec0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
33ed0 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63  .** when first c
33ee0 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65  alled if N is le
33ef0 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
33f00 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61   to zero or if a
33f10 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
33f20 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ate error occurs
33f30 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d  ..**.** ^(The am
33f40 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c  ount of space al
33f50 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
33f60 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
33f70 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20  text(C,N) is.** 
33f80 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68  determined by th
33f90 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  e N parameter on
33fa0 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75   first successfu
33fb0 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e  l call.  Changin
33fc0 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  g the.** value o
33fd0 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e  f N in subsequen
33fe0 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
33ff0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
34000 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20  ext() within.** 
34010 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
34020 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
34030 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65  ance will not re
34040 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a  size the memory.
34050 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e  ** allocation.)^
34060 20 20 57 69 74 68 69 6e 20 74 68 65 20 78 46 69    Within the xFi
34070 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74  nal callback, it
34080 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f   is customary to
34090 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63   set.** N=0 in c
340a0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
340b0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
340c0 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e  t(C,N) so that n
340d0 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20  o .** pointless 
340e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
340f0 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20  ns occur..**.** 
34100 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69  ^SQLite automati
34110 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
34120 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64  memory allocated
34130 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   by .** sqlite3_
34140 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
34150 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67  t() when the agg
34160 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e  regate query con
34170 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
34180 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
34190 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79  r must be a copy
341a0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
341b0 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51  te3_context | SQ
341c0 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65  L function conte
341d0 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20  xt] that is the 
341e0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a  first parameter.
341f0 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20  ** to the xStep 
34200 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
34210 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20  ck routine that 
34220 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61  implements the a
34230 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63  ggregate.** func
34240 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
34250 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
34260 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
34270 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
34280 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67  which.** the agg
34290 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
342a0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
342b0 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
342c0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
342d0 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
342e0 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29  xt*, int nBytes)
342f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34300 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72  F: User Data For
34310 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
34320 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73   ^The sqlite3_us
34330 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66  er_data() interf
34340 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
34350 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
34360 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68  nter that was th
34370 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61  e pUserData para
34380 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70  meter (the 5th p
34390 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
343a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
343b0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
343c0 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
343d0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
343e0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
343f0 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
34400 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
34410 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
34420 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ned function..**
34430 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
34440 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
34450 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
34460 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
34470 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34480 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
34490 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
344a0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
344b0 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33  ser_data(sqlite3
344c0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
344d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
344e0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
344f0 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
34500 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34510 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
34520 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  dle() interface 
34530 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
34540 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
34550 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
34560 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
34570 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
34580 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
34590 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
345a0 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
345b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
345c0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
345d0 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
345e0 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
345f0 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
34600 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
34610 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  tion..*/.sqlite3
34620 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   *sqlite3_contex
34630 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  t_db_handle(sqli
34640 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
34650 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34660 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
34670 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68  ry Data.**.** Th
34680 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  ese functions ma
34690 79 20 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f  y be used by (no
346a0 6e 2d 61 67 67 72 65 67 61 74 65 29 20 53 51 4c  n-aggregate) SQL
346b0 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a   functions to.**
346c0 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64   associate metad
346d0 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ata with argumen
346e0 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65  t values. If the
346f0 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70   same value is p
34700 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74  assed to.** mult
34710 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73  iple invocations
34720 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c   of the same SQL
34730 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67   function during
34740 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e   query execution
34750 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20  , under.** some 
34760 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68  circumstances th
34770 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74  e associated met
34780 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65  adata may be pre
34790 73 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d  served.  An exam
347a0 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20  ple.** of where 
347b0 74 68 69 73 20 6d 69 67 68 74 20 62 65 20 75 73  this might be us
347c0 65 66 75 6c 20 69 73 20 69 6e 20 61 20 72 65 67  eful is in a reg
347d0 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
347e0 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63  matching.** func
347f0 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c  tion. The compil
34800 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ed version of th
34810 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
34820 73 69 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f 72  sion can be stor
34830 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74  ed as.** metadat
34840 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
34850 68 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74  h the pattern st
34860 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20  ring.  .** Then 
34870 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 70  as long as the p
34880 61 74 74 65 72 6e 20 73 74 72 69 6e 67 20 72 65  attern string re
34890 6d 61 69 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a  mains the same,.
348a0 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20  ** the compiled 
348b0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
348c0 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64  on can be reused
348d0 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20   on multiple.** 
348e0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
348f0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
34900 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
34910 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
34920 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
34930 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
34940 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a  o the metadata.*
34950 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20  * associated by 
34960 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
34970 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69  auxdata() functi
34980 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  on with the Nth 
34990 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75  argument.** valu
349a0 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  e to the applica
349b0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
349c0 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65  ction. ^If there
349d0 20 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a   is no metadata.
349e0 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
349f0 74 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  th the function 
34a00 61 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 20 73  argument, this s
34a10 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
34a20 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  ta() interface.*
34a30 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  * returns a NULL
34a40 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
34a50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74  ^The sqlite3_set
34a60 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
34a70 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65  ) interface save
34a80 73 20 50 20 61 73 20 6d 65 74 61 64 61 74 61 20  s P as metadata 
34a90 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20  for the N-th.** 
34aa0 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
34ab0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
34ac0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e  ned function.  ^
34ad0 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61  Subsequent.** ca
34ae0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67  lls to sqlite3_g
34af0 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 20  et_auxdata(C,N) 
34b00 72 65 74 75 72 6e 20 50 20 66 72 6f 6d 20 74 68  return P from th
34b10 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a  e most recent.**
34b20 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
34b30 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61  data(C,N,P,X) ca
34b40 6c 6c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61  ll if the metada
34b50 74 61 20 69 73 20 73 74 69 6c 6c 20 76 61 6c 69  ta is still vali
34b60 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20  d or.** NULL if 
34b70 74 68 65 20 6d 65 74 61 64 61 74 61 20 68 61 73  the metadata has
34b80 20 62 65 65 6e 20 64 69 73 63 61 72 64 65 64 2e   been discarded.
34b90 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61 63 68 20  .** ^After each 
34ba0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
34bb0 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
34bc0 50 2c 58 29 20 77 68 65 72 65 20 58 20 69 73 20  P,X) where X is 
34bd0 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c  not NULL,.** SQL
34be0 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  ite will invoke 
34bf0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 66  the destructor f
34c00 75 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 20 70  unction X with p
34c10 61 72 61 6d 65 74 65 72 20 50 20 65 78 61 63 74  arameter P exact
34c20 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e  ly.** once, when
34c30 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73   the metadata is
34c40 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53   discarded..** S
34c50 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f  QLite is free to
34c60 20 64 69 73 63 61 72 64 20 74 68 65 20 6d 65 74   discard the met
34c70 61 64 61 74 61 20 61 74 20 61 6e 79 20 74 69 6d  adata at any tim
34c80 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75  e, including: <u
34c90 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20  l>.** <li> when 
34ca0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
34cb0 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
34cc0 65 74 65 72 20 63 68 61 6e 67 65 73 2c 20 6f 72  eter changes, or
34cd0 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73  .** <li> when [s
34ce0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
34cf0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
34d00 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
34d10 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20  d for the.**    
34d20 20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c    SQL statement,
34d30 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e   or.** <li> when
34d40 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
34d50 64 61 74 61 28 29 20 69 73 20 69 6e 76 6f 6b 65  data() is invoke
34d60 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 65 20 73  d again on the s
34d70 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 6f  ame parameter, o
34d80 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67  r.** <li> during
34d90 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 71   the original sq
34da0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
34db0 61 28 29 20 63 61 6c 6c 20 77 68 65 6e 20 61 20  a() call when a 
34dc0 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20  memory .**      
34dd0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
34de0 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e   occurs. </ul>)^
34df0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20  .**.** Note the 
34e00 6c 61 73 74 20 62 75 6c 6c 65 74 20 69 6e 20 70  last bullet in p
34e10 61 72 74 69 63 75 6c 61 72 2e 20 20 54 68 65 20  articular.  The 
34e20 64 65 73 74 72 75 63 74 6f 72 20 58 20 69 6e 20  destructor X in 
34e30 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  .** sqlite3_set_
34e40 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
34e50 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
34e60 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65   immediately, be
34e70 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69  fore the.** sqli
34e80 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
34e90 29 20 69 6e 74 65 72 66 61 63 65 20 65 76 65 6e  ) interface even
34ea0 20 72 65 74 75 72 6e 73 2e 20 20 48 65 6e 63 65   returns.  Hence
34eb0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
34ec0 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64  data().** should
34ed0 20 62 65 20 63 61 6c 6c 65 64 20 6e 65 61 72 20   be called near 
34ee0 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
34ef0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
34f00 74 61 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a  tation and the.*
34f10 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  * function imple
34f20 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
34f30 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75 73   not make any us
34f40 65 20 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a 20  e of P after.** 
34f50 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
34f60 61 74 61 28 29 20 68 61 73 20 62 65 65 6e 20 63  ata() has been c
34f70 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  alled..**.** ^(I
34f80 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61  n practice, meta
34f90 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65  data is preserve
34fa0 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69  d between functi
34fb0 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20  on calls for.** 
34fc0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
34fd0 65 72 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d  ers that are com
34fe0 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61  pile-time consta
34ff0 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c  nts, including l
35000 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
35010 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73   and [parameters
35020 5d 20 61 6e 64 20 65 78 70 72 65 73 73 69 6f 6e  ] and expression
35030 73 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20  s composed from 
35040 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a  the same.)^.**.*
35050 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
35060 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
35070 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
35080 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
35090 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
350a0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
350b0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67  .void *sqlite3_g
350c0 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
350d0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
350e0 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65   N);.void sqlite
350f0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_set_auxdata(sq
35100 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
35110 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f  int N, void*, vo
35120 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  id (*)(void*));.
35130 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35140 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69  : Constants Defi
35150 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73  ning Special Des
35160 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72  tructor Behavior
35170 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
35180 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20   special values 
35190 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74  for the destruct
351a0 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  or that is passe
351b0 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
351c0 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f  inal argument to
351d0 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
351e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
351f0 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  lob()].  ^If the
35200 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61   destructor.** a
35210 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54  rgument is SQLIT
35220 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61  E_STATIC, it mea
35230 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
35240 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63  ent pointer is c
35250 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77  onstant.** and w
35260 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65  ill never change
35270 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e  .  It does not n
35280 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f  eed to be destro
35290 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51  yed.  ^The.** SQ
352a0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76  LITE_TRANSIENT v
352b0 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20  alue means that 
352c0 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c  the content will
352d0 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69   likely change i
352e0 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75  n.** the near fu
352f0 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51  ture and that SQ
35300 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65  Lite should make
35310 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
35320 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
35330 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72  content before r
35340 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
35350 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e  The typedef is n
35360 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b  ecessary to work
35370 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73   around problems
35380 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43   in certain.** C
35390 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f  ++ compilers..*/
353a0 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
353b0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
353c0 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b  or_type)(void*);
353d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
353e0 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71  STATIC      ((sq
353f0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
35400 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65  _type)0).#define
35410 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
35420 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65  T   ((sqlite3_de
35430 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31  structor_type)-1
35440 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
35450 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52  F: Setting The R
35460 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20  esult Of An SQL 
35470 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54  Function.**.** T
35480 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
35490 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46  e used by the xF
354a0 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  unc or xFinal ca
354b0 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20  llbacks that.** 
354c0 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75  implement SQL fu
354d0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
354e0 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20  egates.  See.** 
354f0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
35500 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
35510 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
35520 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
35530 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
35540 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
35550 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
35560 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63  ns work very muc
35570 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61  h like the [para
35580 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66  meter binding] f
35590 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63  amily of.** func
355a0 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69  tions used to bi
355b0 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
355c0 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  t parameters in 
355d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
355e0 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f  nts..** Refer to
355f0 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65   the [SQL parame
35600 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  ter] documentati
35610 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
35620 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
35630 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35640 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20  3_result_blob() 
35650 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
35660 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
35670 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
35680 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
35690 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42  n to be the BLOB
356a0 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69   whose content i
356b0 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20  s pointed.** to 
356c0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
356d0 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63  rameter and whic
356e0 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e  h is N bytes lon
356f0 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  g where N is the
35700 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
35710 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
35720 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
35730 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  eroblob() interf
35740 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73  aces set the res
35750 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
35760 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
35770 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
35780 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69   a BLOB containi
35790 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62  ng all zero.** b
357a0 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73  ytes and N bytes
357b0 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20   in size, where 
357c0 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  N is the value o
357d0 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
357e0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
357f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
35800 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  ouble() interfac
35810 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
35820 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
35830 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
35840 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
35850 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
35860 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
35870 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61  .** by its 2nd a
35880 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
35890 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
358a0 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
358b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
358c0 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
358d0 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
358e0 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
358f0 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
35900 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a   an exception..*
35910 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
35920 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  he string pointe
35930 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32  d to by the.** 2
35940 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
35950 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35960 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65  rror() or sqlite
35970 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
35980 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78  ().** as the tex
35990 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65  t of an error me
359a0 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20  ssage.  ^SQLite 
359b0 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65  interprets the e
359c0 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
359d0 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
359e0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
359f0 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51  () as UTF-8. ^SQ
35a00 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  Lite.** interpre
35a10 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72  ts the string fr
35a20 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
35a30 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55  t_error16() as U
35a40 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a  TF-16 in native.
35a50 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20  ** byte order.  
35a60 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
35a70 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
35a80 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
35a90 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
35aa0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
35ab0 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65   is negative the
35ac0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61  n SQLite takes a
35ad0 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
35ae0 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20  essage all text 
35af0 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  up through the f
35b00 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
35b10 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
35b20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
35b30 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
35b40 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20  t_error() or.** 
35b50 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
35b60 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d  rror16() is non-
35b70 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
35b80 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20  Lite takes that 
35b90 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e  many.** bytes (n
35ba0 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66  ot characters) f
35bb0 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
35bc0 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72  meter as the err
35bd0 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e  or message..** ^
35be0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
35bf0 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
35c00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
35c10 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  ror16().** routi
35c20 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61  nes make a priva
35c30 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65  te copy of the e
35c40 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
35c50 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79  t before.** they
35c60 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c   return.  Hence,
35c70 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
35c80 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f  ction can deallo
35c90 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66  cate or.** modif
35ca0 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72  y the text after
35cb0 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74   they return wit
35cc0 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54  hout harm..** ^T
35cd0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35ce0 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
35cf0 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
35d00 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
35d10 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
35d20 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
35d30 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
35d40 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79  a function.  ^By
35d50 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65   default,.** the
35d60 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53   error code is S
35d70 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41  QLITE_ERROR.  ^A
35d80 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
35d90 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
35da0 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
35db0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35dc0 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73  error16() resets
35dd0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
35de0 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  to SQLITE_ERROR.
35df0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35e00 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
35e10 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66  _toobig() interf
35e20 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
35e30 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a  e to throw an.**
35e40 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e   error indicatin
35e50 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20  g that a string 
35e60 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c  or BLOB is too l
35e70 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ong to represent
35e80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
35e90 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
35ea0 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66  r_nomem() interf
35eb0 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
35ec0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a  e to throw an.**
35ed0 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e   error indicatin
35ee0 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20  g that a memory 
35ef0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65  allocation faile
35f00 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
35f10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
35f20 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
35f30 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
35f40 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
35f50 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
35f60 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
35f70 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65  the 32-bit signe
35f80 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
35f90 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
35fa0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
35fb0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
35fc0 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
35fd0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
35fe0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
35ff0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
36000 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
36010 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
36020 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
36030 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
36040 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
36050 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
36060 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36070 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
36080 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
36090 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
360a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
360b0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
360c0 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
360d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
360e0 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71  esult_text(), sq
360f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
36100 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  t16(),.** sqlite
36110 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
36120 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  e(), and sqlite3
36130 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
36140 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
36150 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20   set the return 
36160 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70  value of the app
36170 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36180 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
36190 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  ** a text string
361a0 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73   which is repres
361b0 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20  ented as UTF-8, 
361c0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
361d0 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46  te order,.** UTF
361e0 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61  -16 little endia
361f0 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
36200 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74   endian, respect
36210 69 76 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20 73  ively..** ^The s
36220 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
36230 78 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65  xt64() interface
36240 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
36250 20 76 61 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a 20   value of an.** 
36260 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
36270 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
36280 62 65 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  be a text string
36290 20 69 6e 20 61 6e 20 65 6e 63 6f 64 69 6e 67 0a   in an encoding.
362a0 2a 2a 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ** specified by 
362b0 74 68 65 20 66 69 66 74 68 20 28 61 6e 64 20 6c  the fifth (and l
362c0 61 73 74 29 20 70 61 72 61 6d 65 74 65 72 2c 20  ast) parameter, 
362d0 77 68 69 63 68 20 6d 75 73 74 20 62 65 20 6f 6e  which must be on
362e0 65 0a 2a 2a 20 6f 66 20 5b 53 51 4c 49 54 45 5f  e.** of [SQLITE_
362f0 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
36300 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  TF16], [SQLITE_U
36310 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c  TF16BE], or [SQL
36320 49 54 45 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a  ITE_UTF16LE]..**
36330 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74   ^SQLite takes t
36340 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66  he text result f
36350 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74  rom the applicat
36360 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ion from.** the 
36370 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
36380 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
36390 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
363a0 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  aces..** ^If the
363b0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
363c0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
363d0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
363e0 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61  faces.** is nega
363f0 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74  tive, then SQLit
36400 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74  e takes result t
36410 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  ext from the 2nd
36420 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68   parameter.** th
36430 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
36440 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
36450 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
36460 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
36470 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
36480 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
36490 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  ** is non-negati
364a0 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79  ve, then as many
364b0 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
364c0 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74  acters) of the t
364d0 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ext.** pointed t
364e0 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  o by the 2nd par
364f0 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e  ameter are taken
36500 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74   as the applicat
36510 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66  ion-defined.** f
36520 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20  unction result. 
36530 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
36540 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67  meter is non-neg
36550 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a  ative, then it.*
36560 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  * must be the by
36570 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74  te offset into t
36580 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20  he string where 
36590 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
365a0 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65  or would.** appe
365b0 61 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67  ar if the string
365c0 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69   where NUL termi
365d0 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
365e0 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
365f0 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74  cur.** in the st
36600 72 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f  ring at a byte o
36610 66 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65  ffset that is le
36620 73 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75  ss than the valu
36630 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20  e of the 3rd.** 
36640 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20  parameter, then 
36650 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
36660 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69  ring will contai
36670 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  n embedded NULs 
36680 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  and the.** resul
36690 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
366a0 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74   operating on st
366b0 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64  rings with embed
366c0 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
366d0 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  fined..** ^If th
366e0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
366f0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
36700 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
36710 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
36720 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
36730 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   is a non-NULL p
36740 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
36750 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a  ite calls that.*
36760 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68  * function as th
36770 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  e destructor on 
36780 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
36790 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20   result when it 
367a0 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
367b0 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
367c0 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
367d0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
367e0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
367f0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
36800 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  es or to.** sqli
36810 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
36820 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
36830 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53  onstant SQLITE_S
36840 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69  TATIC, then SQLi
36850 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68  te.** assumes th
36860 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  at the text or B
36870 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e  LOB result is in
36880 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20   constant space 
36890 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  and does not.** 
368a0 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74  copy the content
368b0 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   of the paramete
368c0 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73  r nor call a des
368d0 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63  tructor on the c
368e0 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69  ontent.** when i
368f0 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  t has finished u
36900 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
36910 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
36920 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
36930 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36940 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
36950 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
36960 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
36970 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
36980 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ant SQLITE_TRANS
36990 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c  IENT.** then SQL
369a0 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
369b0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   of the result i
369c0 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e  nto space obtain
369d0 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20  ed from.** from 
369e0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
369f0 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  )] before it ret
36a00 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
36a10 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36a20 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
36a30 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
36a40 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
36a50 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
36a60 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
36a70 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e   copy the.** [un
36a80 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
36a90 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
36aa0 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
36ab0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
36ac0 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
36ad0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
36ae0 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
36af0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
36b00 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
36b10 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71   so that the [sq
36b20 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65  lite3_value] spe
36b30 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61  cified in the pa
36b40 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e  rameter may chan
36b50 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c  ge or.** be deal
36b60 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71  located after sq
36b70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
36b80 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74  ue() returns wit
36b90 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41  hout harm..** ^A
36ba0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
36bb0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
36bc0 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20  t may always be 
36bd0 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a  used where an.**
36be0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
36bf0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
36c00 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c  ect is required,
36c10 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69   so either.** ki
36c20 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76  nd of [sqlite3_v
36c30 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e  alue] object can
36c40 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68   be used with th
36c50 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
36c60 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75  .** If these rou
36c70 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
36c80 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65   from within the
36c90 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
36ca0 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e  d.** than the on
36cb0 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
36cc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
36cd0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68  ined function th
36ce0 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74  at received.** t
36cf0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  he [sqlite3_cont
36d00 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68  ext] pointer, th
36d10 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
36d20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64  defined..*/.void
36d30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36d40 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
36d50 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
36d60 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
36d70 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
36d80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
36d90 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ob64(sqlite3_con
36da0 74 65 78 74 2a 2c 63 6f 6e 73 74 20 76 6f 69 64  text*,const void
36db0 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  *,.             
36dc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71                sq
36dd0 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 76 6f 69  lite3_uint64,voi
36de0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
36df0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36e00 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
36e10 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
36e20 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  e);.void sqlite3
36e30 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
36e40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36e50 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
36e60 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
36e70 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
36e80 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36e90 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
36ea0 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
36eb0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
36ec0 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e  obig(sqlite3_con
36ed0 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
36ee0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36ef0 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f  r_nomem(sqlite3_
36f00 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
36f10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36f20 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
36f30 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
36f40 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36f50 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
36f60 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
36f70 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
36f80 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69  esult_int64(sqli
36f90 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
36fa0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f  lite3_int64);.vo
36fb0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
36fc0 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
36fd0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
36fe0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
36ff0 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
37000 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
37010 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
37020 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
37030 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
37040 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
37050 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
37060 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c  ,sqlite3_uint64,
37070 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
37080 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
37090 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69  (*)(void*), unsi
370a0 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69  gned char encodi
370b0 6e 67 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  ng);.void sqlite
370c0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
370d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
370e0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
370f0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
37100 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
37110 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
37120 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
37130 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
37140 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
37150 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
37160 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
37170 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  be(sqlite3_conte
37180 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
37190 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
371a0 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
371b0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
371c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
371d0 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  *, sqlite3_value
371e0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
371f0 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
37200 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37210 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  *, int n);../*.*
37220 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69  * CAPI3REF: Defi
37230 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67  ne New Collating
37240 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a   Sequences.**.**
37250 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
37260 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f  s add, remove, o
37270 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c  r modify a [coll
37280 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65  ation] associate
37290 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64  d.** with the [d
372a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
372b0 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73  on] specified as
372c0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
372d0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
372e0 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c  name of the coll
372f0 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38  ation is a UTF-8
37300 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73   string.** for s
37310 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
37320 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71  llation() and sq
37330 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
37340 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61  lation_v2().** a
37350 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  nd a UTF-16 stri
37360 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
37370 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  e order for sqli
37380 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
37390 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f  tion16()..** ^Co
373a0 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68  llation names th
373b0 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c  at compare equal
373c0 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73   according to [s
373d0 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28  qlite3_strnicmp(
373e0 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64  )] are.** consid
373f0 65 72 65 64 20 74 6f 20 62 65 20 74 68 65 20 73  ered to be the s
37400 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ame name..**.** 
37410 5e 28 54 68 65 20 74 68 69 72 64 20 61 72 67 75  ^(The third argu
37420 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70 29 20  ment (eTextRep) 
37430 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74  must be one of t
37440 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a  he constants:.**
37450 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
37460 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20  QLITE_UTF8],.** 
37470 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
37480 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  16LE],.** <li> [
37490 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
374a0 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
374b0 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c  _UTF16], or.** <
374c0 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
374d0 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c  6_ALIGNED]..** <
374e0 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65  /ul>)^.** ^The e
374f0 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74  TextRep argument
37500 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20   determines the 
37510 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69  encoding of stri
37520 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f  ngs passed.** to
37530 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
37540 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
37550 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  , xCallback..** 
37560 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46  ^The [SQLITE_UTF
37570 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  16] and [SQLITE_
37580 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76  UTF16_ALIGNED] v
37590 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74 52  alues for eTextR
375a0 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69  ep.** force stri
375b0 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31 36 20  ngs to be UTF16 
375c0 77 69 74 68 20 6e 61 74 69 76 65 20 62 79 74 65  with native byte
375d0 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20   order..** ^The 
375e0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
375f0 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72  IGNED] value for
37600 20 65 54 65 78 74 52 65 70 20 66 6f 72 63 65 73   eTextRep forces
37610 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69   strings to begi
37620 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20  n.** on an even 
37630 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a  byte address..**
37640 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
37650 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20  argument, pArg, 
37660 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  is an applicatio
37670 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74  n data pointer t
37680 68 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a  hat is passed.**
37690 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
376a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
376b0 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
376c0 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
376d0 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  k..**.** ^The fi
376e0 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43  fth argument, xC
376f0 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f  allback, is a po
37700 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c  inter to the col
37710 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e  lating function.
37720 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f  .** ^Multiple co
37730 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
37740 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65  s can be registe
37750 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 61  red using the sa
37760 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77  me name but.** w
37770 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 65 54  ith different eT
37780 65 78 74 52 65 70 20 70 61 72 61 6d 65 74 65 72  extRep parameter
37790 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c  s and SQLite wil
377a0 6c 20 75 73 65 20 77 68 69 63 68 65 76 65 72 0a  l use whichever.
377b0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ** function requ
377c0 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  ires the least a
377d0 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72  mount of data tr
377e0 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a  ansformation..**
377f0 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61   ^If the xCallba
37800 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e  ck argument is N
37810 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c  ULL then the col
37820 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
37830 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20  is.** deleted.  
37840 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74  ^When all collat
37850 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61  ing functions ha
37860 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61  ving the same na
37870 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a  me are deleted,.
37880 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f  ** that collatio
37890 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75  n is no longer u
378a0 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  sable..**.** ^Th
378b0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
378c0 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73  tion callback is
378d0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
378e0 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72 67  copy of the pArg
378f0 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e   .** application
37900 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e   data pointer an
37910 64 20 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e  d with two strin
37920 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69  gs in the encodi
37930 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ng specified.** 
37940 62 79 20 74 68 65 20 65 54 65 78 74 52 65 70 20  by the eTextRep 
37950 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63  argument.  The c
37960 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
37970 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e  n must return an
37980 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74  .** integer that
37990 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65   is negative, ze
379a0 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a  ro, or positive.
379b0 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73 74 20  ** if the first 
379c0 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74  string is less t
379d0 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f  han, equal to, o
379e0 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74  r greater than t
379f0 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65  he second,.** re
37a00 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63  spectively.  A c
37a10 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
37a20 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65  n must always re
37a30 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e  turn the same an
37a40 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68  swer.** given th
37a50 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20  e same inputs.  
37a60 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63  If two or more c
37a70 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
37a80 6e 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65  ns are registere
37a90 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65  d.** to the same
37aa0 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20   collation name 
37ab0 28 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74  (using different
37ac0 20 65 54 65 78 74 52 65 70 20 76 61 6c 75 65 73   eTextRep values
37ad0 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75  ) then all.** mu
37ae0 73 74 20 67 69 76 65 20 61 6e 20 65 71 75 69 76  st give an equiv
37af0 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65  alent answer whe
37b00 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65  n invoked with e
37b10 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67  quivalent string
37b20 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74  s..** The collat
37b30 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
37b40 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f  t obey the follo
37b50 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20  wing properties 
37b60 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e  for all.** strin
37b70 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a  gs A, B, and C:.
37b80 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
37b90 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20  i> If A==B then 
37ba0 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  B==A..** <li> If
37bb0 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74   A==B and B==C t
37bc0 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69  hen A==C..** <li
37bd0 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e  > If A&lt;B THEN
37be0 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e   B&gt;A..** <li>
37bf0 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42   If A&lt;B and B
37c00 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b  &lt;C then A&lt;
37c10 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a  C..** </ol>.**.*
37c20 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67  * If a collating
37c30 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20   function fails 
37c40 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65  any of the above
37c50 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64   constraints and
37c60 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69   that.** collati
37c70 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20  ng function is  
37c80 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 75  registered and u
37c90 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65  sed, then the be
37ca0 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
37cb0 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
37cc0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
37cd0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
37ce0 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73  ation_v2() works
37cf0 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72   like sqlite3_cr
37d00 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
37d10 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64 64  .** with the add
37d20 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78  ition that the x
37d30 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b  Destroy callback
37d40 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70   is invoked on p
37d50 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  Arg when.** the 
37d60 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
37d70 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a  on is deleted..*
37d80 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  * ^Collating fun
37d90 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74  ctions are delet
37da0 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65  ed when they are
37db0 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c   overridden by l
37dc0 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  ater.** calls to
37dd0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63   the collation c
37de0 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  reation function
37df0 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a  s or when the.**
37e00 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
37e10 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64  ction] is closed
37e20 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
37e30 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  close()]..**.** 
37e40 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20 63 61  ^The xDestroy ca
37e50 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74  llback is <u>not
37e60 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74  </u> called if t
37e70 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  he .** sqlite3_c
37e80 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
37e90 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61  v2() function fa
37ea0 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ils.  Applicatio
37eb0 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a  ns that invoke.*
37ec0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
37ed0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
37ee0 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
37ef0 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e  xDestroy argumen
37f00 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65  t should .** che
37f10 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
37f20 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f  de and dispose o
37f30 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
37f40 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a  n data pointer.*
37f50 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74  * themselves rat
37f60 68 65 72 20 74 68 61 6e 20 65 78 70 65 63 74 69  her than expecti
37f70 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61  ng SQLite to dea
37f80 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20 74 68  l with it for th
37f90 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64  em..** This is d
37fa0 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76  ifferent from ev
37fb0 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  ery other SQLite
37fc0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
37fd0 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a   inconsistency .
37fe0 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74  ** is unfortunat
37ff0 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20  e but cannot be 
38000 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20  changed without 
38010 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72  breaking backwar
38020 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  ds .** compatibi
38030 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  lity..**.** See 
38040 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f  also:  [sqlite3_
38050 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
38060 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
38070 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
38080 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  d16()]..*/.int s
38090 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
380a0 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  llation(.  sqlit
380b0 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
380c0 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
380d0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
380e0 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
380f0 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
38100 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
38110 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
38120 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
38130 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
38140 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
38150 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
38160 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
38170 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
38180 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
38190 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
381a0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
381b0 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
381c0 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
381d0 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  oy)(void*).);.in
381e0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
381f0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20  _collation16(.  
38200 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
38210 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a  st void *zName,.
38220 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
38230 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
38240 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
38250 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
38260 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
38270 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
38280 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61   CAPI3REF: Colla
38290 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c  tion Needed Call
382a0 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20  backs.**.** ^To 
382b0 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20  avoid having to 
382c0 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c  register all col
382d0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
382e0 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61   before a databa
382f0 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  se.** can be use
38300 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c  d, a single call
38310 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61  back function ma
38320 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  y be registered 
38330 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74  with the.** [dat
38340 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
38350 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  ] to be invoked 
38360 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65  whenever an unde
38370 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a  fined collation.
38380 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72  ** sequence is r
38390 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
383a0 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
383b0 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73  is registered us
383c0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
383d0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
383e0 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20  () API,.** then 
383f0 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65  it is passed the
38400 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69   names of undefi
38410 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ned collation se
38420 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e  quences as strin
38430 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e  gs.** encoded in
38440 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69   UTF-8. ^If sqli
38450 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
38460 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64  eded16() is used
38470 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61  ,.** the names a
38480 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46  re passed as UTF
38490 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e  -16 in machine n
384a0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
384b0 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
384c0 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20  either function 
384d0 72 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69  replaces the exi
384e0 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d  sting collation-
384f0 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e  needed callback.
38500 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68  .**.** ^(When th
38510 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
38520 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74  voked, the first
38530 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
38540 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66   is a copy.** of
38550 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
38560 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
38570 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
38580 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
38590 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
385a0 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f  d16().  The seco
385b0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
385c0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
385d0 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20  onnection.  The 
385e0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
385f0 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
38600 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
38610 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20  UTF16BE],.** or 
38620 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
38630 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65  , indicating the
38640 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20   most desirable 
38650 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c  form of the coll
38660 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
38670 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  e function requi
38680 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68  red.  The fourth
38690 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
386a0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
386b0 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74   required collat
386c0 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a  ion sequence.)^.
386d0 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
386e0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  ck function shou
386f0 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20  ld register the 
38700 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  desired collatio
38710 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
38720 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
38730 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  tion()], [sqlite
38740 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
38750 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  on16()], or.** [
38760 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
38770 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a  ollation_v2()]..
38780 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
38790 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
387a0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
387b0 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  void*, .  void(*
387c0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
387d0 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
387e0 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e  nst char*).);.in
387f0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
38800 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20  ion_needed16(.  
38810 73 7