/ Hex Artifact Content
Login

Artifact 03f5fe8f2da9713aa1748f7e4ce34a0c35926ac9:


0000: 23 0a 23 20 52 75 6e 20 74 68 69 73 20 54 63 6c  #.# Run this Tcl
0010: 20 73 63 72 69 70 74 20 74 6f 20 67 65 6e 65 72   script to gener
0020: 61 74 65 20 74 68 65 20 73 71 6c 69 74 65 2e 68  ate the sqlite.h
0030: 74 6d 6c 20 66 69 6c 65 2e 0a 23 0a 73 65 74 20  tml file..#.set 
0040: 72 63 73 69 64 20 7b 24 49 64 3a 20 63 5f 69 6e  rcsid {$Id: c_in
0050: 74 65 72 66 61 63 65 2e 74 63 6c 2c 76 20 31 2e  terface.tcl,v 1.
0060: 31 30 20 32 30 30 30 2f 31 30 2f 30 39 20 31 32  10 2000/10/09 12
0070: 3a 35 37 3a 30 31 20 64 72 68 20 45 78 70 20 24  :57:01 drh Exp $
0080: 7d 0a 0a 70 75 74 73 20 7b 3c 68 74 6d 6c 3e 0a  }..puts {<html>.
0090: 3c 68 65 61 64 3e 0a 20 20 3c 74 69 74 6c 65 3e  <head>.  <title>
00a0: 54 68 65 20 43 20 6c 61 6e 67 75 61 67 65 20 69  The C language i
00b0: 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20  nterface to the 
00c0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 3c 2f  SQLite library</
00d0: 74 69 74 6c 65 3e 0a 3c 2f 68 65 61 64 3e 0a 3c  title>.</head>.<
00e0: 62 6f 64 79 20 62 67 63 6f 6c 6f 72 3d 77 68 69  body bgcolor=whi
00f0: 74 65 3e 0a 3c 68 31 20 61 6c 69 67 6e 3d 63 65  te>.<h1 align=ce
0100: 6e 74 65 72 3e 0a 54 68 65 20 43 20 6c 61 6e 67  nter>.The C lang
0110: 75 61 67 65 20 69 6e 74 65 72 66 61 63 65 20 74  uage interface t
0120: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
0130: 72 61 72 79 0a 3c 2f 68 31 3e 7d 0a 70 75 74 73  rary.</h1>}.puts
0140: 20 22 3c 70 20 61 6c 69 67 6e 3d 63 65 6e 74 65   "<p align=cente
0150: 72 3e 0a 28 54 68 69 73 20 70 61 67 65 20 77 61  r>.(This page wa
0160: 73 20 6c 61 73 74 20 6d 6f 64 69 66 69 65 64 20  s last modified 
0170: 6f 6e 20 5b 6c 72 61 6e 67 65 20 24 72 63 73 69  on [lrange $rcsi
0180: 64 20 33 20 34 5d 20 47 4d 54 29 0a 3c 2f 70 3e  d 3 4] GMT).</p>
0190: 22 0a 0a 70 75 74 73 20 7b 0a 3c 70 3e 54 68 65  "..puts {.<p>The
01a0: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
01b0: 69 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 62  is designed to b
01c0: 65 20 76 65 72 79 20 65 61 73 79 20 74 6f 20 75  e very easy to u
01d0: 73 65 20 66 72 6f 6d 0a 61 20 43 20 6f 72 20 43  se from.a C or C
01e0: 2b 2b 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 69  ++ program.  Thi
01f0: 73 20 64 6f 63 75 6d 65 6e 74 20 67 69 76 65 73  s document gives
0200: 20 61 6e 20 6f 76 65 72 76 69 65 77 20 6f 66 20   an overview of 
0210: 74 68 65 20 43 2f 43 2b 2b 0a 70 72 6f 67 72 61  the C/C++.progra
0220: 6d 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 2e  mming interface.
0230: 3c 2f 70 3e 0a 0a 3c 68 32 3e 54 68 65 20 41 50  </p>..<h2>The AP
0240: 49 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 68 65 20 69  I</h2>..<p>The i
0250: 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20  nterface to the 
0260: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 63  SQLite library c
0270: 6f 6e 73 69 73 74 73 20 6f 66 20 74 68 72 65 65  onsists of three
0280: 20 63 6f 72 65 20 66 75 6e 63 74 69 6f 6e 73 2c   core functions,
0290: 0a 6f 6e 65 20 6f 70 61 71 75 65 20 64 61 74 61  .one opaque data
02a0: 20 73 74 72 75 63 74 75 72 65 2c 20 61 6e 64 20   structure, and 
02b0: 73 6f 6d 65 20 63 6f 6e 73 74 61 6e 74 73 20 75  some constants u
02c0: 73 65 64 20 61 73 20 72 65 74 75 72 6e 20 76 61  sed as return va
02d0: 6c 75 65 73 2e 0a 54 68 65 20 63 6f 72 65 20 69  lues..The core i
02e0: 6e 74 65 72 66 61 63 65 20 69 73 20 61 73 20 66  nterface is as f
02f0: 6f 6c 6c 6f 77 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c  ollows:</p>..<bl
0300: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 74  ockquote><pre>.t
0310: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
0320: 6c 69 74 65 20 73 71 6c 69 74 65 3b 0a 0a 73 71  lite sqlite;..sq
0330: 6c 69 74 65 20 2a 73 71 6c 69 74 65 5f 6f 70 65  lite *sqlite_ope
0340: 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69  n(const char *fi
0350: 6c 65 6e 61 6d 65 2c 20 69 6e 74 20 6d 6f 64 65  lename, int mode
0360: 2c 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 29  , char **errmsg)
0370: 3b 0a 0a 76 6f 69 64 20 73 71 6c 69 74 65 5f 63  ;..void sqlite_c
0380: 6c 6f 73 65 28 73 71 6c 69 74 65 2a 29 3b 0a 0a  lose(sqlite*);..
0390: 69 6e 74 20 73 71 6c 69 74 65 5f 65 78 65 63 28  int sqlite_exec(
03a0: 0a 20 20 73 71 6c 69 74 65 2a 2c 0a 20 20 63 68  .  sqlite*,.  ch
03b0: 61 72 20 2a 73 71 6c 2c 0a 20 20 69 6e 74 20 28  ar *sql,.  int (
03c0: 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  *)(void*,int,cha
03d0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 0a 20 20 76  r**,char**),.  v
03e0: 6f 69 64 2a 2c 0a 20 20 63 68 61 72 20 2a 2a 65  oid*,.  char **e
03f0: 72 72 6d 73 67 0a 29 3b 0a 0a 23 64 65 66 69 6e  rrmsg.);..#defin
0400: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
0410: 20 20 20 30 20 20 20 20 2f 2a 20 53 75 63 63 65     0    /* Succe
0420: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
0430: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
0440: 4e 54 45 52 4e 41 4c 20 20 31 20 20 20 20 2f 2a  NTERNAL  1    /*
0450: 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6c 6f 67   An internal log
0460: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
0470: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
0480: 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 32  LITE_ERROR     2
0490: 20 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72      /* SQL error
04a0: 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61   or missing data
04b0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
04c0: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
04d0: 20 33 20 20 20 20 2f 2a 20 41 63 63 65 73 73 20   3    /* Access 
04e0: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
04f0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
0500: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 34 20  ITE_ABORT     4 
0510: 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72     /* Callback r
0520: 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 64  outine requested
0530: 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65   an abort */.#de
0540: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
0550: 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 4f 6e        5    /* On
0560: 65 20 6f 72 20 6d 6f 72 65 20 64 61 74 61 62 61  e or more databa
0570: 73 65 20 66 69 6c 65 73 20 61 72 65 20 6c 6f 63  se files are loc
0580: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
0590: 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20  QLITE_NOMEM     
05a0: 36 20 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63  6    /* A malloc
05b0: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
05c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
05d0: 4f 4e 4c 59 20 20 37 20 20 20 20 2f 2a 20 41 74  ONLY  7    /* At
05e0: 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61  tempt to write a
05f0: 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61   readonly databa
0600: 73 65 20 2a 2f 0a 3c 2f 70 72 65 3e 3c 2f 62 6c  se */.</pre></bl
0610: 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 4f 6e  ockquote>..<p>On
0620: 6c 79 20 74 68 65 20 74 68 72 65 65 20 63 6f 72  ly the three cor
0630: 65 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 77 6e  e routines shown
0640: 20 61 62 6f 76 65 20 61 72 65 20 72 65 71 75 69   above are requi
0650: 72 65 64 20 74 6f 20 75 73 65 0a 53 51 4c 69 74  red to use.SQLit
0660: 65 2e 20 20 42 75 74 20 74 68 65 72 65 20 61 72  e.  But there ar
0670: 65 20 6d 61 6e 79 20 6f 74 68 65 72 20 66 75 6e  e many other fun
0680: 63 74 69 6f 6e 73 20 74 68 61 74 20 70 72 6f 76  ctions that prov
0690: 69 64 65 20 0a 75 73 65 66 75 6c 20 69 6e 74 65  ide .useful inte
06a0: 72 66 61 63 65 73 2e 20 20 54 68 65 73 65 20 65  rfaces.  These e
06b0: 78 74 65 6e 64 65 64 20 72 6f 75 74 69 6e 65 73  xtended routines
06c0: 20 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a   are as follows:
06d0: 0a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f  .</p>..<blockquo
06e0: 74 65 3e 3c 70 72 65 3e 0a 69 6e 74 20 73 71 6c  te><pre>.int sql
06f0: 69 74 65 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  ite_get_table(. 
0700: 20 73 71 6c 69 74 65 2a 2c 0a 20 20 63 68 61 72   sqlite*,.  char
0710: 20 2a 73 71 6c 2c 0a 20 20 63 68 61 72 20 2a 2a   *sql,.  char **
0720: 2a 72 65 73 75 6c 74 2c 0a 20 20 69 6e 74 20 2a  *result,.  int *
0730: 6e 72 6f 77 2c 0a 20 20 69 6e 74 20 2a 6e 63 6f  nrow,.  int *nco
0740: 6c 75 6d 6e 2c 0a 20 20 63 68 61 72 20 2a 2a 65  lumn,.  char **e
0750: 72 72 6d 73 67 0a 29 3b 0a 0a 76 6f 69 64 20 73  rrmsg.);..void s
0760: 71 6c 69 74 65 5f 66 72 65 65 5f 74 61 62 6c 65  qlite_free_table
0770: 28 63 68 61 72 2a 2a 29 3b 0a 0a 69 6e 74 20 73  (char**);..int s
0780: 71 6c 69 74 65 5f 63 6f 6d 70 6c 65 74 65 28 63  qlite_complete(c
0790: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b  onst char *sql);
07a0: 0a 0a 76 6f 69 64 20 73 71 6c 69 74 65 5f 62 75  ..void sqlite_bu
07b0: 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
07c0: 65 2a 2c 20 69 6e 74 20 28 2a 29 28 76 6f 69 64  e*, int (*)(void
07d0: 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e  *,const char*,in
07e0: 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 76 6f 69  t), void*);..voi
07f0: 64 20 73 71 6c 69 74 65 5f 62 75 73 79 5f 74 69  d sqlite_busy_ti
0800: 6d 65 6f 75 74 28 73 71 6c 69 74 65 2a 2c 20 69  meout(sqlite*, i
0810: 6e 74 20 6d 73 29 3b 0a 0a 63 6f 6e 73 74 20 63  nt ms);..const c
0820: 68 61 72 20 73 71 6c 69 74 65 5f 76 65 72 73 69  har sqlite_versi
0830: 6f 6e 5b 5d 3b 0a 0a 69 6e 74 20 73 71 6c 69 74  on[];..int sqlit
0840: 65 5f 65 78 65 63 5f 70 72 69 6e 74 66 28 0a 20  e_exec_printf(. 
0850: 20 73 71 6c 69 74 65 2a 2c 0a 20 20 63 68 61 72   sqlite*,.  char
0860: 20 2a 73 71 6c 2c 0a 20 20 69 6e 74 20 28 2a 29   *sql,.  int (*)
0870: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
0880: 2a 2c 63 68 61 72 2a 2a 29 2c 0a 20 20 76 6f 69  *,char**),.  voi
0890: 64 2a 2c 0a 20 20 63 68 61 72 20 2a 2a 65 72 72  d*,.  char **err
08a0: 6d 73 67 2c 0a 20 20 2e 2e 2e 0a 29 3b 0a 0a 69  msg,.  ....);..i
08b0: 6e 74 20 73 71 6c 69 74 65 5f 65 78 65 63 5f 76  nt sqlite_exec_v
08c0: 70 72 69 6e 74 66 28 0a 20 20 73 71 6c 69 74 65  printf(.  sqlite
08d0: 2a 2c 0a 20 20 63 68 61 72 20 2a 73 71 6c 2c 0a  *,.  char *sql,.
08e0: 20 20 69 6e 74 20 28 2a 29 28 76 6f 69 64 2a 2c    int (*)(void*,
08f0: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
0900: 2a 29 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 63  *),.  void*,.  c
0910: 68 61 72 20 2a 2a 65 72 72 6d 73 67 2c 0a 20 20  har **errmsg,.  
0920: 76 61 5f 6c 69 73 74 0a 29 3b 0a 0a 69 6e 74 20  va_list.);..int 
0930: 73 71 6c 69 74 65 5f 67 65 74 5f 74 61 62 6c 65  sqlite_get_table
0940: 5f 70 72 69 6e 74 66 28 0a 20 20 73 71 6c 69 74  _printf(.  sqlit
0950: 65 2a 2c 0a 20 20 63 68 61 72 20 2a 73 71 6c 2c  e*,.  char *sql,
0960: 0a 20 20 63 68 61 72 20 2a 2a 2a 72 65 73 75 6c  .  char ***resul
0970: 74 2c 0a 20 20 69 6e 74 20 2a 6e 72 6f 77 2c 0a  t,.  int *nrow,.
0980: 20 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 0a    int *ncolumn,.
0990: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 2c    char **errmsg,
09a0: 0a 20 20 2e 2e 2e 0a 29 3b 0a 0a 69 6e 74 20 73  .  ....);..int s
09b0: 71 6c 69 74 65 5f 67 65 74 5f 74 61 62 6c 65 5f  qlite_get_table_
09c0: 76 70 72 69 6e 74 66 28 0a 20 20 73 71 6c 69 74  vprintf(.  sqlit
09d0: 65 2a 2c 0a 20 20 63 68 61 72 20 2a 73 71 6c 2c  e*,.  char *sql,
09e0: 0a 20 20 63 68 61 72 20 2a 2a 2a 72 65 73 75 6c  .  char ***resul
09f0: 74 2c 0a 20 20 69 6e 74 20 2a 6e 72 6f 77 2c 0a  t,.  int *nrow,.
0a00: 20 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 0a    int *ncolumn,.
0a10: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 2c    char **errmsg,
0a20: 0a 20 20 76 61 5f 6c 69 73 74 0a 29 3b 0a 0a 3c  .  va_list.);..<
0a30: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
0a40: 65 3e 0a 0a 3c 70 3e 41 6c 6c 20 6f 66 20 74 68  e>..<p>All of th
0a50: 65 20 61 62 6f 76 65 20 64 65 66 69 6e 69 74 69  e above definiti
0a60: 6f 6e 73 20 61 72 65 20 69 6e 63 6c 75 64 65 64  ons are included
0a70: 20 69 6e 20 74 68 65 20 22 73 71 6c 69 74 65 2e   in the "sqlite.
0a80: 68 22 0a 68 65 61 64 65 72 20 66 69 6c 65 20 74  h".header file t
0a90: 68 61 74 20 63 6f 6d 65 73 20 69 6e 20 74 68 65  hat comes in the
0aa0: 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 70   source tree.</p
0ab0: 3e 0a 0a 3c 68 32 3e 4f 70 65 6e 69 6e 67 20 61  >..<h2>Opening a
0ac0: 20 64 61 74 61 62 61 73 65 3c 2f 68 32 3e 0a 0a   database</h2>..
0ad0: 3c 70 3e 55 73 65 20 74 68 65 20 3c 62 3e 73 71  <p>Use the <b>sq
0ae0: 6c 69 74 65 5f 6f 70 65 6e 28 29 3c 2f 62 3e 20  lite_open()</b> 
0af0: 66 75 6e 63 74 69 6f 6e 20 74 6f 20 6f 70 65 6e  function to open
0b00: 20 61 6e 20 65 78 69 73 74 69 6e 67 20 53 51 4c   an existing SQL
0b10: 69 74 65 0a 64 61 74 61 62 61 73 65 20 6f 72 20  ite.database or 
0b20: 74 6f 20 63 72 65 61 74 65 20 61 20 6e 65 77 20  to create a new 
0b30: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 2e  SQLite database.
0b40: 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
0b50: 6d 65 6e 74 0a 69 73 20 74 68 65 20 64 61 74 61  ment.is the data
0b60: 62 61 73 65 20 6e 61 6d 65 2e 20 20 54 68 65 20  base name.  The 
0b70: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
0b80: 69 73 20 61 20 63 6f 6e 73 74 61 6e 74 20 30 36  is a constant 06
0b90: 36 36 20 74 6f 0a 6f 70 65 6e 20 74 68 65 20 64  66 to.open the d
0ba0: 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64  atabase for read
0bb0: 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
0bc0: 61 6e 64 20 30 34 34 34 20 74 6f 20 6f 70 65 6e  and 0444 to open
0bd0: 20 74 68 65 0a 64 61 74 61 62 61 73 65 20 72 65   the.database re
0be0: 61 64 20 6f 6e 6c 79 2e 20 20 54 68 65 20 74 68  ad only.  The th
0bf0: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
0c00: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73  a pointer to a s
0c10: 74 72 69 6e 67 0a 70 6f 69 6e 74 65 72 2e 20 20  tring.pointer.  
0c20: 49 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67  If the third arg
0c30: 75 6d 65 6e 74 20 69 73 20 6e 6f 74 20 4e 55 4c  ument is not NUL
0c40: 4c 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6f  L and an error o
0c50: 63 63 75 72 73 0a 77 68 69 6c 65 20 74 72 79 69  ccurs.while tryi
0c60: 6e 67 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  ng to open the d
0c70: 61 74 61 62 61 73 65 2c 20 74 68 65 6e 20 61 6e  atabase, then an
0c80: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 77   error message w
0c90: 69 6c 6c 20 62 65 0a 77 72 69 74 74 65 6e 20 74  ill be.written t
0ca0: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
0cb0: 64 20 66 72 6f 6d 20 6d 61 6c 6c 6f 63 28 29 20  d from malloc() 
0cc0: 61 6e 64 20 2a 65 72 72 6d 73 67 20 77 69 6c 6c  and *errmsg will
0cd0: 20 62 65 20 6d 61 64 65 0a 74 6f 20 70 6f 69 6e   be made.to poin
0ce0: 74 20 74 6f 20 74 68 69 73 20 65 72 72 6f 72 20  t to this error 
0cf0: 6d 65 73 73 61 67 65 2e 20 20 54 68 65 20 63 61  message.  The ca
0d00: 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  lling function i
0d10: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 0a 66 6f  s responsible.fo
0d20: 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65  r freeing the me
0d30: 6d 6f 72 79 20 77 68 65 6e 20 69 74 20 68 61 73  mory when it has
0d40: 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
0d50: 74 2e 3c 2f 70 3e 0a 0a 3c 70 3e 41 6e 20 53 51  t.</p>..<p>An SQ
0d60: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73  Lite database is
0d70: 20 6a 75 73 74 20 61 20 64 69 72 65 63 74 6f 72   just a director
0d80: 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20 63  y containing a c
0d90: 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 47 44 42  ollection of.GDB
0da0: 4d 20 66 69 6c 65 73 2e 20 20 54 68 65 72 65 20  M files.  There 
0db0: 69 73 20 6f 6e 65 20 47 44 42 4d 20 66 69 6c 65  is one GDBM file
0dc0: 20 66 6f 72 20 65 61 63 68 20 74 61 62 6c 65 20   for each table 
0dd0: 61 6e 64 20 69 6e 64 65 78 20 69 6e 20 74 68 65  and index in the
0de0: 0a 64 61 74 61 62 61 73 65 2e 20 20 41 6c 6c 20  .database.  All 
0df0: 47 44 42 4d 20 66 69 6c 65 73 20 65 6e 64 20 77  GDBM files end w
0e00: 69 74 68 20 74 68 65 20 22 2e 74 62 6c 22 20 73  ith the ".tbl" s
0e10: 75 66 66 69 78 2e 20 20 45 76 65 72 79 20 53 51  uffix.  Every SQ
0e20: 4c 69 74 65 0a 64 61 74 61 62 61 73 65 20 61 6c  Lite.database al
0e30: 73 6f 20 63 6f 6e 74 61 69 6e 73 20 61 20 73 70  so contains a sp
0e40: 65 63 69 61 6c 20 64 61 74 61 62 61 73 65 20 74  ecial database t
0e50: 61 62 6c 65 20 6e 61 6d 65 64 20 3c 62 3e 73 71  able named <b>sq
0e60: 6c 69 74 65 5f 6d 61 73 74 65 72 3c 2f 62 3e 0a  lite_master</b>.
0e70: 73 74 6f 72 65 64 20 69 6e 20 69 74 73 20 6f 77  stored in its ow
0e80: 6e 20 47 44 42 4d 20 66 69 6c 65 2e 20 20 54 68  n GDBM file.  Th
0e90: 69 73 20 73 70 65 63 69 61 6c 20 74 61 62 6c 65  is special table
0ea0: 20 72 65 63 6f 72 64 73 20 74 68 65 20 64 61 74   records the dat
0eb0: 61 62 61 73 65 0a 73 63 68 65 6d 61 2e 3c 2f 70  abase.schema.</p
0ec0: 3e 0a 0a 3c 70 3e 54 6f 20 63 72 65 61 74 65 20  >..<p>To create 
0ed0: 61 20 6e 65 77 20 53 51 4c 69 74 65 20 64 61 74  a new SQLite dat
0ee0: 61 62 61 73 65 2c 20 61 6c 6c 20 79 6f 75 20 68  abase, all you h
0ef0: 61 76 65 20 74 6f 20 64 6f 20 69 73 20 63 61 6c  ave to do is cal
0f00: 6c 0a 3c 62 3e 73 71 6c 69 74 65 5f 6f 70 65 6e  l.<b>sqlite_open
0f10: 28 29 3c 2f 62 3e 20 77 69 74 68 20 74 68 65 20  ()</b> with the 
0f20: 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
0f30: 73 65 74 20 74 6f 20 74 68 65 20 6e 61 6d 65 20  set to the name 
0f40: 6f 66 0a 61 6e 20 65 6d 70 74 79 20 64 69 72 65  of.an empty dire
0f50: 63 74 6f 72 79 20 61 6e 64 20 74 68 65 20 73 65  ctory and the se
0f60: 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 73  cond parameter s
0f70: 65 74 20 74 6f 20 30 36 36 36 2e 3c 2f 70 3e 0a  et to 0666.</p>.
0f80: 0a 3c 70 3e 54 68 65 20 72 65 74 75 72 6e 20 76  .<p>The return v
0f90: 61 6c 75 65 20 6f 66 20 74 68 65 20 3c 62 3e 73  alue of the <b>s
0fa0: 71 6c 69 74 65 5f 6f 70 65 6e 28 29 3c 2f 62 3e  qlite_open()</b>
0fb0: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 0a 70   function is a.p
0fc0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 6f 70 61  ointer to an opa
0fd0: 71 75 65 20 3c 62 3e 73 71 6c 69 74 65 3c 2f 62  que <b>sqlite</b
0fe0: 3e 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  > structure.  Th
0ff0: 69 73 20 70 6f 69 6e 74 65 72 20 77 69 6c 6c 0a  is pointer will.
1000: 62 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  be the first arg
1010: 75 6d 65 6e 74 20 74 6f 20 61 6c 6c 20 73 75 62  ument to all sub
1020: 73 65 71 75 65 6e 74 20 53 51 4c 69 74 65 20 66  sequent SQLite f
1030: 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 74 68  unction calls th
1040: 61 74 0a 64 65 61 6c 20 77 69 74 68 20 74 68 65  at.deal with the
1050: 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e 20   same database. 
1060: 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
1070: 64 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61  d if the open fa
1080: 69 6c 73 0a 66 6f 72 20 61 6e 79 20 72 65 61 73  ils.for any reas
1090: 6f 6e 2e 3c 2f 70 3e 0a 0a 3c 68 32 3e 43 6c 6f  on.</p>..<h2>Clo
10a0: 73 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  sing the databas
10b0: 65 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 6f 20 63 6c  e</h2>..<p>To cl
10c0: 6f 73 65 20 61 6e 20 53 51 4c 69 74 65 20 64 61  ose an SQLite da
10d0: 74 61 62 61 73 65 2c 20 63 61 6c 6c 20 74 68 65  tabase, call the
10e0: 20 3c 62 3e 73 71 6c 69 74 65 5f 63 6c 6f 73 65   <b>sqlite_close
10f0: 28 29 3c 2f 62 3e 0a 66 75 6e 63 74 69 6f 6e 20  ()</b>.function 
1100: 70 61 73 73 69 6e 67 20 69 74 20 74 68 65 20 73  passing it the s
1110: 71 6c 69 74 65 20 73 74 72 75 63 74 75 72 65 20  qlite structure 
1120: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
1130: 20 6f 62 74 61 69 6e 65 64 0a 66 72 6f 6d 20 61   obtained.from a
1140: 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 3c   prior call to <
1150: 62 3e 73 71 6c 69 74 65 5f 6f 70 65 6e 3c 2f 62  b>sqlite_open</b
1160: 3e 2e 0a 0a 3c 68 32 3e 45 78 65 63 75 74 69 6e  >...<h2>Executin
1170: 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  g SQL statements
1180: 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 68 65 20 3c 62  </h2>..<p>The <b
1190: 3e 73 71 6c 69 74 65 5f 65 78 65 63 28 29 3c 2f  >sqlite_exec()</
11a0: 62 3e 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  b> function is u
11b0: 73 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53  sed to process S
11c0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 61 6e  QL statements.an
11d0: 64 20 71 75 65 72 69 65 73 2e 20 20 54 68 69 73  d queries.  This
11e0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
11f0: 65 73 20 35 20 70 61 72 61 6d 65 74 65 72 73 20  es 5 parameters 
1200: 61 73 20 66 6f 6c 6c 6f 77 73 3a 3c 2f 70 3e 0a  as follows:</p>.
1210: 0a 3c 6f 6c 3e 0a 3c 6c 69 3e 3c 70 3e 41 20 70  .<ol>.<li><p>A p
1220: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71  ointer to the sq
1230: 6c 69 74 65 20 73 74 72 75 63 74 75 72 65 20 6f  lite structure o
1240: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
1250: 72 69 6f 72 20 63 61 6c 6c 0a 20 20 20 20 20 20  rior call.      
1260: 20 74 6f 20 3c 62 3e 73 71 6c 69 74 65 5f 6f 70   to <b>sqlite_op
1270: 65 6e 28 29 3c 2f 62 3e 2e 3c 2f 70 3e 3c 2f 6c  en()</b>.</p></l
1280: 69 3e 0a 3c 6c 69 3e 3c 70 3e 41 20 6e 75 6c 6c  i>.<li><p>A null
1290: 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
12a0: 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
12b0: 65 20 74 65 78 74 20 6f 66 20 6f 6e 65 20 6f 72  e text of one or
12c0: 20 6d 6f 72 65 0a 20 20 20 20 20 20 20 53 51 4c   more.       SQL
12d0: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6e 64 2f   statements and/
12e0: 6f 72 20 71 75 65 72 69 65 73 20 74 6f 20 62 65  or queries to be
12f0: 20 70 72 6f 63 65 73 73 65 64 2e 3c 2f 70 3e 3c   processed.</p><
1300: 2f 6c 69 3e 0a 3c 6c 69 3e 3c 70 3e 41 20 70 6f  /li>.<li><p>A po
1310: 69 6e 74 65 72 20 74 6f 20 61 20 63 61 6c 6c 62  inter to a callb
1320: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 68 69  ack function whi
1330: 63 68 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ch is invoked on
1340: 63 65 20 66 6f 72 20 65 61 63 68 0a 20 20 20 20  ce for each.    
1350: 20 20 20 72 6f 77 20 69 6e 20 74 68 65 20 72 65     row in the re
1360: 73 75 6c 74 20 6f 66 20 61 20 71 75 65 72 79 2e  sult of a query.
1370: 20 20 54 68 69 73 20 61 72 67 75 6d 65 6e 74 20    This argument 
1380: 6d 61 79 20 62 65 20 4e 55 4c 4c 2c 20 69 6e 20  may be NULL, in 
1390: 77 68 69 63 68 0a 20 20 20 20 20 20 20 63 61 73  which.       cas
13a0: 65 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 73 20 77  e no callbacks w
13b0: 69 6c 6c 20 65 76 65 72 20 62 65 20 69 6e 76 6f  ill ever be invo
13c0: 6b 65 64 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 3c 6c  ked.</p></li>.<l
13d0: 69 3e 3c 70 3e 41 20 70 6f 69 6e 74 65 72 20 74  i><p>A pointer t
13e0: 68 61 74 20 69 73 20 66 6f 72 77 61 72 64 65 64  hat is forwarded
13f0: 20 74 6f 20 62 65 63 6f 6d 65 20 74 68 65 20 66   to become the f
1400: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 20 20  irst argument.  
1410: 20 20 20 20 20 74 6f 20 74 68 65 20 63 61 6c 6c       to the call
1420: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  back function.</
1430: 70 3e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 3c 70 3e 41  p></li>.<li><p>A
1440: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65   pointer to an e
1450: 72 72 6f 72 20 73 74 72 69 6e 67 2e 20 20 45 72  rror string.  Er
1460: 72 6f 72 20 6d 65 73 73 61 67 65 73 20 61 72 65  ror messages are
1470: 20 77 72 69 74 74 65 6e 20 74 6f 20 73 70 61 63   written to spac
1480: 65 0a 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65  e.       obtaine
1490: 64 20 66 72 6f 6d 20 6d 61 6c 6c 6f 63 28 29 20  d from malloc() 
14a0: 61 6e 64 20 74 68 65 20 65 72 72 6f 72 20 73 74  and the error st
14b0: 72 69 6e 67 20 69 73 20 6d 61 64 65 20 74 6f 20  ring is made to 
14c0: 70 6f 69 6e 74 20 74 6f 0a 20 20 20 20 20 20 20  point to.       
14d0: 74 68 65 20 6d 61 6c 6c 6f 63 65 64 20 73 70 61  the malloced spa
14e0: 63 65 2e 20 20 54 68 65 20 63 61 6c 6c 69 6e 67  ce.  The calling
14f0: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 73   function is res
1500: 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65  ponsible for fre
1510: 65 69 6e 67 0a 20 20 20 20 20 20 20 74 68 69 73  eing.       this
1520: 20 73 70 61 63 65 20 77 68 65 6e 20 69 74 20 68   space when it h
1530: 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1540: 20 69 74 2e 0a 20 20 20 20 20 20 20 54 68 69 73   it..       This
1550: 20 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65   argument may be
1560: 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20   NULL, in which 
1570: 63 61 73 65 20 65 72 72 6f 72 20 6d 65 73 73 61  case error messa
1580: 67 65 73 20 61 72 65 20 6e 6f 74 0a 20 20 20 20  ges are not.    
1590: 20 20 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b     reported back
15a0: 20 74 6f 20 74 68 65 20 63 61 6c 6c 69 6e 67 20   to the calling 
15b0: 66 75 6e 63 74 69 6f 6e 2e 3c 2f 70 3e 3c 2f 6c  function.</p></l
15c0: 69 3e 0a 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 0a 54 68  i>.</ol>..<p>.Th
15d0: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
15e0: 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72  ion is used to r
15f0: 65 63 65 69 76 65 20 74 68 65 20 72 65 73 75 6c  eceive the resul
1600: 74 73 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ts of a query.  
1610: 41 0a 70 72 6f 74 6f 74 79 70 65 20 66 6f 72 20  A.prototype for 
1620: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
1630: 63 74 69 6f 6e 20 69 73 20 61 73 20 66 6f 6c 6c  ction is as foll
1640: 6f 77 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b  ows:</p>..<block
1650: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 69 6e 74 20  quote><pre>.int 
1660: 43 61 6c 6c 62 61 63 6b 28 76 6f 69 64 20 2a 70  Callback(void *p
1670: 41 72 67 2c 20 69 6e 74 20 61 72 67 63 2c 20 63  Arg, int argc, c
1680: 68 61 72 20 2a 2a 61 72 67 76 2c 20 63 68 61 72  har **argv, char
1690: 20 2a 2a 63 6f 6c 75 6d 6e 4e 61 6d 65 73 29 7b   **columnNames){
16a0: 0a 20 20 72 65 74 75 72 6e 20 30 3b 0a 7d 0a 3c  .  return 0;.}.<
16b0: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
16c0: 65 3e 0a 0a 3c 70 3e 54 68 65 20 66 69 72 73 74  e>..<p>The first
16d0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
16e0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6a 75 73   callback is jus
16f0: 74 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  t a copy of the 
1700: 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a  fourth argument.
1710: 74 6f 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65  to <b>sqlite_exe
1720: 63 28 29 3c 2f 62 3e 20 20 54 68 69 73 20 70 61  c()</b>  This pa
1730: 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 75  rameter can be u
1740: 73 65 64 20 74 6f 20 70 61 73 73 20 61 72 62 69  sed to pass arbi
1750: 74 72 61 72 79 0a 69 6e 66 6f 72 6d 61 74 69 6f  trary.informatio
1760: 6e 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  n through to the
1770: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1780: 6f 6e 20 66 72 6f 6d 20 63 6c 69 65 6e 74 20 63  on from client c
1790: 6f 64 65 2e 0a 54 68 65 20 73 65 63 6f 6e 64 20  ode..The second 
17a0: 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
17b0: 6e 75 6d 62 65 72 20 63 6f 6c 75 6d 6e 73 20 69  number columns i
17c0: 6e 20 74 68 65 20 71 75 65 72 79 20 72 65 73 75  n the query resu
17d0: 6c 74 2e 0a 54 68 65 20 74 68 69 72 64 20 61 72  lt..The third ar
17e0: 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 61 72 72  gument is an arr
17f0: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
1800: 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20  o strings where 
1810: 65 61 63 68 20 73 74 72 69 6e 67 0a 69 73 20 61  each string.is a
1820: 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
1830: 66 20 74 68 65 20 72 65 73 75 6c 74 20 66 6f 72  f the result for
1840: 20 74 68 61 74 20 72 65 63 6f 72 64 2e 20 20 4e   that record.  N
1850: 6f 74 65 20 74 68 61 74 20 74 68 65 0a 63 61 6c  ote that the.cal
1860: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
1870: 65 70 6f 72 74 73 20 61 20 4e 55 4c 4c 20 76 61  eports a NULL va
1880: 6c 75 65 20 69 6e 20 74 68 65 20 64 61 74 61 62  lue in the datab
1890: 61 73 65 20 61 73 20 61 20 4e 55 4c 4c 20 70 6f  ase as a NULL po
18a0: 69 6e 74 65 72 2c 0a 77 68 69 63 68 20 69 73 20  inter,.which is 
18b0: 76 65 72 79 20 64 69 66 66 65 72 65 6e 74 20 66  very different f
18c0: 72 6f 6d 20 61 6e 20 65 6d 70 74 79 20 73 74 72  rom an empty str
18d0: 69 6e 67 2e 20 20 49 66 20 74 68 65 20 69 2d 74  ing.  If the i-t
18e0: 68 20 70 61 72 61 6d 65 74 65 72 0a 69 73 20 61  h parameter.is a
18f0: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
1900: 77 65 20 77 69 6c 6c 20 67 65 74 3a 3c 2f 70 3e  we will get:</p>
1910: 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72  .<blockquote><pr
1920: 65 3e 0a 61 72 67 76 5b 69 5d 5b 30 5d 20 3d 3d  e>.argv[i][0] ==
1930: 20 30 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b   0.</pre></block
1940: 71 75 6f 74 65 3e 0a 3c 70 3e 42 75 74 20 69 66  quote>.<p>But if
1950: 20 74 68 65 20 69 2d 74 68 20 70 61 72 61 6d 65   the i-th parame
1960: 74 65 72 20 69 73 20 4e 55 4c 4c 20 77 65 20 77  ter is NULL we w
1970: 69 6c 6c 20 67 65 74 3a 3c 2f 70 3e 0a 3c 62 6c  ill get:</p>.<bl
1980: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 61  ockquote><pre>.a
1990: 72 67 76 5b 69 5d 20 3d 3d 20 30 0a 3c 2f 70 72  rgv[i] == 0.</pr
19a0: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
19b0: 3c 70 3e 54 68 65 20 6e 61 6d 65 73 20 6f 66 20  <p>The names of 
19c0: 74 68 65 20 63 6f 6c 75 6d 6e 73 20 61 72 65 20  the columns are 
19d0: 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65  contained in the
19e0: 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
19f0: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 63 61  .</p>..<p>The ca
1a00: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1a10: 73 68 6f 75 6c 64 20 6e 6f 72 6d 61 6c 6c 79 20  should normally 
1a20: 72 65 74 75 72 6e 20 30 2e 20 20 49 66 20 74 68  return 0.  If th
1a30: 65 20 63 61 6c 6c 62 61 63 6b 0a 66 75 6e 63 74  e callback.funct
1a40: 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ion returns non-
1a50: 7a 65 72 6f 2c 20 74 68 65 20 71 75 65 72 79 20  zero, the query 
1a60: 69 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61  is immediately a
1a70: 62 6f 72 74 65 64 20 61 6e 64 20 0a 3c 62 3e 73  borted and .<b>s
1a80: 71 6c 69 74 65 5f 65 78 65 63 28 29 3c 2f 62 3e  qlite_exec()</b>
1a90: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c   will return SQL
1aa0: 49 54 45 5f 41 42 4f 52 54 2e 3c 2f 70 3e 0a 0a  ITE_ABORT.</p>..
1ab0: 3c 70 3e 54 68 65 20 3c 62 3e 73 71 6c 69 74 65  <p>The <b>sqlite
1ac0: 5f 65 78 65 63 28 29 3c 2f 62 3e 20 66 75 6e 63  _exec()</b> func
1ad0: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1ae0: 69 6e 74 65 67 65 72 20 74 6f 20 69 6e 64 69 63  integer to indic
1af0: 61 74 65 0a 73 75 63 63 65 73 73 20 6f 72 20 66  ate.success or f
1b00: 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 6f 70  ailure of the op
1b10: 65 72 61 74 69 6f 6e 2e 20 20 54 68 65 20 66 6f  eration.  The fo
1b20: 6c 6c 6f 77 69 6e 67 20 61 72 65 20 70 6f 73 73  llowing are poss
1b30: 69 62 6c 65 0a 72 65 74 75 72 6e 20 76 61 6c 75  ible.return valu
1b40: 65 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71  es:</p>..<blockq
1b50: 75 6f 74 65 3e 0a 3c 64 6c 3e 0a 3c 64 74 3e 53  uote>.<dl>.<dt>S
1b60: 51 4c 49 54 45 5f 4f 4b 3c 2f 64 74 3e 0a 3c 64  QLITE_OK</dt>.<d
1b70: 64 3e 3c 70 3e 54 68 69 73 20 76 61 6c 75 65 20  d><p>This value 
1b80: 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 65  is returned if e
1b90: 76 65 72 79 74 68 69 6e 67 20 77 6f 72 6b 65 64  verything worked
1ba0: 20 61 6e 64 20 74 68 65 72 65 20 77 65 72 65 20   and there were 
1bb0: 6e 6f 20 65 72 72 6f 72 73 2e 0a 3c 2f 70 3e 3c  no errors..</p><
1bc0: 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f  /dd>.<dt>SQLITE_
1bd0: 49 4e 54 45 52 4e 41 4c 3c 2f 64 74 3e 0a 3c 64  INTERNAL</dt>.<d
1be0: 64 3e 3c 70 3e 54 68 69 73 20 76 61 6c 75 65 20  d><p>This value 
1bf0: 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 61  indicates that a
1c00: 6e 20 69 6e 74 65 72 6e 61 6c 20 63 6f 6e 73 69  n internal consi
1c10: 73 74 65 6e 63 79 20 63 68 65 63 6b 20 77 69 74  stency check wit
1c20: 68 69 6e 0a 74 68 65 20 53 51 4c 69 74 65 20 6c  hin.the SQLite l
1c30: 69 62 72 61 72 79 20 66 61 69 6c 65 64 2e 20 20  ibrary failed.  
1c40: 54 68 69 73 20 63 61 6e 20 6f 6e 6c 79 20 68 61  This can only ha
1c50: 70 70 65 6e 20 69 66 20 74 68 65 72 65 20 69 73  ppen if there is
1c60: 20 61 20 62 75 67 20 69 6e 0a 74 68 65 20 53 51   a bug in.the SQ
1c70: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 49  Lite library.  I
1c80: 66 20 79 6f 75 20 65 76 65 72 20 67 65 74 20 61  f you ever get a
1c90: 6e 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41  n SQLITE_INTERNA
1ca0: 4c 20 72 65 70 6c 79 20 66 72 6f 6d 0a 61 6e 20  L reply from.an 
1cb0: 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 28 29  <b>sqlite_exec()
1cc0: 3c 2f 62 3e 20 63 61 6c 6c 2c 20 70 6c 65 61 73  </b> call, pleas
1cd0: 65 20 72 65 70 6f 72 74 20 74 68 65 20 70 72 6f  e report the pro
1ce0: 62 6c 65 6d 20 6f 6e 20 74 68 65 20 53 51 4c 69  blem on the SQLi
1cf0: 74 65 0a 6d 61 69 6c 69 6e 67 20 6c 69 73 74 2e  te.mailing list.
1d00: 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53  .</p></dd>.<dt>S
1d10: 51 4c 49 54 45 5f 45 52 52 4f 52 3c 2f 64 74 3e  QLITE_ERROR</dt>
1d20: 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20 72 65 74  .<dd><p>This ret
1d30: 75 72 6e 20 76 61 6c 75 65 20 69 6e 64 69 63 61  urn value indica
1d40: 74 65 73 20 74 68 61 74 20 74 68 65 72 65 20 77  tes that there w
1d50: 61 73 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 74  as an error in t
1d60: 68 65 20 53 51 4c 0a 74 68 61 74 20 77 61 73 20  he SQL.that was 
1d70: 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
1d80: 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 28 29  <b>sqlite_exec()
1d90: 3c 2f 62 3e 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a  </b>..</p></dd>.
1da0: 3c 64 74 3e 53 51 4c 49 54 45 5f 50 45 52 4d 3c  <dt>SQLITE_PERM<
1db0: 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73  /dt>.<dd><p>This
1dc0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 73 61   return value sa
1dd0: 79 73 20 74 68 61 74 20 74 68 65 20 61 63 63 65  ys that the acce
1de0: 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 6f  ss permissions o
1df0: 6e 20 6f 6e 65 20 6f 66 20 74 68 65 0a 47 44 42  n one of the.GDB
1e00: 4d 20 66 69 6c 65 73 20 69 73 20 73 75 63 68 20  M files is such 
1e10: 74 68 61 74 20 74 68 65 20 66 69 6c 65 20 63 61  that the file ca
1e20: 6e 6e 6f 74 20 62 65 20 6f 70 65 6e 65 64 2e 0a  nnot be opened..
1e30: 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51  </p></dd>.<dt>SQ
1e40: 4c 49 54 45 5f 41 42 4f 52 54 3c 2f 64 74 3e 0a  LITE_ABORT</dt>.
1e50: 3c 64 64 3e 3c 70 3e 54 68 69 73 20 76 61 6c 75  <dd><p>This valu
1e60: 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  e is returned if
1e70: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75   the callback fu
1e80: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e  nction returns n
1e90: 6f 6e 2d 7a 65 72 6f 2e 0a 3c 2f 70 3e 3c 2f 64  on-zero..</p></d
1ea0: 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f 42 55  d>.<dt>SQLITE_BU
1eb0: 53 59 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54  SY</dt>.<dd><p>T
1ec0: 68 69 73 20 72 65 74 75 72 6e 20 63 6f 64 65 20  his return code 
1ed0: 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 6f  indicates that o
1ee0: 6e 65 20 6f 66 20 74 68 65 20 75 6e 64 65 72 6c  ne of the underl
1ef0: 79 69 6e 67 20 47 44 42 4d 20 66 69 6c 65 73 0a  ying GDBM files.
1f00: 69 73 20 6c 6f 63 6b 65 64 20 62 65 63 61 75 73  is locked becaus
1f10: 65 20 69 74 20 69 73 20 63 75 72 72 65 6e 74 6c  e it is currentl
1f20: 79 20 62 65 69 6e 67 20 61 63 63 65 73 73 65 64  y being accessed
1f30: 20 62 79 20 61 6e 6f 74 68 65 72 20 74 68 72 65   by another thre
1f40: 61 64 20 6f 72 0a 70 72 6f 63 65 73 73 2e 20 20  ad or.process.  
1f50: 47 44 42 4d 20 61 6c 6c 6f 77 73 20 6d 75 74 69  GDBM allows muti
1f60: 70 6c 65 20 72 65 61 64 65 72 73 20 6f 66 20 74  ple readers of t
1f70: 68 65 20 73 61 6d 65 20 66 69 6c 65 2c 20 62 75  he same file, bu
1f80: 74 20 6f 6e 6c 79 20 6f 6e 65 0a 77 72 69 74 65  t only one.write
1f90: 72 2e 20 20 53 6f 20 6d 75 6c 74 69 70 6c 65 20  r.  So multiple 
1fa0: 70 72 6f 63 65 73 73 65 73 20 63 61 6e 20 71 75  processes can qu
1fb0: 65 72 79 20 61 6e 20 53 51 4c 69 74 65 20 64 61  ery an SQLite da
1fc0: 74 61 62 61 73 65 20 61 74 20 6f 6e 63 65 2e 0a  tabase at once..
1fd0: 42 75 74 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c  But only a singl
1fe0: 65 20 70 72 6f 63 65 73 73 20 63 61 6e 20 77 72  e process can wr
1ff0: 69 74 65 20 74 6f 20 61 6e 20 53 51 4c 69 74 65  ite to an SQLite
2000: 20 64 61 74 61 62 61 73 65 20 61 74 20 6f 6e 65   database at one
2010: 20 74 69 6d 65 2e 0a 49 66 20 61 6e 20 61 74 74   time..If an att
2020: 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
2030: 77 72 69 74 65 20 74 6f 20 61 6e 20 53 51 4c 69  write to an SQLi
2040: 74 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74  te database that
2050: 20 61 6e 6f 74 68 65 72 0a 70 72 6f 63 65 73 73   another.process
2060: 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 65   is currently re
2070: 61 64 69 6e 67 2c 20 74 68 65 20 77 72 69 74 65  ading, the write
2080: 20 69 73 20 6e 6f 74 20 70 65 72 66 6f 72 6d 65   is not performe
2090: 64 20 61 6e 64 20 0a 3c 62 3e 73 71 6c 69 74 65  d and .<b>sqlite
20a0: 5f 65 78 65 63 28 29 3c 2f 62 3e 20 72 65 74 75  _exec()</b> retu
20b0: 72 6e 73 20 53 51 4c 49 54 45 5f 42 55 53 59 2e  rns SQLITE_BUSY.
20c0: 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 61 6e 20    Similarly, an 
20d0: 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 0a  attempt to read.
20e0: 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61  an SQLite databa
20f0: 73 65 20 74 68 61 74 20 69 73 20 63 75 72 72 65  se that is curre
2100: 6e 74 6c 79 20 62 65 69 6e 67 20 77 72 69 74 74  ntly being writt
2110: 65 6e 20 62 79 20 61 6e 6f 74 68 65 72 20 70 72  en by another pr
2120: 6f 63 65 73 73 0a 77 69 6c 6c 20 72 65 74 75 72  ocess.will retur
2130: 6e 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20  n SQLITE_BUSY.  
2140: 49 6e 20 62 6f 74 68 20 63 61 73 65 73 2c 20 74  In both cases, t
2150: 68 65 20 77 72 69 74 65 20 6f 72 20 71 75 65 72  he write or quer
2160: 79 20 61 74 74 65 6d 70 74 0a 63 61 6e 20 62 65  y attempt.can be
2170: 20 72 65 74 72 69 65 64 20 61 66 74 65 72 20 74   retried after t
2180: 68 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  he other process
2190: 20 66 69 6e 69 73 68 65 73 2e 3c 2f 70 3e 0a 3c   finishes.</p>.<
21a0: 70 3e 4e 6f 74 65 20 74 68 61 74 20 6c 6f 63 6b  p>Note that lock
21b0: 69 6e 67 20 69 73 20 64 6f 6e 65 20 61 74 20 74  ing is done at t
21c0: 68 65 20 66 69 6c 65 20 6c 65 76 65 6c 2e 20 20  he file level.  
21d0: 4f 6e 65 20 70 72 6f 63 65 73 73 20 63 61 6e 0a  One process can.
21e0: 77 72 69 74 65 20 74 6f 20 74 61 62 6c 65 20 41  write to table A
21f0: 42 43 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 29  BC (for example)
2200: 20 77 68 69 6c 65 20 61 6e 6f 74 68 65 72 20 70   while another p
2210: 72 6f 63 65 73 73 20 73 69 6d 75 6c 74 61 6e 65  rocess simultane
2220: 6f 75 73 6c 79 0a 72 65 61 64 73 20 66 72 6f 6d  ously.reads from
2230: 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 61 62   a different tab
2240: 6c 65 20 58 59 5a 2e 20 20 42 75 74 20 79 6f 75  le XYZ.  But you
2250: 20 63 61 6e 6e 6f 74 20 68 61 76 65 20 74 77 6f   cannot have two
2260: 20 70 72 6f 63 65 73 73 65 73 20 72 65 61 64 69   processes readi
2270: 6e 67 0a 61 6e 64 20 77 72 69 74 69 6e 67 20 74  ng.and writing t
2280: 61 62 6c 65 20 41 42 43 20 61 74 20 74 68 65 20  able ABC at the 
2290: 73 61 6d 65 20 74 69 6d 65 2e 0a 3c 2f 70 3e 3c  same time..</p><
22a0: 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f  /dd>.<dt>SQLITE_
22b0: 4e 4f 4d 45 4d 3c 2f 64 74 3e 0a 3c 64 64 3e 3c  NOMEM</dt>.<dd><
22c0: 70 3e 54 68 69 73 20 76 61 6c 75 65 20 69 73 20  p>This value is 
22d0: 72 65 74 75 72 6e 65 64 20 69 66 20 61 20 63 61  returned if a ca
22e0: 6c 6c 20 74 6f 20 3c 62 3e 6d 61 6c 6c 6f 63 28  ll to <b>malloc(
22f0: 29 3c 2f 62 3e 20 66 61 69 6c 73 2e 0a 3c 2f 70  )</b> fails..</p
2300: 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54  ></dd>.<dt>SQLIT
2310: 45 5f 52 45 41 44 4f 4e 4c 59 3c 2f 64 74 3e 0a  E_READONLY</dt>.
2320: 3c 64 64 3e 3c 70 3e 54 68 69 73 20 72 65 74 75  <dd><p>This retu
2330: 72 6e 20 63 6f 64 65 20 69 6e 64 69 63 61 74 65  rn code indicate
2340: 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
2350: 74 20 77 61 73 20 6d 61 64 65 20 74 6f 20 77 72  t was made to wr
2360: 69 74 65 20 74 6f 0a 61 20 64 61 74 61 62 61 73  ite to.a databas
2370: 65 20 66 69 6c 65 20 74 68 61 74 20 77 61 73 20  e file that was 
2380: 6f 72 69 67 69 6e 61 6c 6c 79 20 6f 70 65 6e 65  originally opene
2390: 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e  d for reading on
23a0: 6c 79 2e 20 20 54 68 69 73 20 63 61 6e 0a 68 61  ly.  This can.ha
23b0: 70 70 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c  ppen if the call
23c0: 62 61 63 6b 20 66 72 6f 6d 20 61 20 71 75 65 72  back from a quer
23d0: 79 20 61 74 74 65 6d 70 74 73 20 74 6f 20 75 70  y attempts to up
23e0: 64 61 74 65 20 74 68 65 20 74 61 62 6c 65 0a 62  date the table.b
23f0: 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 3c 2f  eing queried..</
2400: 70 3e 3c 2f 64 64 3e 0a 3c 2f 64 6c 3e 0a 3c 2f  p></dd>.</dl>.</
2410: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 68 32  blockquote>..<h2
2420: 3e 51 75 65 72 79 69 6e 67 20 77 69 74 68 6f 75  >Querying withou
2430: 74 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 62 61  t using a callba
2440: 63 6b 20 66 75 6e 63 74 69 6f 6e 3c 2f 68 32 3e  ck function</h2>
2450: 0a 0a 3c 70 3e 54 68 65 20 3c 62 3e 73 71 6c 69  ..<p>The <b>sqli
2460: 74 65 5f 67 65 74 5f 74 61 62 6c 65 28 29 3c 2f  te_get_table()</
2470: 62 3e 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  b> function is a
2480: 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
2490: 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 28 29  <b>sqlite_exec()
24a0: 3c 2f 62 3e 20 74 68 61 74 20 63 6f 6c 6c 65 63  </b> that collec
24b0: 74 73 20 61 6c 6c 20 74 68 65 20 69 6e 66 6f 72  ts all the infor
24c0: 6d 61 74 69 6f 6e 20 66 72 6f 6d 20 73 75 63 63  mation from succ
24d0: 65 73 73 69 76 65 0a 63 61 6c 6c 62 61 63 6b 73  essive.callbacks
24e0: 20 61 6e 64 20 77 72 69 74 65 20 69 74 20 69 6e   and write it in
24f0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
2500: 65 64 20 66 72 6f 6d 20 6d 61 6c 6c 6f 63 28 29  ed from malloc()
2510: 2e 20 20 54 68 69 73 0a 69 73 20 61 20 63 6f 6e  .  This.is a con
2520: 76 65 6e 69 65 6e 63 65 20 66 75 6e 63 74 69 6f  venience functio
2530: 6e 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 74 68  n that allows th
2540: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  e application to
2550: 20 67 65 74 20 74 68 65 0a 65 6e 74 69 72 65 20   get the.entire 
2560: 72 65 73 75 6c 74 20 6f 66 20 61 20 64 61 74 61  result of a data
2570: 62 61 73 65 20 71 75 65 72 79 20 77 69 74 68 20  base query with 
2580: 61 20 73 69 6e 67 6c 65 20 66 75 6e 63 74 69 6f  a single functio
2590: 6e 20 63 61 6c 6c 2e 3c 2f 70 3e 0a 0a 3c 70 3e  n call.</p>..<p>
25a0: 54 68 65 20 6d 61 69 6e 20 72 65 73 75 6c 74 20  The main result 
25b0: 66 72 6f 6d 20 3c 62 3e 73 71 6c 69 74 65 5f 67  from <b>sqlite_g
25c0: 65 74 5f 74 61 62 6c 65 28 29 3c 2f 62 3e 20 69  et_table()</b> i
25d0: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
25e0: 69 6e 74 65 72 73 0a 74 6f 20 73 74 72 69 6e 67  inters.to string
25f0: 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65  s.  There is one
2600: 20 65 6c 65 6d 65 6e 74 20 69 6e 20 74 68 69 73   element in this
2610: 20 61 72 72 61 79 20 66 6f 72 20 65 61 63 68 20   array for each 
2620: 63 6f 6c 75 6d 6e 20 6f 66 0a 65 61 63 68 20 72  column of.each r
2630: 6f 77 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ow in the result
2640: 2e 20 20 4e 55 4c 4c 20 72 65 73 75 6c 74 73 20  .  NULL results 
2650: 61 72 65 20 72 65 70 72 65 73 65 6e 74 65 64 20  are represented 
2660: 62 79 20 61 20 4e 55 4c 4c 0a 70 6f 69 6e 74 65  by a NULL.pointe
2670: 72 2e 20 49 6e 20 61 64 64 69 74 69 6f 6e 20 74  r. In addition t
2680: 6f 20 74 68 65 20 72 65 67 75 6c 61 72 20 64 61  o the regular da
2690: 74 61 2c 20 74 68 65 72 65 20 69 73 20 61 6e 20  ta, there is an 
26a0: 61 64 64 65 64 20 72 6f 77 20 61 74 20 74 68 65  added row at the
26b0: 20 0a 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 74   .beginning of t
26c0: 68 65 20 61 72 72 61 79 20 74 68 61 74 20 63 6f  he array that co
26d0: 6e 74 61 69 6e 73 20 74 68 65 20 6e 61 6d 65 73  ntains the names
26e0: 20 6f 66 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20   of each column 
26f0: 6f 66 20 74 68 65 0a 72 65 73 75 6c 74 2e 3c 2f  of the.result.</
2700: 70 3e 0a 0a 3c 70 3e 41 73 20 61 6e 20 65 78 61  p>..<p>As an exa
2710: 6d 70 6c 65 2c 20 63 6f 6e 73 69 64 65 72 20 74  mple, consider t
2720: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65  he following que
2730: 72 79 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71  ry:</p>..<blockq
2740: 75 6f 74 65 3e 0a 53 45 4c 45 43 54 20 65 6d 70  uote>.SELECT emp
2750: 6c 6f 79 65 65 5f 6e 61 6d 65 2c 20 6c 6f 67 69  loyee_name, logi
2760: 6e 2c 20 68 6f 73 74 20 46 52 4f 4d 20 75 73 65  n, host FROM use
2770: 72 73 20 57 48 45 52 45 20 6c 6f 67 69 63 20 4c  rs WHERE logic L
2780: 49 4b 45 20 27 64 25 27 3b 0a 3c 2f 62 6c 6f 63  IKE 'd%';.</bloc
2790: 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 69 73  kquote>..<p>This
27a0: 20 71 75 65 72 79 20 77 69 6c 6c 20 72 65 74 75   query will retu
27b0: 72 6e 20 74 68 65 20 6e 61 6d 65 2c 20 6c 6f 67  rn the name, log
27c0: 69 6e 20 61 6e 64 20 68 6f 73 74 20 63 6f 6d 70  in and host comp
27d0: 75 74 65 72 20 6e 61 6d 65 0a 66 6f 72 20 65 76  uter name.for ev
27e0: 65 72 79 20 65 6d 70 6c 6f 79 65 65 20 77 68 6f  ery employee who
27f0: 73 65 20 6c 6f 67 69 6e 20 62 65 67 69 6e 73 20  se login begins 
2800: 77 69 74 68 20 74 68 65 20 6c 65 74 74 65 72 20  with the letter 
2810: 22 64 22 2e 20 20 49 66 20 74 68 69 73 0a 71 75  "d".  If this.qu
2820: 65 72 79 20 69 73 20 73 75 62 6d 69 74 74 65 64  ery is submitted
2830: 20 74 6f 20 3c 62 3e 73 71 6c 69 74 65 5f 67 65   to <b>sqlite_ge
2840: 74 5f 74 61 62 6c 65 28 29 3c 2f 62 3e 20 74 68  t_table()</b> th
2850: 65 20 72 65 73 75 6c 74 20 6d 69 67 68 74 0a 6c  e result might.l
2860: 6f 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a 3c 2f  ook like this:</
2870: 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  p>..<blockquote>
2880: 0a 6e 72 6f 77 20 3d 20 32 3c 62 72 3e 0a 6e 63  .nrow = 2<br>.nc
2890: 6f 6c 75 6d 6e 20 3d 20 33 3c 62 72 3e 0a 72 65  olumn = 3<br>.re
28a0: 73 75 6c 74 5b 30 5d 20 3d 20 22 65 6d 70 6c 6f  sult[0] = "emplo
28b0: 79 65 65 5f 6e 61 6d 65 22 3c 62 72 3e 0a 72 65  yee_name"<br>.re
28c0: 73 75 6c 74 5b 31 5d 20 3d 20 22 6c 6f 67 69 6e  sult[1] = "login
28d0: 22 3c 62 72 3e 0a 72 65 73 75 6c 74 5b 32 5d 20  "<br>.result[2] 
28e0: 3d 20 22 68 6f 73 74 22 3c 62 72 3e 0a 72 65 73  = "host"<br>.res
28f0: 75 6c 74 5b 33 5d 20 3d 20 22 64 75 6d 6d 79 22  ult[3] = "dummy"
2900: 3c 62 72 3e 0a 72 65 73 75 6c 74 5b 34 5d 20 3d  <br>.result[4] =
2910: 20 22 4e 6f 20 73 75 63 68 20 75 73 65 72 22 3c   "No such user"<
2920: 62 72 3e 0a 72 65 73 75 6c 74 5b 35 5d 20 3d 20  br>.result[5] = 
2930: 30 3c 62 72 3e 0a 72 65 73 75 6c 74 5b 36 5d 20  0<br>.result[6] 
2940: 3d 20 22 44 2e 20 52 69 63 68 61 72 64 20 48 69  = "D. Richard Hi
2950: 70 70 22 3c 62 72 3e 0a 72 65 73 75 6c 74 5b 37  pp"<br>.result[7
2960: 5d 20 3d 20 22 64 72 68 22 3c 62 72 3e 0a 72 65  ] = "drh"<br>.re
2970: 73 75 6c 74 5b 38 5d 20 3d 20 22 7a 61 64 6f 6b  sult[8] = "zadok
2980: 22 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ".</blockquote>.
2990: 0a 3c 70 3e 4e 6f 74 69 63 65 20 74 68 61 74 20  .<p>Notice that 
29a0: 74 68 65 20 22 68 6f 73 74 22 20 76 61 6c 75 65  the "host" value
29b0: 20 66 6f 72 20 74 68 65 20 22 64 75 6d 6d 79 22   for the "dummy"
29c0: 20 72 65 63 6f 72 64 20 69 73 20 4e 55 4c 4c 20   record is NULL 
29d0: 73 6f 0a 74 68 65 20 72 65 73 75 6c 74 5b 5d 20  so.the result[] 
29e0: 61 72 72 61 79 20 63 6f 6e 74 61 69 6e 73 20 61  array contains a
29f0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 74   NULL pointer at
2a00: 20 74 68 61 74 20 73 6c 6f 74 2e 3c 2f 70 3e 0a   that slot.</p>.
2a10: 0a 3c 70 3e 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  .<p>Memory to ho
2a20: 6c 64 20 74 68 65 20 69 6e 66 6f 72 6d 61 74 69  ld the informati
2a30: 6f 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 3c  on returned by <
2a40: 62 3e 73 71 6c 69 74 65 5f 67 65 74 5f 74 61 62  b>sqlite_get_tab
2a50: 6c 65 28 29 3c 2f 62 3e 0a 69 73 20 6f 62 74 61  le()</b>.is obta
2a60: 69 6e 65 64 20 66 72 6f 6d 20 6d 61 6c 6c 6f 63  ined from malloc
2a70: 28 29 2e 20 20 42 75 74 20 74 68 65 20 63 61 6c  ().  But the cal
2a80: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68  ling function sh
2a90: 6f 75 6c 64 20 6e 6f 74 20 74 72 79 0a 74 6f 20  ould not try.to 
2aa0: 66 72 65 65 20 74 68 69 73 20 69 6e 66 6f 72 6d  free this inform
2ab0: 61 74 69 6f 6e 20 64 69 72 65 63 74 6c 79 2e 20  ation directly. 
2ac0: 20 49 6e 73 74 65 61 64 2c 20 70 61 73 73 20 74   Instead, pass t
2ad0: 68 65 20 63 6f 6d 70 6c 65 74 65 20 74 61 62 6c  he complete tabl
2ae0: 65 0a 74 6f 20 3c 62 3e 73 71 6c 69 74 65 5f 66  e.to <b>sqlite_f
2af0: 72 65 65 5f 74 61 62 6c 65 28 29 3c 2f 62 3e 20  ree_table()</b> 
2b00: 77 68 65 6e 20 74 68 65 20 74 61 62 6c 65 20 69  when the table i
2b10: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  s no longer need
2b20: 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20  ed.</p>..<p>The 
2b30: 3c 62 3e 73 71 6c 69 74 65 5f 67 65 74 5f 74 61  <b>sqlite_get_ta
2b40: 62 6c 65 28 29 3c 2f 62 3e 20 72 6f 75 74 69 6e  ble()</b> routin
2b50: 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 61  e returns the sa
2b60: 6d 65 20 69 6e 74 65 67 65 72 0a 72 65 73 75 6c  me integer.resul
2b70: 74 20 63 6f 64 65 20 61 73 20 3c 62 3e 73 71 6c  t code as <b>sql
2b80: 69 74 65 5f 65 78 65 63 28 29 3c 2f 62 3e 2e 3c  ite_exec()</b>.<
2b90: 2f 70 3e 0a 0a 3c 68 32 3e 54 65 73 74 69 6e 67  /p>..<h2>Testing
2ba0: 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 20   for a complete 
2bb0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 3c 2f 68  SQL statement</h
2bc0: 32 3e 0a 0a 3c 70 3e 54 68 65 20 6e 65 78 74 20  2>..<p>The next 
2bd0: 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
2be0: 65 20 74 6f 20 53 51 4c 69 74 65 20 69 73 20 61  e to SQLite is a
2bf0: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 66 75 6e   convenience fun
2c00: 63 74 69 6f 6e 20 75 73 65 64 0a 74 6f 20 74 65  ction used.to te
2c10: 73 74 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  st whether or no
2c20: 74 20 61 20 73 74 72 69 6e 67 20 66 6f 72 6d 73  t a string forms
2c30: 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
2c40: 73 74 61 74 65 6d 65 6e 74 2e 0a 49 66 20 74 68  statement..If th
2c50: 65 20 3c 62 3e 73 71 6c 69 74 65 5f 63 6f 6d 70  e <b>sqlite_comp
2c60: 6c 65 74 65 28 29 3c 2f 62 3e 20 66 75 6e 63 74  lete()</b> funct
2c70: 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 72 75 65  ion returns true
2c80: 20 77 68 65 6e 20 69 74 73 20 69 6e 70 75 74 0a   when its input.
2c90: 69 73 20 61 20 73 74 72 69 6e 67 2c 20 74 68 65  is a string, the
2ca0: 6e 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 66  n the argument f
2cb0: 6f 72 6d 73 20 61 20 63 6f 6d 70 6c 65 74 65 20  orms a complete 
2cc0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 54  SQL statement..T
2cd0: 68 65 72 65 20 61 72 65 20 6e 6f 20 67 75 61 72  here are no guar
2ce0: 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
2cf0: 73 79 6e 74 61 78 20 6f 66 20 74 68 61 74 20 73  syntax of that s
2d00: 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 72 72  tatement is corr
2d10: 65 63 74 2c 0a 62 75 74 20 77 65 20 61 74 20 6c  ect,.but we at l
2d20: 65 61 73 74 20 6b 6e 6f 77 20 74 68 65 20 73 74  east know the st
2d30: 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6d 70 6c  atement is compl
2d40: 65 74 65 2e 20 20 49 66 20 3c 62 3e 73 71 6c 69  ete.  If <b>sqli
2d50: 74 65 5f 63 6f 6d 70 6c 65 74 65 28 29 3c 2f 62  te_complete()</b
2d60: 3e 0a 72 65 74 75 72 6e 73 20 66 61 6c 73 65 2c  >.returns false,
2d70: 20 74 68 65 6e 20 6d 6f 72 65 20 74 65 78 74 20   then more text 
2d80: 69 73 20 72 65 71 75 69 72 65 64 20 74 6f 20 63  is required to c
2d90: 6f 6d 70 6c 65 74 65 20 74 68 65 20 53 51 4c 20  omplete the SQL 
2da0: 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 70 3e 0a 0a  statement.</p>..
2db0: 3c 70 3e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  <p>For the purpo
2dc0: 73 65 20 6f 66 20 74 68 65 20 3c 62 3e 73 71 6c  se of the <b>sql
2dd0: 69 74 65 5f 63 6f 6d 70 6c 65 74 65 28 29 3c 2f  ite_complete()</
2de0: 62 3e 20 66 75 6e 63 74 69 6f 6e 2c 20 61 6e 20  b> function, an 
2df0: 53 51 4c 0a 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL.statement is
2e00: 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20   complete if it 
2e10: 65 6e 64 73 20 69 6e 20 61 20 73 65 6d 69 63 6f  ends in a semico
2e20: 6c 6f 6e 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65  lon.</p>..<p>The
2e30: 20 3c 62 3e 73 71 6c 69 74 65 3c 2f 62 3e 20 63   <b>sqlite</b> c
2e40: 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 75 74 69 6c  ommand-line util
2e50: 69 74 79 20 75 73 65 73 20 74 68 65 20 3c 62 3e  ity uses the <b>
2e60: 73 71 6c 69 74 65 5f 63 6f 6d 70 6c 65 74 65 28  sqlite_complete(
2e70: 29 3c 2f 62 3e 0a 66 75 6e 63 74 69 6f 6e 20 74  )</b>.function t
2e80: 6f 20 6b 6e 6f 77 20 77 68 65 6e 20 69 74 20 6e  o know when it n
2e90: 65 65 64 73 20 74 6f 20 63 61 6c 6c 20 3c 62 3e  eeds to call <b>
2ea0: 73 71 6c 69 74 65 5f 65 78 65 63 28 29 3c 2f 62  sqlite_exec()</b
2eb0: 3e 2e 20 20 41 66 74 65 72 20 65 61 63 68 0a 6c  >.  After each.l
2ec0: 69 6e 65 20 6f 66 20 69 6e 70 75 74 20 69 73 20  ine of input is 
2ed0: 72 65 63 65 69 76 65 64 2c 20 3c 62 3e 73 71 6c  received, <b>sql
2ee0: 69 74 65 3c 2f 62 3e 20 63 61 6c 6c 73 20 3c 62  ite</b> calls <b
2ef0: 3e 73 71 6c 69 74 65 5f 63 6f 6d 70 6c 65 74 65  >sqlite_complete
2f00: 28 29 3c 2f 62 3e 0a 6f 6e 20 61 6c 6c 20 69 6e  ()</b>.on all in
2f10: 70 75 74 20 69 6e 20 69 74 73 20 62 75 66 66 65  put in its buffe
2f20: 72 2e 20 20 49 66 20 3c 62 3e 73 71 6c 69 74 65  r.  If <b>sqlite
2f30: 5f 63 6f 6d 70 6c 65 74 65 28 29 3c 2f 62 3e 20  _complete()</b> 
2f40: 72 65 74 75 72 6e 73 20 74 72 75 65 2c 20 0a 74  returns true, .t
2f50: 68 65 6e 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78  hen <b>sqlite_ex
2f60: 65 63 28 29 3c 2f 62 3e 20 69 73 20 63 61 6c 6c  ec()</b> is call
2f70: 65 64 20 61 6e 64 20 74 68 65 20 69 6e 70 75 74  ed and the input
2f80: 20 62 75 66 66 65 72 20 69 73 20 72 65 73 65 74   buffer is reset
2f90: 2e 20 20 49 66 0a 3c 62 3e 73 71 6c 69 74 65 5f  .  If.<b>sqlite_
2fa0: 63 6f 6d 70 6c 65 74 65 28 29 3c 2f 62 3e 20 72  complete()</b> r
2fb0: 65 74 75 72 6e 73 20 66 61 6c 73 65 2c 20 74 68  eturns false, th
2fc0: 65 6e 20 74 68 65 20 70 72 6f 6d 70 74 20 69 73  en the prompt is
2fd0: 20 63 68 61 6e 67 65 64 20 74 6f 0a 74 68 65 20   changed to.the 
2fe0: 63 6f 6e 74 69 6e 75 61 74 69 6f 6e 20 70 72 6f  continuation pro
2ff0: 6d 70 74 20 61 6e 64 20 61 6e 6f 74 68 65 72 20  mpt and another 
3000: 6c 69 6e 65 20 6f 66 20 74 65 78 74 20 69 73 20  line of text is 
3010: 72 65 61 64 20 61 6e 64 20 61 64 64 65 64 20 74  read and added t
3020: 6f 0a 74 68 65 20 69 6e 70 75 74 20 62 75 66 66  o.the input buff
3030: 65 72 2e 3c 2f 70 3e 0a 0a 3c 68 32 3e 4c 69 62  er.</p>..<h2>Lib
3040: 72 61 72 79 20 76 65 72 73 69 6f 6e 20 73 74 72  rary version str
3050: 69 6e 67 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 68 65  ing</h2>..<p>The
3060: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
3070: 65 78 70 6f 72 74 73 20 74 68 65 20 73 74 72 69  exports the stri
3080: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 6e 61 6d 65  ng constant name
3090: 64 0a 3c 62 3e 73 71 6c 69 74 65 5f 76 65 72 73  d.<b>sqlite_vers
30a0: 69 6f 6e 3c 2f 62 3e 20 77 68 69 63 68 20 63 6f  ion</b> which co
30b0: 6e 74 61 69 6e 73 20 74 68 65 20 76 65 72 73 69  ntains the versi
30c0: 6f 6e 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 65  on number of the
30d0: 0a 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 68  .library.  The h
30e0: 65 61 64 65 72 20 66 69 6c 65 20 63 6f 6e 74 61  eader file conta
30f0: 69 6e 73 20 61 20 6d 61 63 72 6f 20 53 51 4c 49  ins a macro SQLI
3100: 54 45 5f 56 45 52 53 49 4f 4e 0a 77 69 74 68 20  TE_VERSION.with 
3110: 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
3120: 74 69 6f 6e 2e 20 20 49 66 20 64 65 73 69 72 65  tion.  If desire
3130: 64 2c 20 61 20 70 72 6f 67 72 61 6d 20 63 61 6e  d, a program can
3140: 20 63 6f 6d 70 61 72 65 0a 74 68 65 20 53 51 4c   compare.the SQL
3150: 49 54 45 5f 56 45 52 53 49 4f 4e 20 6d 61 63 72  ITE_VERSION macr
3160: 6f 20 61 67 61 69 6e 73 74 20 74 68 65 20 3c 62  o against the <b
3170: 3e 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 3c  >sqlite_version<
3180: 2f 62 3e 0a 73 74 72 69 6e 67 20 63 6f 6e 73 74  /b>.string const
3190: 61 6e 74 20 74 6f 20 76 65 72 69 66 79 20 74 68  ant to verify th
31a0: 61 74 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e  at the version n
31b0: 75 6d 62 65 72 20 6f 66 20 74 68 65 0a 68 65 61  umber of the.hea
31c0: 64 65 72 20 66 69 6c 65 20 61 6e 64 20 74 68 65  der file and the
31d0: 20 6c 69 62 72 61 72 79 20 6d 61 74 63 68 2e 3c   library match.<
31e0: 2f 70 3e 20 0a 0a 3c 68 32 3e 43 68 61 6e 67 69  /p> ..<h2>Changi
31f0: 6e 67 20 74 68 65 20 6c 69 62 72 61 72 69 65 73  ng the libraries
3200: 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 6c 6f 63   response to loc
3210: 6b 65 64 20 66 69 6c 65 73 3c 2f 68 32 3e 0a 0a  ked files</h2>..
3220: 3c 70 3e 54 68 65 20 47 44 42 4d 20 6c 69 62 72  <p>The GDBM libr
3230: 61 72 79 20 73 75 70 70 6f 72 74 73 20 64 61 74  ary supports dat
3240: 61 62 61 73 65 20 6c 6f 63 6b 73 20 61 74 20 74  abase locks at t
3250: 68 65 20 66 69 6c 65 20 6c 65 76 65 6c 2e 0a 49  he file level..I
3260: 66 20 61 20 47 44 42 4d 20 64 61 74 61 62 61 73  f a GDBM databas
3270: 65 20 66 69 6c 65 20 69 73 20 6f 70 65 6e 65 64  e file is opened
3280: 20 66 6f 72 20 72 65 61 64 69 6e 67 2c 20 74 68   for reading, th
3290: 65 6e 20 74 68 61 74 20 73 61 6d 65 0a 66 69 6c  en that same.fil
32a0: 65 20 63 61 6e 6e 6f 74 20 62 65 20 72 65 6f 70  e cannot be reop
32b0: 65 6e 65 64 20 66 6f 72 20 77 72 69 74 69 6e 67  ened for writing
32c0: 20 75 6e 74 69 6c 20 61 6c 6c 20 72 65 61 64 65   until all reade
32d0: 72 73 20 68 61 76 65 20 63 6c 6f 73 65 64 0a 74  rs have closed.t
32e0: 68 65 20 66 69 6c 65 2e 20 20 49 66 20 61 20 47  he file.  If a G
32f0: 44 42 4d 20 66 69 6c 65 20 69 73 20 6f 70 65 6e  DBM file is open
3300: 20 66 6f 72 20 77 72 69 74 69 6e 67 2c 20 74 68   for writing, th
3310: 65 6e 20 74 68 65 20 66 69 6c 65 20 63 61 6e 6e  en the file cann
3320: 6f 74 0a 62 65 20 72 65 6f 70 65 6e 65 64 20 66  ot.be reopened f
3330: 6f 72 20 72 65 61 64 69 6e 67 20 6f 72 20 77 72  or reading or wr
3340: 69 74 69 6e 67 20 75 6e 74 69 6c 20 69 74 20 69  iting until it i
3350: 73 20 63 6c 6f 73 65 64 2e 3c 2f 70 3e 0a 0a 3c  s closed.</p>..<
3360: 70 3e 49 66 20 74 68 65 20 53 51 4c 69 74 65 20  p>If the SQLite 
3370: 6c 69 62 72 61 72 79 20 61 74 74 65 6d 70 74 73  library attempts
3380: 20 74 6f 20 6f 70 65 6e 20 61 20 47 44 42 4d 20   to open a GDBM 
3390: 66 69 6c 65 20 61 6e 64 20 66 69 6e 64 73 20 74  file and finds t
33a0: 68 61 74 0a 74 68 65 20 66 69 6c 65 20 69 73 20  hat.the file is 
33b0: 6c 6f 63 6b 65 64 2c 20 74 68 65 20 64 65 66 61  locked, the defa
33c0: 75 6c 74 20 61 63 74 69 6f 6e 20 69 73 20 74 6f  ult action is to
33d0: 20 61 62 6f 72 74 20 74 68 65 20 63 75 72 72 65   abort the curre
33e0: 6e 74 0a 6f 70 65 72 61 74 69 6f 6e 20 61 6e 64  nt.operation and
33f0: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 42   return SQLITE_B
3400: 55 53 59 2e 20 20 42 75 74 20 74 68 69 73 20 69  USY.  But this i
3410: 73 20 6e 6f 74 20 61 6c 77 61 79 73 20 74 68 65  s not always the
3420: 20 6d 6f 73 74 0a 63 6f 6e 76 65 6e 69 65 6e 74   most.convenient
3430: 20 62 65 68 61 76 69 6f 72 2c 20 73 6f 20 61 20   behavior, so a 
3440: 6d 65 63 68 61 6e 69 73 6d 20 65 78 69 73 74 73  mechanism exists
3450: 20 74 6f 20 63 68 61 6e 67 65 20 69 74 2e 3c 2f   to change it.</
3460: 70 3e 0a 0a 3c 70 3e 54 68 65 20 3c 62 3e 73 71  p>..<p>The <b>sq
3470: 6c 69 74 65 5f 62 75 73 79 5f 68 61 6e 64 6c 65  lite_busy_handle
3480: 72 28 29 3c 2f 62 3e 20 70 72 6f 63 65 64 75 72  r()</b> procedur
3490: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
34a0: 20 72 65 67 69 73 74 65 72 0a 61 20 62 75 73 79   register.a busy
34b0: 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
34c0: 6e 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61  n open SQLite da
34d0: 74 61 62 61 73 65 2e 20 20 54 68 65 20 62 75 73  tabase.  The bus
34e0: 79 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 0a  y callback will.
34f0: 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
3500: 76 65 72 20 53 51 4c 69 74 65 20 74 72 69 65 73  ver SQLite tries
3510: 20 74 6f 20 6f 70 65 6e 20 61 20 47 44 42 4d 20   to open a GDBM 
3520: 66 69 6c 65 20 74 68 61 74 20 69 73 20 6c 6f 63  file that is loc
3530: 6b 65 64 2e 0a 54 68 65 20 63 61 6c 6c 62 61 63  ked..The callbac
3540: 6b 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79  k will typically
3550: 20 64 6f 20 73 6f 6d 65 20 6f 74 68 65 72 20 75   do some other u
3560: 73 65 66 75 6c 20 77 6f 72 6b 2c 20 6f 72 20 70  seful work, or p
3570: 65 72 68 61 70 73 20 73 6c 65 65 70 2c 0a 69 6e  erhaps sleep,.in
3580: 20 6f 72 64 65 72 20 74 6f 20 67 69 76 65 20 74   order to give t
3590: 68 65 20 6c 6f 63 6b 20 61 20 63 68 61 6e 63 65  he lock a chance
35a0: 20 74 6f 20 63 6c 65 61 72 2e 20 20 49 66 20 74   to clear.  If t
35b0: 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
35c0: 72 6e 73 0a 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns.non-zero, th
35d0: 65 6e 20 53 51 4c 69 74 65 20 74 72 69 65 73 20  en SQLite tries 
35e0: 61 67 61 69 6e 20 74 6f 20 6f 70 65 6e 20 74 68  again to open th
35f0: 65 20 47 44 42 4d 20 66 69 6c 65 20 61 6e 64 20  e GDBM file and 
3600: 74 68 65 20 63 79 63 6c 65 0a 72 65 70 65 61 74  the cycle.repeat
3610: 73 2e 20 20 49 66 20 74 68 65 20 63 61 6c 6c 62  s.  If the callb
3620: 61 63 6b 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ack returns zero
3630: 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 62  , then SQLite ab
3640: 6f 72 74 73 20 74 68 65 20 63 75 72 72 65 6e 74  orts the current
3650: 0a 6f 70 65 72 61 74 69 6f 6e 20 61 6e 64 20 72  .operation and r
3660: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 42 55  eturns SQLITE_BU
3670: 53 59 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20  SY.</p>..<p>The 
3680: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 3c 62 3e  arguments to <b>
3690: 73 71 6c 69 74 65 5f 62 75 73 79 5f 68 61 6e 64  sqlite_busy_hand
36a0: 6c 65 72 28 29 3c 2f 62 3e 20 61 72 65 20 74 68  ler()</b> are th
36b0: 65 20 6f 70 61 71 75 65 0a 73 74 72 75 63 74 75  e opaque.structu
36c0: 72 65 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  re returned from
36d0: 20 3c 62 3e 73 71 6c 69 74 65 5f 6f 70 65 6e 28   <b>sqlite_open(
36e0: 29 3c 2f 62 3e 2c 20 61 20 70 6f 69 6e 74 65 72  )</b>, a pointer
36f0: 20 74 6f 20 74 68 65 20 62 75 73 79 0a 63 61 6c   to the busy.cal
3700: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2c 20  lback function, 
3710: 61 6e 64 20 61 20 67 65 6e 65 72 69 63 20 70 6f  and a generic po
3720: 69 6e 74 65 72 20 74 68 61 74 20 77 69 6c 6c 20  inter that will 
3730: 62 65 20 70 61 73 73 65 64 20 61 73 0a 74 68 65  be passed as.the
3740: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
3750: 74 6f 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  to the busy call
3760: 62 61 63 6b 2e 20 20 57 68 65 6e 20 53 51 4c 69  back.  When SQLi
3770: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 0a 62  te invokes the.b
3780: 75 73 79 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74  usy callback, it
3790: 20 73 65 6e 64 73 20 69 74 20 74 68 72 65 65 20   sends it three 
37a0: 61 72 67 75 6d 65 6e 74 73 3a 20 20 74 68 65 20  arguments:  the 
37b0: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 0a  generic pointer.
37c0: 74 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20  that was passed 
37d0: 69 6e 20 61 73 20 74 68 65 20 74 68 69 72 64 20  in as the third 
37e0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 3c 62 3e 73  argument to <b>s
37f0: 71 6c 69 74 65 5f 62 75 73 79 5f 68 61 6e 64 6c  qlite_busy_handl
3800: 65 72 3c 2f 62 3e 2c 0a 74 68 65 20 6e 61 6d 65  er</b>,.the name
3810: 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
3820: 20 74 61 62 6c 65 20 6f 72 20 69 6e 64 65 78 20   table or index 
3830: 74 68 61 74 20 74 68 65 20 6c 69 62 72 61 72 79  that the library
3840: 20 69 73 20 74 72 79 69 6e 67 0a 74 6f 20 6f 70   is trying.to op
3850: 65 6e 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62  en, and the numb
3860: 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
3870: 20 74 68 65 20 6c 69 62 72 61 72 79 20 68 61 73   the library has
3880: 20 61 74 74 65 6d 70 74 65 64 20 74 6f 0a 6f 70   attempted to.op
3890: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
38a0: 74 61 62 6c 65 20 6f 72 20 69 6e 64 65 78 2e 3c  table or index.<
38b0: 2f 70 3e 0a 0a 3c 70 3e 46 6f 72 20 74 68 65 20  /p>..<p>For the 
38c0: 63 6f 6d 6d 6f 6e 20 63 61 73 65 20 77 68 65 72  common case wher
38d0: 65 20 77 65 20 77 61 6e 74 20 74 68 65 20 62 75  e we want the bu
38e0: 73 79 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 73  sy callback to s
38f0: 6c 65 65 70 2c 0a 74 68 65 20 53 51 4c 69 74 65  leep,.the SQLite
3900: 20 6c 69 62 72 61 72 79 20 70 72 6f 76 69 64 65   library provide
3910: 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20  s a convenience 
3920: 72 6f 75 74 69 6e 65 20 3c 62 3e 73 71 6c 69 74  routine <b>sqlit
3930: 65 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  e_busy_timeout()
3940: 3c 2f 62 3e 2e 0a 54 68 65 20 66 69 72 73 74 20  </b>..The first 
3950: 61 72 67 75 6d 65 6e 74 20 74 6f 20 3c 62 3e 73  argument to <b>s
3960: 71 6c 69 74 65 5f 62 75 73 79 5f 74 69 6d 65 6f  qlite_busy_timeo
3970: 75 74 28 29 3c 2f 62 3e 20 69 73 20 61 20 70 6f  ut()</b> is a po
3980: 69 6e 74 65 72 20 74 6f 0a 61 6e 20 6f 70 65 6e  inter to.an open
3990: 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
39a0: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
39b0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 6e 75  argument is a nu
39c0: 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
39d0: 6f 6e 64 73 2e 0a 41 66 74 65 72 20 3c 62 3e 73  onds..After <b>s
39e0: 71 6c 69 74 65 5f 62 75 73 79 5f 74 69 6d 65 6f  qlite_busy_timeo
39f0: 75 74 28 29 3c 2f 62 3e 20 68 61 73 20 62 65 65  ut()</b> has bee
3a00: 6e 20 65 78 65 63 75 74 65 64 2c 20 74 68 65 20  n executed, the 
3a10: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 0a 77  SQLite library.w
3a20: 69 6c 6c 20 77 61 69 74 20 66 6f 72 20 74 68 65  ill wait for the
3a30: 20 6c 6f 63 6b 20 74 6f 20 63 6c 65 61 72 20 66   lock to clear f
3a40: 6f 72 20 61 74 20 6c 65 61 73 74 20 74 68 65 20  or at least the 
3a50: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
3a60: 65 63 6f 6e 64 73 20 0a 73 70 65 63 69 66 69 65  econds .specifie
3a70: 64 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75  d before it retu
3a80: 72 6e 73 20 53 51 4c 49 54 45 5f 42 55 53 59 2e  rns SQLITE_BUSY.
3a90: 20 20 53 70 65 63 69 66 79 69 6e 67 20 7a 65 72    Specifying zer
3aa0: 6f 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 66  o milliseconds f
3ab0: 6f 72 0a 74 68 65 20 74 69 6d 65 6f 75 74 20 72  or.the timeout r
3ac0: 65 73 74 6f 72 65 73 20 74 68 65 20 64 65 66 61  estores the defa
3ad0: 75 6c 74 20 62 65 68 61 76 69 6f 72 2e 3c 2f 70  ult behavior.</p
3ae0: 3e 0a 0a 3c 68 32 3e 55 73 69 6e 67 20 74 68 65  >..<h2>Using the
3af0: 20 3c 74 74 3e 5f 70 72 69 6e 74 66 28 29 3c 2f   <tt>_printf()</
3b00: 74 74 3e 20 77 72 61 70 70 65 72 20 66 75 6e 63  tt> wrapper func
3b10: 74 69 6f 6e 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 54  tions</h2>..<p>T
3b20: 68 65 20 66 6f 75 72 20 75 74 69 6c 69 74 79 20  he four utility 
3b30: 66 75 6e 63 74 69 6f 6e 73 3c 2f 70 3e 0a 0a 3c  functions</p>..<
3b40: 70 3e 0a 3c 75 6c 3e 0a 3c 6c 69 3e 3c 62 3e 73  p>.<ul>.<li><b>s
3b50: 71 6c 69 74 65 5f 65 78 65 63 5f 70 72 69 6e 74  qlite_exec_print
3b60: 66 28 29 3c 2f 62 3e 3c 2f 6c 69 3e 0a 3c 6c 69  f()</b></li>.<li
3b70: 3e 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 5f  ><b>sqlite_exec_
3b80: 76 70 72 69 6e 74 66 28 29 3c 2f 62 3e 3c 2f 6c  vprintf()</b></l
3b90: 69 3e 0a 3c 6c 69 3e 3c 62 3e 73 71 6c 69 74 65  i>.<li><b>sqlite
3ba0: 5f 67 65 74 5f 74 61 62 6c 65 5f 70 72 69 6e 74  _get_table_print
3bb0: 66 28 29 3c 2f 62 3e 3c 2f 6c 69 3e 0a 3c 6c 69  f()</b></li>.<li
3bc0: 3e 3c 62 3e 73 71 6c 69 74 65 5f 67 65 74 5f 74  ><b>sqlite_get_t
3bd0: 61 62 6c 65 5f 76 70 72 69 6e 74 66 28 29 3c 2f  able_vprintf()</
3be0: 62 3e 3c 2f 6c 69 3e 0a 3c 2f 75 6c 3e 0a 3c 2f  b></li>.</ul>.</
3bf0: 70 3e 0a 0a 3c 70 3e 69 6d 70 6c 65 6d 65 6e 74  p>..<p>implement
3c00: 20 74 68 65 20 73 61 6d 65 20 71 75 65 72 79 20   the same query 
3c10: 66 75 6e 63 74 69 6f 6e 61 6c 69 74 79 20 61 73  functionality as
3c20: 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 28   <b>sqlite_exec(
3c30: 29 3c 2f 62 3e 0a 61 6e 64 20 3c 62 3e 73 71 6c  )</b>.and <b>sql
3c40: 69 74 65 5f 67 65 74 5f 74 61 62 6c 65 28 29 3c  ite_get_table()<
3c50: 2f 62 3e 2e 20 20 42 75 74 20 69 6e 73 74 65 61  /b>.  But instea
3c60: 64 20 6f 66 20 74 61 6b 69 6e 67 20 61 20 63 6f  d of taking a co
3c70: 6d 70 6c 65 74 65 0a 53 51 4c 20 73 74 61 74 65  mplete.SQL state
3c80: 6d 65 6e 74 20 61 73 20 74 68 65 69 72 20 73 65  ment as their se
3c90: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 74  cond argument, t
3ca0: 68 65 20 66 6f 75 72 20 3c 62 3e 5f 70 72 69 6e  he four <b>_prin
3cb0: 74 66 3c 2f 62 3e 0a 72 6f 75 74 69 6e 65 73 20  tf</b>.routines 
3cc0: 74 61 6b 65 20 61 20 70 72 69 6e 74 66 2d 73 74  take a printf-st
3cd0: 79 6c 65 20 66 6f 72 6d 61 74 20 73 74 72 69 6e  yle format strin
3ce0: 67 2e 20 20 54 68 65 20 53 51 4c 20 73 74 61 74  g.  The SQL stat
3cf0: 65 6d 65 6e 74 20 74 6f 0a 62 65 20 65 78 65 63  ement to.be exec
3d00: 75 74 65 64 20 69 73 20 67 65 6e 65 72 61 74 65  uted is generate
3d10: 64 20 66 72 6f 6d 20 74 68 69 73 20 66 6f 72 6d  d from this form
3d20: 61 74 20 73 74 72 69 6e 67 20 61 6e 64 20 66 72  at string and fr
3d30: 6f 6d 20 77 68 61 74 65 76 65 72 0a 61 64 64 69  om whatever.addi
3d40: 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
3d50: 20 61 72 65 20 61 74 74 61 63 68 65 64 20 74 6f   are attached to
3d60: 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
3d70: 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 2e 3c 2f  function call.</
3d80: 70 3e 0a 0a 3c 70 3e 54 68 65 72 65 20 61 72 65  p>..<p>There are
3d90: 20 74 77 6f 20 61 64 76 61 6e 74 61 67 65 73 20   two advantages 
3da0: 74 6f 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c  to using the SQL
3db0: 69 74 65 20 70 72 69 6e 74 66 0a 66 75 6e 63 74  ite printf.funct
3dc0: 69 6f 6e 73 20 69 6e 73 74 65 61 64 20 6f 66 20  ions instead of 
3dd0: 3c 62 3e 73 70 72 69 6e 74 66 28 29 3c 2f 62 3e  <b>sprintf()</b>
3de0: 2e 20 20 46 69 72 73 74 20 6f 66 20 61 6c 6c 2c  .  First of all,
3df0: 20 77 69 74 68 20 74 68 65 0a 53 51 4c 69 74 65   with the.SQLite
3e00: 20 70 72 69 6e 74 66 20 72 6f 75 74 69 6e 65 73   printf routines
3e10: 2c 20 74 68 65 72 65 20 69 73 20 6e 65 76 65 72  , there is never
3e20: 20 61 20 64 61 6e 67 65 72 20 6f 66 20 6f 76 65   a danger of ove
3e30: 72 66 6c 6f 77 69 6e 67 20 61 0a 73 74 61 74 69  rflowing a.stati
3e40: 63 20 62 75 66 66 65 72 20 61 73 20 74 68 65 72  c buffer as ther
3e50: 65 20 69 73 20 77 69 74 68 20 3c 62 3e 73 70 72  e is with <b>spr
3e60: 69 6e 74 66 28 29 3c 2f 62 3e 2e 20 20 54 68 65  intf()</b>.  The
3e70: 20 53 51 4c 69 74 65 0a 70 72 69 6e 74 66 20 72   SQLite.printf r
3e80: 6f 75 74 69 6e 65 73 20 61 75 74 6f 6d 61 74 69  outines automati
3e90: 63 61 6c 6c 79 20 61 6c 6c 6f 63 61 74 65 20 28  cally allocate (
3ea0: 61 6e 64 20 6c 61 74 65 72 20 66 72 65 65 29 0a  and later free).
3eb0: 61 73 20 6d 75 63 68 20 6d 65 6d 6f 72 79 20 61  as much memory a
3ec0: 73 20 69 73 20 0a 6e 65 63 65 73 73 61 72 79 20  s is .necessary 
3ed0: 74 6f 20 68 6f 6c 64 20 74 68 65 20 53 51 4c 20  to hold the SQL 
3ee0: 73 74 61 74 65 6d 65 6e 74 73 20 67 65 6e 65 72  statements gener
3ef0: 61 74 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68  ated.</p>..<p>Th
3f00: 65 20 73 65 63 6f 6e 64 20 61 64 76 61 6e 74 61  e second advanta
3f10: 67 65 20 74 68 65 20 53 51 4c 69 74 65 20 70 72  ge the SQLite pr
3f20: 69 6e 74 66 20 72 6f 75 74 69 6e 65 73 20 68 61  intf routines ha
3f30: 76 65 20 6f 76 65 72 0a 3c 62 3e 73 70 72 69 6e  ve over.<b>sprin
3f40: 74 66 28 29 3c 2f 62 3e 20 69 73 20 61 20 6e 65  tf()</b> is a ne
3f50: 77 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  w formatting opt
3f60: 69 6f 6e 20 73 70 65 63 69 66 69 63 61 6c 6c 79  ion specifically
3f70: 20 64 65 73 69 67 6e 65 64 0a 74 6f 20 73 75 70   designed.to sup
3f80: 70 6f 72 74 20 73 74 72 69 6e 67 20 6c 69 74 65  port string lite
3f90: 72 61 6c 73 20 69 6e 20 53 51 4c 2e 20 20 57 69  rals in SQL.  Wi
3fa0: 74 68 69 6e 20 74 68 65 20 66 6f 72 6d 61 74 20  thin the format 
3fb0: 73 74 72 69 6e 67 2c 0a 74 68 65 20 25 71 20 66  string,.the %q f
3fc0: 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
3fd0: 20 77 6f 72 6b 73 20 76 65 72 79 20 6d 75 63 68   works very much
3fe0: 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
3ff0: 20 69 74 0a 72 65 61 64 73 20 61 20 6e 75 6c 6c   it.reads a null
4000: 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
4010: 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
4020: 6d 65 6e 74 20 6c 69 73 74 20 61 6e 64 20 69 6e  ment list and in
4030: 73 65 72 74 73 0a 69 74 20 69 6e 74 6f 20 74 68  serts.it into th
4040: 65 20 72 65 73 75 6c 74 2e 20 20 42 75 74 20 25  e result.  But %
4050: 71 20 74 72 61 6e 73 6c 61 74 65 73 20 74 68 65  q translates the
4060: 20 69 6e 73 65 72 74 65 64 20 73 74 72 69 6e 67   inserted string
4070: 20 62 79 0a 6d 61 6b 69 6e 67 20 74 77 6f 20 63   by.making two c
4080: 6f 70 69 65 73 20 6f 66 20 65 76 65 72 79 20 73  opies of every s
4090: 69 6e 67 6c 65 2d 71 75 6f 74 65 20 28 27 29 20  ingle-quote (') 
40a0: 63 68 61 72 61 63 74 65 72 20 69 6e 20 74 68 65  character in the
40b0: 0a 73 75 62 73 74 69 74 75 74 65 64 20 73 74 72  .substituted str
40c0: 69 6e 67 2e 20 20 54 68 69 73 20 68 61 73 20 74  ing.  This has t
40d0: 68 65 20 65 66 66 65 63 74 20 6f 66 20 65 73 63  he effect of esc
40e0: 61 70 69 6e 67 20 74 68 65 20 65 6e 64 2d 6f 66  aping the end-of
40f0: 2d 73 74 72 69 6e 67 0a 6d 65 61 6e 69 6e 67 20  -string.meaning 
4100: 6f 66 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 20  of single-quote 
4110: 77 69 74 68 69 6e 20 61 20 73 74 72 69 6e 67 20  within a string 
4120: 6c 69 74 65 72 61 6c 2e 0a 3c 2f 70 3e 0a 0a 3c  literal..</p>..<
4130: 70 3e 43 6f 6e 73 69 64 65 72 20 61 6e 20 65 78  p>Consider an ex
4140: 61 6d 70 6c 65 2e 20 20 53 75 70 70 6f 73 65 20  ample.  Suppose 
4150: 79 6f 75 20 61 72 65 20 74 72 79 69 6e 67 20 74  you are trying t
4160: 6f 20 69 6e 73 65 72 74 20 61 20 73 74 72 69 6e  o insert a strin
4170: 67 0a 76 61 6c 75 65 73 20 69 6e 74 6f 20 61 20  g.values into a 
4180: 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 77  database table w
4190: 68 65 72 65 20 74 68 65 20 73 74 72 69 6e 67 20  here the string 
41a0: 76 61 6c 75 65 20 77 61 73 20 6f 62 74 61 69 6e  value was obtain
41b0: 65 64 20 66 72 6f 6d 0a 75 73 65 72 20 69 6e 70  ed from.user inp
41c0: 75 74 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  ut.  Suppose the
41d0: 20 73 74 72 69 6e 67 20 74 6f 20 62 65 20 69 6e   string to be in
41e0: 73 65 72 74 65 64 20 69 73 20 73 74 6f 72 65 64  serted is stored
41f0: 20 69 6e 20 61 20 76 61 72 69 61 62 6c 65 0a 6e   in a variable.n
4200: 61 6d 65 64 20 7a 53 74 72 69 6e 67 2e 20 20 54  amed zString.  T
4210: 68 65 20 63 6f 64 65 20 74 6f 20 64 6f 20 74 68  he code to do th
4220: 65 20 69 6e 73 65 72 74 69 6f 6e 20 6d 69 67 68  e insertion migh
4230: 74 20 6c 6f 6f 6b 20 6c 69 6b 65 20 74 68 69 73  t look like this
4240: 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f  :</p>..<blockquo
4250: 74 65 3e 3c 70 72 65 3e 0a 73 71 6c 69 74 65 5f  te><pre>.sqlite_
4260: 65 78 65 63 5f 70 72 69 6e 74 66 28 64 62 2c 0a  exec_printf(db,.
4270: 20 20 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74    "INSERT INTO t
4280: 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 25 73  able1 VALUES('%s
4290: 27 29 22 2c 0a 20 20 30 2c 20 30 2c 20 30 2c 20  ')",.  0, 0, 0, 
42a0: 7a 53 74 72 69 6e 67 29 3b 0a 3c 2f 70 72 65 3e  zString);.</pre>
42b0: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c  </blockquote>..<
42c0: 70 3e 49 66 20 74 68 65 20 7a 53 74 72 69 6e 67  p>If the zString
42d0: 20 76 61 72 69 61 62 6c 65 20 68 6f 6c 64 73 20   variable holds 
42e0: 74 65 78 74 20 6c 69 6b 65 20 22 48 65 6c 6c 6f  text like "Hello
42f0: 22 2c 20 74 68 65 6e 20 74 68 69 73 20 73 74 61  ", then this sta
4300: 74 65 6d 65 6e 74 0a 77 69 6c 6c 20 77 6f 72 6b  tement.will work
4310: 20 6a 75 73 74 20 66 69 6e 65 2e 20 20 42 75 74   just fine.  But
4320: 20 73 75 70 70 6f 73 65 20 74 68 65 20 75 73 65   suppose the use
4330: 72 20 65 6e 74 65 72 73 20 61 20 73 74 72 69 6e  r enters a strin
4340: 67 20 6c 69 6b 65 20 0a 22 48 69 20 79 27 61 6c  g like ."Hi y'al
4350: 6c 21 22 2e 20 20 54 68 65 20 53 51 4c 20 73 74  l!".  The SQL st
4360: 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 74 65  atement generate
4370: 64 20 72 65 61 64 73 20 61 73 20 66 6f 6c 6c 6f  d reads as follo
4380: 77 73 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65  ws:..<blockquote
4390: 3e 3c 70 72 65 3e 0a 49 4e 53 45 52 54 20 49 4e  ><pre>.INSERT IN
43a0: 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
43b0: 28 27 48 69 20 79 27 61 6c 6c 27 29 0a 3c 2f 70  ('Hi y'all').</p
43c0: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
43d0: 0a 0a 3c 70 3e 54 68 69 73 20 69 73 20 6e 6f 74  ..<p>This is not
43e0: 20 76 61 6c 69 64 20 53 51 4c 20 62 65 63 61 75   valid SQL becau
43f0: 73 65 20 6f 66 20 74 68 65 20 61 70 6f 73 74 72  se of the apostr
4400: 6f 70 68 79 20 69 6e 20 74 68 65 20 77 6f 72 64  ophy in the word
4410: 20 22 79 27 61 6c 6c 22 2e 0a 42 75 74 20 69 66   "y'all"..But if
4420: 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 74 69   the %q formatti
4430: 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ng option is use
4440: 64 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 2c  d instead of %s,
4450: 20 6c 69 6b 65 20 74 68 69 73 3a 3c 2f 70 3e 0a   like this:</p>.
4460: 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72  .<blockquote><pr
4470: 65 3e 0a 73 71 6c 69 74 65 5f 65 78 65 63 5f 70  e>.sqlite_exec_p
4480: 72 69 6e 74 66 28 64 62 2c 0a 20 20 22 49 4e 53  rintf(db,.  "INS
4490: 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
44a0: 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 0a 20  VALUES('%q')",. 
44b0: 20 30 2c 20 30 2c 20 30 2c 20 7a 53 74 72 69 6e   0, 0, 0, zStrin
44c0: 67 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  g);.</pre></bloc
44d0: 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65 6e  kquote>..<p>Then
44e0: 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
44f0: 51 4c 20 77 69 6c 6c 20 6c 6f 6f 6b 20 6c 69 6b  QL will look lik
4500: 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 3a  e the following:
4510: 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74  </p>..<blockquot
4520: 65 3e 3c 70 72 65 3e 0a 49 4e 53 45 52 54 20 49  e><pre>.INSERT I
4530: 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
4540: 53 28 27 48 69 20 79 27 27 61 6c 6c 27 29 0a 3c  S('Hi y''all').<
4550: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
4560: 65 3e 0a 0a 3c 70 3e 48 65 72 65 20 74 68 65 20  e>..<p>Here the 
4570: 61 70 6f 73 74 72 6f 70 68 79 20 68 61 73 20 62  apostrophy has b
4580: 65 65 6e 20 65 73 63 61 70 65 64 20 61 6e 64 20  een escaped and 
4590: 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
45a0: 74 20 69 73 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  t is well-formed
45b0: 2e 0a 57 68 65 6e 20 67 65 6e 65 72 61 74 69 6e  ..When generatin
45c0: 67 20 53 51 4c 20 6f 6e 2d 74 68 65 2d 66 6c 79  g SQL on-the-fly
45d0: 20 66 72 6f 6d 20 64 61 74 61 20 74 68 61 74 20   from data that 
45e0: 6d 69 67 68 74 20 63 6f 6e 74 61 69 6e 20 61 0a  might contain a.
45f0: 73 69 6e 67 6c 65 2d 71 75 6f 74 65 20 63 68 61  single-quote cha
4600: 72 61 63 74 65 72 20 28 27 29 2c 20 69 74 20 69  racter ('), it i
4610: 73 20 61 6c 77 61 79 73 20 61 20 67 6f 6f 64 20  s always a good 
4620: 69 64 65 61 20 74 6f 20 75 73 65 20 74 68 65 0a  idea to use the.
4630: 53 51 4c 69 74 65 20 70 72 69 6e 74 66 20 72 6f  SQLite printf ro
4640: 75 74 69 6e 65 73 20 61 6e 64 20 74 68 65 20 25  utines and the %
4650: 71 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  q formatting opt
4660: 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 3c  ion instead of <
4670: 62 3e 73 70 72 69 6e 74 66 3c 2f 62 3e 2e 0a 3c  b>sprintf</b>..<
4680: 2f 70 3e 0a 0a 3c 68 32 3e 55 73 61 67 65 20 45  /p>..<h2>Usage E
4690: 78 61 6d 70 6c 65 73 3c 2f 68 32 3e 0a 0a 3c 70  xamples</h2>..<p
46a0: 3e 46 6f 72 20 65 78 61 6d 70 6c 65 73 20 6f 66  >For examples of
46b0: 20 68 6f 77 20 74 68 65 20 53 51 4c 69 74 65 20   how the SQLite 
46c0: 43 2f 43 2b 2b 20 69 6e 74 65 72 66 61 63 65 20  C/C++ interface 
46d0: 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 72 65 66  can be used,.ref
46e0: 65 72 20 74 6f 20 74 68 65 20 73 6f 75 72 63 65  er to the source
46f0: 20 63 6f 64 65 20 66 6f 72 20 74 68 65 20 3c 62   code for the <b
4700: 3e 73 71 6c 69 74 65 3c 2f 62 3e 20 70 72 6f 67  >sqlite</b> prog
4710: 72 61 6d 20 69 6e 20 74 68 65 0a 66 69 6c 65 20  ram in the.file 
4720: 3c 62 3e 73 72 63 2f 73 68 65 6c 6c 2e 63 3c 2f  <b>src/shell.c</
4730: 62 3e 20 6f 66 20 74 68 65 20 73 6f 75 72 63 65  b> of the source
4740: 20 74 72 65 65 2e 0a 41 64 64 69 74 69 6f 6e 61   tree..Additiona
4750: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  l information ab
4760: 6f 75 74 20 73 71 6c 69 74 65 20 69 73 20 61 76  out sqlite is av
4770: 61 69 6c 61 62 6c 65 20 61 74 0a 3c 61 20 68 72  ailable at.<a hr
4780: 65 66 3d 22 73 71 6c 69 74 65 2e 68 74 6d 6c 22  ef="sqlite.html"
4790: 3e 73 71 6c 69 74 65 2e 68 74 6d 6c 3c 2f 61 3e  >sqlite.html</a>
47a0: 2e 0a 53 65 65 20 61 6c 73 6f 20 74 68 65 20 73  ..See also the s
47b0: 6f 75 72 63 65 73 20 74 6f 20 74 68 65 20 54 63  ources to the Tc
47c0: 6c 20 69 6e 74 65 72 66 61 63 65 20 66 6f 72 20  l interface for 
47d0: 53 51 4c 69 74 65 20 69 6e 0a 74 68 65 20 73 6f  SQLite in.the so
47e0: 75 72 63 65 20 66 69 6c 65 20 3c 62 3e 73 72 63  urce file <b>src
47f0: 2f 74 63 6c 73 71 6c 69 74 65 2e 63 3c 2f 62 3e  /tclsqlite.c</b>
4800: 2e 3c 2f 70 3e 0a 7d 0a 0a 70 75 74 73 20 7b 0a  .</p>.}..puts {.
4810: 3c 70 3e 3c 68 72 20 2f 3e 3c 2f 70 3e 0a 3c 70  <p><hr /></p>.<p
4820: 3e 3c 61 20 68 72 65 66 3d 22 69 6e 64 65 78 2e  ><a href="index.
4830: 68 74 6d 6c 22 3e 3c 69 6d 67 20 73 72 63 3d 22  html"><img src="
4840: 2f 67 6f 62 61 63 6b 2e 6a 70 67 22 20 62 6f 72  /goback.jpg" bor
4850: 64 65 72 3d 30 20 2f 3e 0a 42 61 63 6b 20 74 6f  der=0 />.Back to
4860: 20 74 68 65 20 53 51 4c 69 74 65 20 48 6f 6d 65   the SQLite Home
4870: 20 50 61 67 65 3c 2f 61 3e 0a 3c 2f 70 3e 0a 0a   Page</a>.</p>..
4880: 3c 2f 62 6f 64 79 3e 3c 2f 68 74 6d 6c 3e 7d 0a  </body></html>}.