/ Hex Artifact Content
Login

Artifact 47d6b9b66510be10d3b482ce978a317a183477e5:


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: 39 20 32 30 30 30 2f 31 30 2f 30 38 20 32 32 3a  9 2000/10/08 22:
0070: 32 30 3a 35 38 20 64 72 68 20 45 78 70 20 24 7d  20:58 drh Exp $}
0080: 0a 0a 70 75 74 73 20 7b 3c 68 74 6d 6c 3e 0a 3c  ..puts {<html>.<
0090: 68 65 61 64 3e 0a 20 20 3c 74 69 74 6c 65 3e 54  head>.  <title>T
00a0: 68 65 20 43 20 6c 61 6e 67 75 61 67 65 20 69 6e  he C language in
00b0: 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 53  terface to the S
00c0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 3c 2f 74  QLite library</t
00d0: 69 74 6c 65 3e 0a 3c 2f 68 65 61 64 3e 0a 3c 62  itle>.</head>.<b
00e0: 6f 64 79 20 62 67 63 6f 6c 6f 72 3d 77 68 69 74  ody bgcolor=whit
00f0: 65 3e 0a 3c 68 31 20 61 6c 69 67 6e 3d 63 65 6e  e>.<h1 align=cen
0100: 74 65 72 3e 0a 54 68 65 20 43 20 6c 61 6e 67 75  ter>.The C langu
0110: 61 67 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  age interface to
0120: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
0130: 61 72 79 0a 3c 2f 68 31 3e 7d 0a 70 75 74 73 20  ary.</h1>}.puts 
0140: 22 3c 70 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72  "<p align=center
0150: 3e 0a 28 54 68 69 73 20 70 61 67 65 20 77 61 73  >.(This page was
0160: 20 6c 61 73 74 20 6d 6f 64 69 66 69 65 64 20 6f   last modified o
0170: 6e 20 5b 6c 72 61 6e 67 65 20 24 72 63 73 69 64  n [lrange $rcsid
0180: 20 33 20 34 5d 20 47 4d 54 29 0a 3c 2f 70 3e 22   3 4] GMT).</p>"
0190: 0a 0a 70 75 74 73 20 7b 0a 3c 70 3e 54 68 65 20  ..puts {.<p>The 
01a0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 69  SQLite library i
01b0: 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 62 65  s designed to be
01c0: 20 76 65 72 79 20 65 61 73 79 20 74 6f 20 75 73   very easy to us
01d0: 65 20 66 72 6f 6d 0a 61 20 43 20 6f 72 20 43 2b  e from.a C or C+
01e0: 2b 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 69 73  + program.  This
01f0: 20 64 6f 63 75 6d 65 6e 74 20 67 69 76 65 73 20   document gives 
0200: 61 6e 20 6f 76 65 72 76 69 65 77 20 6f 66 20 74  an overview of t
0210: 68 65 20 43 2f 43 2b 2b 0a 70 72 6f 67 72 61 6d  he C/C++.program
0220: 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 2e 3c  ming interface.<
0230: 2f 70 3e 0a 0a 3c 68 32 3e 54 68 65 20 41 50 49  /p>..<h2>The API
0240: 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 68 65 20 69 6e  </h2>..<p>The in
0250: 74 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 53  terface to the S
0260: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 63 6f  QLite library co
0270: 6e 73 69 73 74 73 20 6f 66 20 74 68 72 65 65 20  nsists of three 
0280: 63 6f 72 65 20 66 75 6e 63 74 69 6f 6e 73 2c 0a  core functions,.
0290: 6f 6e 65 20 6f 70 61 71 75 65 20 64 61 74 61 20  one opaque data 
02a0: 73 74 72 75 63 74 75 72 65 2c 20 61 6e 64 20 73  structure, and s
02b0: 6f 6d 65 20 63 6f 6e 73 74 61 6e 74 73 20 75 73  ome constants us
02c0: 65 64 20 61 73 20 72 65 74 75 72 6e 20 76 61 6c  ed as return val
02d0: 75 65 73 2e 0a 54 68 65 20 63 6f 72 65 20 69 6e  ues..The core in
02e0: 74 65 72 66 61 63 65 20 69 73 20 61 73 20 66 6f  terface is as fo
02f0: 6c 6c 6f 77 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f  llows:</p>..<blo
0300: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 74 79  ckquote><pre>.ty
0310: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
0320: 69 74 65 20 73 71 6c 69 74 65 3b 0a 0a 73 71 6c  ite sqlite;..sql
0330: 69 74 65 20 2a 73 71 6c 69 74 65 5f 6f 70 65 6e  ite *sqlite_open
0340: 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c  (const char *fil
0350: 65 6e 61 6d 65 2c 20 69 6e 74 20 6d 6f 64 65 2c  ename, int mode,
0360: 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 29 3b   char **errmsg);
0370: 0a 0a 76 6f 69 64 20 73 71 6c 69 74 65 5f 63 6c  ..void sqlite_cl
0380: 6f 73 65 28 73 71 6c 69 74 65 2a 29 3b 0a 0a 69  ose(sqlite*);..i
0390: 6e 74 20 73 71 6c 69 74 65 5f 65 78 65 63 28 0a  nt sqlite_exec(.
03a0: 20 20 73 71 6c 69 74 65 2a 2c 0a 20 20 63 68 61    sqlite*,.  cha
03b0: 72 20 2a 73 71 6c 2c 0a 20 20 69 6e 74 20 28 2a  r *sql,.  int (*
03c0: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
03d0: 2a 2a 2c 63 68 61 72 2a 2a 29 2c 0a 20 20 76 6f  **,char**),.  vo
03e0: 69 64 2a 2c 0a 20 20 63 68 61 72 20 2a 2a 65 72  id*,.  char **er
03f0: 72 6d 73 67 0a 29 3b 0a 0a 23 64 65 66 69 6e 65  rmsg.);..#define
0400: 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20   SQLITE_OK      
0410: 20 20 30 20 20 20 20 2f 2a 20 53 75 63 63 65 73    0    /* Succes
0420: 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 23  sful result */.#
0430: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
0440: 54 45 52 4e 41 4c 20 20 31 20 20 20 20 2f 2a 20  TERNAL  1    /* 
0450: 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  An internal logi
0460: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
0470: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
0480: 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 32 20  ITE_ERROR     2 
0490: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
04a0: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
04b0: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
04c0: 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20  QLITE_PERM      
04d0: 33 20 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70  3    /* Access p
04e0: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
04f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
0500: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 34 20 20  TE_ABORT     4  
0510: 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f    /* Callback ro
0520: 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20  utine requested 
0530: 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66  an abort */.#def
0540: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  ine SQLITE_BUSY 
0550: 20 20 20 20 20 35 20 20 20 20 2f 2a 20 4f 6e 65       5    /* One
0560: 20 6f 72 20 6d 6f 72 65 20 64 61 74 61 62 61 73   or more databas
0570: 65 20 66 69 6c 65 73 20 61 72 65 20 6c 6f 63 6b  e files are lock
0580: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
0590: 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 36  LITE_NOMEM     6
05a0: 20 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28      /* A malloc(
05b0: 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66  ) failed */.#def
05c0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
05d0: 4e 4c 59 20 20 37 20 20 20 20 2f 2a 20 41 74 74  NLY  7    /* Att
05e0: 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20  empt to write a 
05f0: 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73  readonly databas
0600: 65 20 2a 2f 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  e */.</pre></blo
0610: 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 4f 6e 6c  ckquote>..<p>Onl
0620: 79 20 74 68 65 20 74 68 72 65 65 20 63 6f 72 65  y the three core
0630: 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 77 6e 20   routines shown 
0640: 61 62 6f 76 65 20 61 72 65 20 72 65 71 75 69 72  above are requir
0650: 65 64 20 74 6f 20 75 73 65 0a 53 51 4c 69 74 65  ed to use.SQLite
0660: 2e 20 20 42 75 74 20 74 68 65 72 65 20 61 72 65  .  But there are
0670: 20 6d 61 6e 79 20 6f 74 68 65 72 20 66 75 6e 63   many other func
0680: 74 69 6f 6e 73 20 74 68 61 74 20 70 72 6f 76 69  tions that provi
0690: 64 65 20 0a 75 73 65 66 75 6c 20 69 6e 74 65 72  de .useful inter
06a0: 66 61 63 65 73 2e 20 20 54 68 65 73 65 20 65 78  faces.  These ex
06b0: 74 65 6e 64 65 64 20 72 6f 75 74 69 6e 65 73 20  tended routines 
06c0: 61 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  are as follows:.
06d0: 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74  </p>..<blockquot
06e0: 65 3e 3c 70 72 65 3e 0a 69 6e 74 20 73 71 6c 69  e><pre>.int sqli
06f0: 74 65 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  te_get_table(.  
0700: 73 71 6c 69 74 65 2a 2c 0a 20 20 63 68 61 72 20  sqlite*,.  char 
0710: 2a 73 71 6c 2c 0a 20 20 63 68 61 72 20 2a 2a 2a  *sql,.  char ***
0720: 72 65 73 75 6c 74 2c 0a 20 20 69 6e 74 20 2a 6e  result,.  int *n
0730: 72 6f 77 2c 0a 20 20 69 6e 74 20 2a 6e 63 6f 6c  row,.  int *ncol
0740: 75 6d 6e 2c 0a 20 20 63 68 61 72 20 2a 2a 65 72  umn,.  char **er
0750: 72 6d 73 67 0a 29 3b 0a 0a 76 6f 69 64 20 73 71  rmsg.);..void sq
0760: 6c 69 74 65 5f 66 72 65 65 5f 74 61 62 6c 65 28  lite_free_table(
0770: 63 68 61 72 2a 2a 29 3b 0a 0a 69 6e 74 20 73 71  char**);..int sq
0780: 6c 69 74 65 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  lite_complete(co
0790: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
07a0: 0a 76 6f 69 64 20 73 71 6c 69 74 65 5f 62 75 73  .void sqlite_bus
07b0: 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  y_handler(sqlite
07c0: 2a 2c 20 69 6e 74 20 28 2a 29 28 76 6f 69 64 2a  *, int (*)(void*
07d0: 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74  ,const char*,int
07e0: 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 76 6f 69 64  ), void*);..void
07f0: 20 73 71 6c 69 74 65 5f 62 75 73 79 5f 74 69 6d   sqlite_busy_tim
0800: 65 6f 75 74 28 73 71 6c 69 74 65 2a 2c 20 69 6e  eout(sqlite*, in
0810: 74 20 6d 73 29 3b 0a 0a 63 6f 6e 73 74 20 63 68  t ms);..const ch
0820: 61 72 20 73 71 6c 69 74 65 5f 76 65 72 73 69 6f  ar sqlite_versio
0830: 6e 5b 5d 3b 0a 0a 69 6e 74 20 73 71 6c 69 74 65  n[];..int sqlite
0840: 5f 65 78 65 63 5f 70 72 69 6e 74 66 28 0a 20 20  _exec_printf(.  
0850: 73 71 6c 69 74 65 2a 2c 0a 20 20 63 68 61 72 20  sqlite*,.  char 
0860: 2a 73 71 6c 2c 0a 20 20 69 6e 74 20 28 2a 29 28  *sql,.  int (*)(
0870: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a  void*,int,char**
0880: 2c 63 68 61 72 2a 2a 29 2c 0a 20 20 76 6f 69 64  ,char**),.  void
0890: 2a 2c 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  *,.  char **errm
08a0: 73 67 2c 0a 20 20 2e 2e 2e 0a 29 3b 0a 0a 69 6e  sg,.  ....);..in
08b0: 74 20 73 71 6c 69 74 65 5f 65 78 65 63 5f 76 70  t sqlite_exec_vp
08c0: 72 69 6e 74 66 28 0a 20 20 73 71 6c 69 74 65 2a  rintf(.  sqlite*
08d0: 2c 0a 20 20 63 68 61 72 20 2a 73 71 6c 2c 0a 20  ,.  char *sql,. 
08e0: 20 69 6e 74 20 28 2a 29 28 76 6f 69 64 2a 2c 69   int (*)(void*,i
08f0: 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a  nt,char**,char**
0900: 29 2c 0a 20 20 76 6f 69 64 2a 2c 0a 20 20 63 68  ),.  void*,.  ch
0910: 61 72 20 2a 2a 65 72 72 6d 73 67 2c 0a 20 20 76  ar **errmsg,.  v
0920: 61 5f 6c 69 73 74 0a 29 3b 0a 0a 69 6e 74 20 73  a_list.);..int s
0930: 71 6c 69 74 65 5f 67 65 74 5f 74 61 62 6c 65 5f  qlite_get_table_
0940: 70 72 69 6e 74 66 28 0a 20 20 73 71 6c 69 74 65  printf(.  sqlite
0950: 2a 2c 0a 20 20 63 68 61 72 20 2a 73 71 6c 2c 0a  *,.  char *sql,.
0960: 20 20 63 68 61 72 20 2a 2a 2a 72 65 73 75 6c 74    char ***result
0970: 2c 0a 20 20 69 6e 74 20 2a 6e 72 6f 77 2c 0a 20  ,.  int *nrow,. 
0980: 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 0a 20   int *ncolumn,. 
0990: 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 2c 0a   char **errmsg,.
09a0: 20 20 2e 2e 2e 0a 29 3b 0a 0a 69 6e 74 20 73 71    ....);..int sq
09b0: 6c 69 74 65 5f 67 65 74 5f 74 61 62 6c 65 5f 76  lite_get_table_v
09c0: 70 72 69 6e 74 66 28 0a 20 20 73 71 6c 69 74 65  printf(.  sqlite
09d0: 2a 2c 0a 20 20 63 68 61 72 20 2a 73 71 6c 2c 0a  *,.  char *sql,.
09e0: 20 20 63 68 61 72 20 2a 2a 2a 72 65 73 75 6c 74    char ***result
09f0: 2c 0a 20 20 69 6e 74 20 2a 6e 72 6f 77 2c 0a 20  ,.  int *nrow,. 
0a00: 20 69 6e 74 20 2a 6e 63 6f 6c 75 6d 6e 2c 0a 20   int *ncolumn,. 
0a10: 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 2c 0a   char **errmsg,.
0a20: 20 20 76 61 5f 6c 69 73 74 0a 29 3b 0a 0a 3c 2f    va_list.);..</
0a30: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
0a40: 3e 0a 0a 3c 70 3e 41 6c 6c 20 6f 66 20 74 68 65  >..<p>All of the
0a50: 20 61 62 6f 76 65 20 64 65 66 69 6e 69 74 69 6f   above definitio
0a60: 6e 73 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20  ns are included 
0a70: 69 6e 20 74 68 65 20 22 73 71 6c 69 74 65 2e 68  in the "sqlite.h
0a80: 22 0a 68 65 61 64 65 72 20 66 69 6c 65 20 74 68  ".header file th
0a90: 61 74 20 63 6f 6d 65 73 20 69 6e 20 74 68 65 20  at comes in the 
0aa0: 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 70 3e  source tree.</p>
0ab0: 0a 0a 3c 68 32 3e 4f 70 65 6e 69 6e 67 20 61 20  ..<h2>Opening a 
0ac0: 64 61 74 61 62 61 73 65 3c 2f 68 32 3e 0a 0a 3c  database</h2>..<
0ad0: 70 3e 55 73 65 20 74 68 65 20 3c 62 3e 73 71 6c  p>Use the <b>sql
0ae0: 69 74 65 5f 6f 70 65 6e 28 29 3c 2f 62 3e 20 66  ite_open()</b> f
0af0: 75 6e 63 74 69 6f 6e 20 74 6f 20 6f 70 65 6e 20  unction to open 
0b00: 61 6e 20 65 78 69 73 74 69 6e 67 20 53 51 4c 69  an existing SQLi
0b10: 74 65 0a 64 61 74 61 62 61 73 65 20 6f 72 20 74  te.database or t
0b20: 6f 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 53  o create a new S
0b30: 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 2e 20  QLite database. 
0b40: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
0b50: 65 6e 74 0a 69 73 20 74 68 65 20 64 61 74 61 62  ent.is the datab
0b60: 61 73 65 20 6e 61 6d 65 2e 20 20 54 68 65 20 73  ase name.  The s
0b70: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
0b80: 73 20 61 20 63 6f 6e 73 74 61 6e 74 20 30 36 36  s a constant 066
0b90: 36 20 74 6f 0a 6f 70 65 6e 20 74 68 65 20 64 61  6 to.open the da
0ba0: 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69  tabase for readi
0bb0: 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 61  ng and writing a
0bc0: 6e 64 20 30 34 34 34 20 74 6f 20 6f 70 65 6e 20  nd 0444 to open 
0bd0: 74 68 65 0a 64 61 74 61 62 61 73 65 20 72 65 61  the.database rea
0be0: 64 20 6f 6e 6c 79 2e 20 20 54 68 65 20 74 68 69  d only.  The thi
0bf0: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  rd argument is a
0c00: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
0c10: 72 69 6e 67 0a 70 6f 69 6e 74 65 72 2e 20 20 49  ring.pointer.  I
0c20: 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  f the third argu
0c30: 6d 65 6e 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ment is not NULL
0c40: 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6f 63   and an error oc
0c50: 63 75 72 73 0a 77 68 69 6c 65 20 74 72 79 69 6e  curs.while tryin
0c60: 67 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  g to open the da
0c70: 74 61 62 61 73 65 2c 20 74 68 65 6e 20 61 6e 20  tabase, then an 
0c80: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 77 69  error message wi
0c90: 6c 6c 20 62 65 0a 77 72 69 74 74 65 6e 20 74 6f  ll be.written to
0ca0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
0cb0: 20 66 72 6f 6d 20 6d 61 6c 6c 6f 63 28 29 20 61   from malloc() a
0cc0: 6e 64 20 2a 65 72 72 6d 73 67 20 77 69 6c 6c 20  nd *errmsg will 
0cd0: 62 65 20 6d 61 64 65 0a 74 6f 20 70 6f 69 6e 74  be made.to point
0ce0: 20 74 6f 20 74 68 69 73 20 65 72 72 6f 72 20 6d   to this error m
0cf0: 65 73 73 61 67 65 2e 20 20 54 68 65 20 63 61 6c  essage.  The cal
0d00: 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ling function is
0d10: 20 72 65 73 70 6f 6e 73 69 62 6c 65 0a 66 6f 72   responsible.for
0d20: 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d   freeing the mem
0d30: 6f 72 79 20 77 68 65 6e 20 69 74 20 68 61 73 20  ory when it has 
0d40: 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
0d50: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 41 6e 20 53 51 4c  .</p>..<p>An SQL
0d60: 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73 20  ite database is 
0d70: 6a 75 73 74 20 61 20 64 69 72 65 63 74 6f 72 79  just a directory
0d80: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 20 63 6f   containing a co
0d90: 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 47 44 42 4d  llection of.GDBM
0da0: 20 66 69 6c 65 73 2e 20 20 54 68 65 72 65 20 69   files.  There i
0db0: 73 20 6f 6e 65 20 47 44 42 4d 20 66 69 6c 65 20  s one GDBM file 
0dc0: 66 6f 72 20 65 61 63 68 20 74 61 62 6c 65 20 61  for each table a
0dd0: 6e 64 20 69 6e 64 65 78 20 69 6e 20 74 68 65 0a  nd index in the.
0de0: 64 61 74 61 62 61 73 65 2e 20 20 41 6c 6c 20 47  database.  All G
0df0: 44 42 4d 20 66 69 6c 65 73 20 65 6e 64 20 77 69  DBM files end wi
0e00: 74 68 20 74 68 65 20 22 2e 74 62 6c 22 20 73 75  th the ".tbl" su
0e10: 66 66 69 78 2e 20 20 45 76 65 72 79 20 53 51 4c  ffix.  Every SQL
0e20: 69 74 65 0a 64 61 74 61 62 61 73 65 20 61 6c 73  ite.database als
0e30: 6f 20 63 6f 6e 74 61 69 6e 73 20 61 20 73 70 65  o contains a spe
0e40: 63 69 61 6c 20 64 61 74 61 62 61 73 65 20 74 61  cial database ta
0e50: 62 6c 65 20 6e 61 6d 65 64 20 3c 62 3e 73 71 6c  ble named <b>sql
0e60: 69 74 65 5f 6d 61 73 74 65 72 3c 2f 62 3e 0a 73  ite_master</b>.s
0e70: 74 6f 72 65 64 20 69 6e 20 69 74 73 20 6f 77 6e  tored in its own
0e80: 20 47 44 42 4d 20 66 69 6c 65 2e 20 20 54 68 69   GDBM file.  Thi
0e90: 73 20 73 70 65 63 69 61 6c 20 74 61 62 6c 65 20  s special table 
0ea0: 72 65 63 6f 72 64 73 20 74 68 65 20 64 61 74 61  records the data
0eb0: 62 61 73 65 0a 73 63 68 65 6d 61 2e 3c 2f 70 3e  base.schema.</p>
0ec0: 0a 0a 3c 70 3e 54 6f 20 63 72 65 61 74 65 20 61  ..<p>To create a
0ed0: 20 6e 65 77 20 53 51 4c 69 74 65 20 64 61 74 61   new SQLite data
0ee0: 62 61 73 65 2c 20 61 6c 6c 20 79 6f 75 20 68 61  base, all you ha
0ef0: 76 65 20 74 6f 20 64 6f 20 69 73 20 63 61 6c 6c  ve to do is call
0f00: 0a 3c 62 3e 73 71 6c 69 74 65 5f 6f 70 65 6e 28  .<b>sqlite_open(
0f10: 29 3c 2f 62 3e 20 77 69 74 68 20 74 68 65 20 66  )</b> with the f
0f20: 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 73  irst parameter s
0f30: 65 74 20 74 6f 20 74 68 65 20 6e 61 6d 65 20 6f  et to the name o
0f40: 66 0a 61 6e 20 65 6d 70 74 79 20 64 69 72 65 63  f.an empty direc
0f50: 74 6f 72 79 20 61 6e 64 20 74 68 65 20 73 65 63  tory and the sec
0f60: 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 73 65  ond parameter se
0f70: 74 20 74 6f 20 30 36 36 36 2e 3c 2f 70 3e 0a 0a  t to 0666.</p>..
0f80: 3c 70 3e 54 68 65 20 72 65 74 75 72 6e 20 76 61  <p>The return va
0f90: 6c 75 65 20 6f 66 20 74 68 65 20 3c 62 3e 73 71  lue of the <b>sq
0fa0: 6c 69 74 65 5f 6f 70 65 6e 28 29 3c 2f 62 3e 20  lite_open()</b> 
0fb0: 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 0a 70 6f  function is a.po
0fc0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 6f 70 61 71  inter to an opaq
0fd0: 75 65 20 3c 62 3e 73 71 6c 69 74 65 3c 2f 62 3e  ue <b>sqlite</b>
0fe0: 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 69   structure.  Thi
0ff0: 73 20 70 6f 69 6e 74 65 72 20 77 69 6c 6c 0a 62  s pointer will.b
1000: 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
1010: 6d 65 6e 74 20 74 6f 20 61 6c 6c 20 73 75 62 73  ment to all subs
1020: 65 71 75 65 6e 74 20 53 51 4c 69 74 65 20 66 75  equent SQLite fu
1030: 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 74 68 61  nction calls tha
1040: 74 0a 64 65 61 6c 20 77 69 74 68 20 74 68 65 20  t.deal with the 
1050: 73 61 6d 65 20 64 61 74 61 62 61 73 65 2e 20 20  same database.  
1060: 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
1070: 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69   if the open fai
1080: 6c 73 0a 66 6f 72 20 61 6e 79 20 72 65 61 73 6f  ls.for any reaso
1090: 6e 2e 3c 2f 70 3e 0a 0a 3c 68 32 3e 43 6c 6f 73  n.</p>..<h2>Clos
10a0: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
10b0: 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 6f 20 63 6c 6f  </h2>..<p>To clo
10c0: 73 65 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  se an SQLite dat
10d0: 61 62 61 73 65 2c 20 63 61 6c 6c 20 74 68 65 20  abase, call the 
10e0: 3c 62 3e 73 71 6c 69 74 65 5f 63 6c 6f 73 65 28  <b>sqlite_close(
10f0: 29 3c 2f 62 3e 0a 66 75 6e 63 74 69 6f 6e 20 70  )</b>.function p
1100: 61 73 73 69 6e 67 20 69 74 20 74 68 65 20 73 71  assing it the sq
1110: 6c 69 74 65 20 73 74 72 75 63 74 75 72 65 20 70  lite structure p
1120: 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20  ointer that was 
1130: 6f 62 74 61 69 6e 65 64 0a 66 72 6f 6d 20 61 20  obtained.from a 
1140: 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 3c 62  prior call to <b
1150: 3e 73 71 6c 69 74 65 5f 6f 70 65 6e 3c 2f 62 3e  >sqlite_open</b>
1160: 2e 0a 0a 3c 68 32 3e 45 78 65 63 75 74 69 6e 67  ...<h2>Executing
1170: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 3c   SQL statements<
1180: 2f 68 32 3e 0a 0a 3c 70 3e 54 68 65 20 3c 62 3e  /h2>..<p>The <b>
1190: 73 71 6c 69 74 65 5f 65 78 65 63 28 29 3c 2f 62  sqlite_exec()</b
11a0: 3e 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  > function is us
11b0: 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51  ed to process SQ
11c0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 61 6e 64  L statements.and
11d0: 20 71 75 65 72 69 65 73 2e 20 20 54 68 69 73 20   queries.  This 
11e0: 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
11f0: 73 20 35 20 70 61 72 61 6d 65 74 65 72 73 20 61  s 5 parameters a
1200: 73 20 66 6f 6c 6c 6f 77 73 3a 3c 2f 70 3e 0a 0a  s follows:</p>..
1210: 3c 6f 6c 3e 0a 3c 6c 69 3e 3c 70 3e 41 20 70 6f  <ol>.<li><p>A po
1220: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  inter to the sql
1230: 69 74 65 20 73 74 72 75 63 74 75 72 65 20 6f 62  ite structure ob
1240: 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
1250: 69 6f 72 20 63 61 6c 6c 0a 20 20 20 20 20 20 20  ior call.       
1260: 74 6f 20 3c 62 3e 73 71 6c 69 74 65 5f 6f 70 65  to <b>sqlite_ope
1270: 6e 28 29 3c 2f 62 3e 2e 3c 2f 70 3e 3c 2f 6c 69  n()</b>.</p></li
1280: 3e 0a 3c 6c 69 3e 3c 70 3e 41 20 6e 75 6c 6c 2d  >.<li><p>A null-
1290: 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
12a0: 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  g containing the
12b0: 20 74 65 78 74 20 6f 66 20 6f 6e 65 20 6f 72 20   text of one or 
12c0: 6d 6f 72 65 0a 20 20 20 20 20 20 20 53 51 4c 20  more.       SQL 
12d0: 73 74 61 74 65 6d 65 6e 74 73 20 61 6e 64 2f 6f  statements and/o
12e0: 72 20 71 75 65 72 69 65 73 20 74 6f 20 62 65 20  r queries to be 
12f0: 70 72 6f 63 65 73 73 65 64 2e 3c 2f 70 3e 3c 2f  processed.</p></
1300: 6c 69 3e 0a 3c 6c 69 3e 3c 70 3e 41 20 70 6f 69  li>.<li><p>A poi
1310: 6e 74 65 72 20 74 6f 20 61 20 63 61 6c 6c 62 61  nter to a callba
1320: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 68 69 63  ck function whic
1330: 68 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63  h is invoked onc
1340: 65 20 66 6f 72 20 65 61 63 68 0a 20 20 20 20 20  e for each.     
1350: 20 20 72 6f 77 20 69 6e 20 74 68 65 20 72 65 73    row in the res
1360: 75 6c 74 20 6f 66 20 61 20 71 75 65 72 79 2e 20  ult of a query. 
1370: 20 54 68 69 73 20 61 72 67 75 6d 65 6e 74 20 6d   This argument m
1380: 61 79 20 62 65 20 4e 55 4c 4c 2c 20 69 6e 20 77  ay be NULL, in w
1390: 68 69 63 68 0a 20 20 20 20 20 20 20 63 61 73 65  hich.       case
13a0: 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 73 20 77 69   no callbacks wi
13b0: 6c 6c 20 65 76 65 72 20 62 65 20 69 6e 76 6f 6b  ll ever be invok
13c0: 65 64 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a 3c 6c 69  ed.</p></li>.<li
13d0: 3e 3c 70 3e 41 20 70 6f 69 6e 74 65 72 20 74 68  ><p>A pointer th
13e0: 61 74 20 69 73 20 66 6f 72 77 61 72 64 65 64 20  at is forwarded 
13f0: 74 6f 20 62 65 63 6f 6d 65 20 74 68 65 20 66 69  to become the fi
1400: 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 20 20 20  rst argument.   
1410: 20 20 20 20 74 6f 20 74 68 65 20 63 61 6c 6c 62      to the callb
1420: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 70  ack function.</p
1430: 3e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 3c 70 3e 41 20  ></li>.<li><p>A 
1440: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 72  pointer to an er
1450: 72 6f 72 20 73 74 72 69 6e 67 2e 20 20 45 72 72  ror string.  Err
1460: 6f 72 20 6d 65 73 73 61 67 65 73 20 61 72 65 20  or messages are 
1470: 77 72 69 74 74 65 6e 20 74 6f 20 73 70 61 63 65  written to space
1480: 0a 20 20 20 20 20 20 20 6f 62 74 61 69 6e 65 64  .       obtained
1490: 20 66 72 6f 6d 20 6d 61 6c 6c 6f 63 28 29 20 61   from malloc() a
14a0: 6e 64 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  nd the error str
14b0: 69 6e 67 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ing is made to p
14c0: 6f 69 6e 74 20 74 6f 0a 20 20 20 20 20 20 20 74  oint to.       t
14d0: 68 65 20 6d 61 6c 6c 6f 63 65 64 20 73 70 61 63  he malloced spac
14e0: 65 2e 20 20 54 68 65 20 63 61 6c 6c 69 6e 67 20  e.  The calling 
14f0: 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 73 70  function is resp
1500: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65  onsible for free
1510: 69 6e 67 0a 20 20 20 20 20 20 20 74 68 69 73 20  ing.       this 
1520: 73 70 61 63 65 20 77 68 65 6e 20 69 74 20 68 61  space when it ha
1530: 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1540: 69 74 2e 0a 20 20 20 20 20 20 20 54 68 69 73 20  it..       This 
1550: 61 72 67 75 6d 65 6e 74 20 6d 61 79 20 62 65 20  argument may be 
1560: 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63  NULL, in which c
1570: 61 73 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  ase error messag
1580: 65 73 20 61 72 65 20 6e 6f 74 0a 20 20 20 20 20  es are not.     
1590: 20 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20    reported back 
15a0: 74 6f 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  to the calling f
15b0: 75 6e 63 74 69 6f 6e 2e 3c 2f 70 3e 3c 2f 6c 69  unction.</p></li
15c0: 3e 0a 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 0a 54 68 65  >.</ol>..<p>.The
15d0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
15e0: 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 72 65  on is used to re
15f0: 63 65 69 76 65 20 74 68 65 20 72 65 73 75 6c 74  ceive the result
1600: 73 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 41  s of a query.  A
1610: 0a 70 72 6f 74 6f 74 79 70 65 20 66 6f 72 20 74  .prototype for t
1620: 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
1630: 74 69 6f 6e 20 69 73 20 61 73 20 66 6f 6c 6c 6f  tion is as follo
1640: 77 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71  ws:</p>..<blockq
1650: 75 6f 74 65 3e 3c 70 72 65 3e 0a 69 6e 74 20 43  uote><pre>.int C
1660: 61 6c 6c 62 61 63 6b 28 76 6f 69 64 20 2a 70 41  allback(void *pA
1670: 72 67 2c 20 69 6e 74 20 61 72 67 63 2c 20 63 68  rg, int argc, ch
1680: 61 72 20 2a 2a 61 72 67 76 2c 20 63 68 61 72 20  ar **argv, char 
1690: 2a 2a 63 6f 6c 75 6d 6e 4e 61 6d 65 73 29 7b 0a  **columnNames){.
16a0: 20 20 72 65 74 75 72 6e 20 30 3b 0a 7d 0a 3c 2f    return 0;.}.</
16b0: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
16c0: 3e 0a 0a 3c 70 3e 54 68 65 20 66 69 72 73 74 20  >..<p>The first 
16d0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
16e0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 6a 75 73 74  callback is just
16f0: 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66   a copy of the f
1700: 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 74  ourth argument.t
1710: 6f 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63  o <b>sqlite_exec
1720: 28 29 3c 2f 62 3e 20 20 54 68 69 73 20 70 61 72  ()</b>  This par
1730: 61 6d 65 74 65 72 20 63 61 6e 20 62 65 20 75 73  ameter can be us
1740: 65 64 20 74 6f 20 70 61 73 73 20 61 72 62 69 74  ed to pass arbit
1750: 72 61 72 79 0a 69 6e 66 6f 72 6d 61 74 69 6f 6e  rary.information
1760: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
1770: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1780: 6e 20 66 72 6f 6d 20 63 6c 69 65 6e 74 20 63 6f  n from client co
1790: 64 65 2e 0a 54 68 65 20 73 65 63 6f 6e 64 20 61  de..The second a
17a0: 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
17b0: 75 6d 62 65 72 20 63 6f 6c 75 6d 6e 73 20 69 6e  umber columns in
17c0: 20 74 68 65 20 71 75 65 72 79 20 72 65 73 75 6c   the query resul
17d0: 74 2e 0a 54 68 65 20 74 68 69 72 64 20 61 72 67  t..The third arg
17e0: 75 6d 65 6e 74 20 69 73 20 61 6e 20 61 72 72 61  ument is an arra
17f0: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
1800: 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 65   strings where e
1810: 61 63 68 20 73 74 72 69 6e 67 0a 69 73 20 61 20  ach string.is a 
1820: 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
1830: 20 74 68 65 20 72 65 73 75 6c 74 20 66 6f 72 20   the result for 
1840: 74 68 61 74 20 72 65 63 6f 72 64 2e 20 20 4e 6f  that record.  No
1850: 74 65 20 74 68 61 74 20 74 68 65 0a 63 61 6c 6c  te that the.call
1860: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
1870: 70 6f 72 74 73 20 61 20 4e 55 4c 4c 20 76 61 6c  ports a NULL val
1880: 75 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61  ue in the databa
1890: 73 65 20 61 73 20 61 20 4e 55 4c 4c 20 70 6f 69  se as a NULL poi
18a0: 6e 74 65 72 2c 0a 77 68 69 63 68 20 69 73 20 76  nter,.which is v
18b0: 65 72 79 20 64 69 66 66 65 72 65 6e 74 20 66 72  ery different fr
18c0: 6f 6d 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  om an empty stri
18d0: 6e 67 2e 20 20 49 66 20 74 68 65 20 69 2d 74 68  ng.  If the i-th
18e0: 20 70 61 72 61 6d 65 74 65 72 0a 69 73 20 61 6e   parameter.is an
18f0: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 77   empty string, w
1900: 65 20 77 69 6c 6c 20 67 65 74 3a 3c 2f 70 3e 0a  e will get:</p>.
1910: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1920: 3e 0a 61 72 67 76 5b 69 5d 5b 30 5d 20 3d 3d 20  >.argv[i][0] == 
1930: 30 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  0.</pre></blockq
1940: 75 6f 74 65 3e 0a 3c 70 3e 42 75 74 20 69 66 20  uote>.<p>But if 
1950: 74 68 65 20 69 2d 74 68 20 70 61 72 61 6d 65 74  the i-th paramet
1960: 65 72 20 69 73 20 4e 55 4c 4c 20 77 65 20 77 69  er is NULL we wi
1970: 6c 6c 20 67 65 74 3a 3c 2f 70 3e 0a 3c 62 6c 6f  ll get:</p>.<blo
1980: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 61 72  ckquote><pre>.ar
1990: 67 76 5b 69 5d 20 3d 3d 20 30 0a 3c 2f 70 72 65  gv[i] == 0.</pre
19a0: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 3c  ></blockquote>.<
19b0: 70 3e 54 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  p>The names of t
19c0: 68 65 20 63 6f 6c 75 6d 6e 73 20 61 72 65 20 63  he columns are c
19d0: 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65 20  ontained in the 
19e0: 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2e  fourth argument.
19f0: 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 63 61 6c  </p>..<p>The cal
1a00: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73  lback function s
1a10: 68 6f 75 6c 64 20 6e 6f 72 6d 61 6c 6c 79 20 72  hould normally r
1a20: 65 74 75 72 6e 20 30 2e 20 20 49 66 20 74 68 65  eturn 0.  If the
1a30: 20 63 61 6c 6c 62 61 63 6b 0a 66 75 6e 63 74 69   callback.functi
1a40: 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  on returns non-z
1a50: 65 72 6f 2c 20 74 68 65 20 71 75 65 72 79 20 69  ero, the query i
1a60: 73 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 62  s immediately ab
1a70: 6f 72 74 65 64 20 61 6e 64 20 0a 3c 62 3e 73 71  orted and .<b>sq
1a80: 6c 69 74 65 5f 65 78 65 63 28 29 3c 2f 62 3e 20  lite_exec()</b> 
1a90: 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49  will return SQLI
1aa0: 54 45 5f 41 42 4f 52 54 2e 3c 2f 70 3e 0a 0a 3c  TE_ABORT.</p>..<
1ab0: 70 3e 54 68 65 20 3c 62 3e 73 71 6c 69 74 65 5f  p>The <b>sqlite_
1ac0: 65 78 65 63 28 29 3c 2f 62 3e 20 66 75 6e 63 74  exec()</b> funct
1ad0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ion returns an i
1ae0: 6e 74 65 67 65 72 20 74 6f 20 69 6e 64 69 63 61  nteger to indica
1af0: 74 65 0a 73 75 63 63 65 73 73 20 6f 72 20 66 61  te.success or fa
1b00: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 6f 70 65  ilure of the ope
1b10: 72 61 74 69 6f 6e 2e 20 20 54 68 65 20 66 6f 6c  ration.  The fol
1b20: 6c 6f 77 69 6e 67 20 61 72 65 20 70 6f 73 73 69  lowing are possi
1b30: 62 6c 65 0a 72 65 74 75 72 6e 20 76 61 6c 75 65  ble.return value
1b40: 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75  s:</p>..<blockqu
1b50: 6f 74 65 3e 0a 3c 64 6c 3e 0a 3c 64 74 3e 53 51  ote>.<dl>.<dt>SQ
1b60: 4c 49 54 45 5f 4f 4b 3c 2f 64 74 3e 0a 3c 64 64  LITE_OK</dt>.<dd
1b70: 3e 3c 70 3e 54 68 69 73 20 76 61 6c 75 65 20 69  ><p>This value i
1b80: 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 65 76  s returned if ev
1b90: 65 72 79 74 68 69 6e 67 20 77 6f 72 6b 65 64 20  erything worked 
1ba0: 61 6e 64 20 74 68 65 72 65 20 77 65 72 65 20 6e  and there were n
1bb0: 6f 20 65 72 72 6f 72 73 2e 0a 3c 2f 70 3e 3c 2f  o errors..</p></
1bc0: 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f 49  dd>.<dt>SQLITE_I
1bd0: 4e 54 45 52 4e 41 4c 3c 2f 64 74 3e 0a 3c 64 64  NTERNAL</dt>.<dd
1be0: 3e 3c 70 3e 54 68 69 73 20 76 61 6c 75 65 20 69  ><p>This value i
1bf0: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 61 6e  ndicates that an
1c00: 20 69 6e 74 65 72 6e 61 6c 20 63 6f 6e 73 69 73   internal consis
1c10: 74 65 6e 63 79 20 63 68 65 63 6b 20 77 69 74 68  tency check with
1c20: 69 6e 0a 74 68 65 20 53 51 4c 69 74 65 20 6c 69  in.the SQLite li
1c30: 62 72 61 72 79 20 66 61 69 6c 65 64 2e 20 20 54  brary failed.  T
1c40: 68 69 73 20 63 61 6e 20 6f 6e 6c 79 20 68 61 70  his can only hap
1c50: 70 65 6e 20 69 66 20 74 68 65 72 65 20 69 73 20  pen if there is 
1c60: 61 20 62 75 67 20 69 6e 0a 74 68 65 20 53 51 4c  a bug in.the SQL
1c70: 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 49 66  ite library.  If
1c80: 20 79 6f 75 20 65 76 65 72 20 67 65 74 20 61 6e   you ever get an
1c90: 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c   SQLITE_INTERNAL
1ca0: 20 72 65 70 6c 79 20 66 72 6f 6d 0a 61 6e 20 3c   reply from.an <
1cb0: 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 28 29 3c  b>sqlite_exec()<
1cc0: 2f 62 3e 20 63 61 6c 6c 2c 20 70 6c 65 61 73 65  /b> call, please
1cd0: 20 72 65 70 6f 72 74 20 74 68 65 20 70 72 6f 62   report the prob
1ce0: 6c 65 6d 20 6f 6e 20 74 68 65 20 53 51 4c 69 74  lem on the SQLit
1cf0: 65 0a 6d 61 69 6c 69 6e 67 20 6c 69 73 74 2e 0a  e.mailing list..
1d00: 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51  </p></dd>.<dt>SQ
1d10: 4c 49 54 45 5f 45 52 52 4f 52 3c 2f 64 74 3e 0a  LITE_ERROR</dt>.
1d20: 3c 64 64 3e 3c 70 3e 54 68 69 73 20 72 65 74 75  <dd><p>This retu
1d30: 72 6e 20 76 61 6c 75 65 20 69 6e 64 69 63 61 74  rn value indicat
1d40: 65 73 20 74 68 61 74 20 74 68 65 72 65 20 77 61  es that there wa
1d50: 73 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 74 68  s an error in th
1d60: 65 20 53 51 4c 0a 74 68 61 74 20 77 61 73 20 70  e SQL.that was p
1d70: 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 3c  assed into the <
1d80: 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 28 29 3c  b>sqlite_exec()<
1d90: 2f 62 3e 2e 0a 3c 2f 70 3e 3c 2f 64 64 3e 0a 3c  /b>..</p></dd>.<
1da0: 64 74 3e 53 51 4c 49 54 45 5f 50 45 52 4d 3c 2f  dt>SQLITE_PERM</
1db0: 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68 69 73 20  dt>.<dd><p>This 
1dc0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 73 61 79  return value say
1dd0: 73 20 74 68 61 74 20 74 68 65 20 61 63 63 65 73  s that the acces
1de0: 73 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 6f 6e  s permissions on
1df0: 20 6f 6e 65 20 6f 66 20 74 68 65 0a 47 44 42 4d   one of the.GDBM
1e00: 20 66 69 6c 65 73 20 69 73 20 73 75 63 68 20 74   files is such t
1e10: 68 61 74 20 74 68 65 20 66 69 6c 65 20 63 61 6e  hat the file can
1e20: 6e 6f 74 20 62 65 20 6f 70 65 6e 65 64 2e 0a 3c  not be opened..<
1e30: 2f 70 3e 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c  /p></dd>.<dt>SQL
1e40: 49 54 45 5f 41 42 4f 52 54 3c 2f 64 74 3e 0a 3c  ITE_ABORT</dt>.<
1e50: 64 64 3e 3c 70 3e 54 68 69 73 20 76 61 6c 75 65  dd><p>This value
1e60: 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
1e70: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
1e80: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f  ction returns no
1e90: 6e 2d 7a 65 72 6f 2e 0a 3c 2f 70 3e 3c 2f 64 64  n-zero..</p></dd
1ea0: 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f 42 55 53  >.<dt>SQLITE_BUS
1eb0: 59 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70 3e 54 68  Y</dt>.<dd><p>Th
1ec0: 69 73 20 72 65 74 75 72 6e 20 63 6f 64 65 20 69  is return code i
1ed0: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 6f 6e  ndicates that on
1ee0: 65 20 6f 66 20 74 68 65 20 75 6e 64 65 72 6c 79  e of the underly
1ef0: 69 6e 67 20 47 44 42 4d 20 66 69 6c 65 73 0a 69  ing GDBM files.i
1f00: 73 20 6c 6f 63 6b 65 64 20 62 65 63 61 75 73 65  s locked because
1f10: 20 69 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79   it is currently
1f20: 20 62 65 69 6e 67 20 61 63 63 65 73 73 65 64 20   being accessed 
1f30: 62 79 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  by another threa
1f40: 64 20 6f 72 0a 70 72 6f 63 65 73 73 2e 20 20 47  d or.process.  G
1f50: 44 42 4d 20 61 6c 6c 6f 77 73 20 6d 75 74 69 70  DBM allows mutip
1f60: 6c 65 20 72 65 61 64 65 72 73 20 6f 66 20 74 68  le readers of th
1f70: 65 20 73 61 6d 65 20 66 69 6c 65 2c 20 62 75 74  e same file, but
1f80: 20 6f 6e 6c 79 20 6f 6e 65 0a 77 72 69 74 65 72   only one.writer
1f90: 2e 20 20 53 6f 20 6d 75 6c 74 69 70 6c 65 20 70  .  So multiple p
1fa0: 72 6f 63 65 73 73 65 73 20 63 61 6e 20 71 75 65  rocesses can que
1fb0: 72 79 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  ry an SQLite dat
1fc0: 61 62 61 73 65 20 61 74 20 6f 6e 63 65 2e 0a 42  abase at once..B
1fd0: 75 74 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  ut only a single
1fe0: 20 70 72 6f 63 65 73 73 20 63 61 6e 20 77 72 69   process can wri
1ff0: 74 65 20 74 6f 20 61 6e 20 53 51 4c 69 74 65 20  te to an SQLite 
2000: 64 61 74 61 62 61 73 65 20 61 74 20 6f 6e 65 20  database at one 
2010: 74 69 6d 65 2e 0a 49 66 20 61 6e 20 61 74 74 65  time..If an atte
2020: 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 77  mpt is made to w
2030: 72 69 74 65 20 74 6f 20 61 6e 20 53 51 4c 69 74  rite to an SQLit
2040: 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74 20  e database that 
2050: 61 6e 6f 74 68 65 72 0a 70 72 6f 63 65 73 73 20  another.process 
2060: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 65 61  is currently rea
2070: 64 69 6e 67 2c 20 74 68 65 20 77 72 69 74 65 20  ding, the write 
2080: 69 73 20 6e 6f 74 20 70 65 72 66 6f 72 6d 65 64  is not performed
2090: 20 61 6e 64 20 0a 3c 62 3e 73 71 6c 69 74 65 5f   and .<b>sqlite_
20a0: 65 78 65 63 28 29 3c 2f 62 3e 20 72 65 74 75 72  exec()</b> retur
20b0: 6e 73 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20  ns SQLITE_BUSY. 
20c0: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 61 6e 20 61   Similarly, an a
20d0: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 0a 61  ttempt to read.a
20e0: 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
20f0: 65 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  e that is curren
2100: 74 6c 79 20 62 65 69 6e 67 20 77 72 69 74 74 65  tly being writte
2110: 6e 20 62 79 20 61 6e 6f 74 68 65 72 20 70 72 6f  n by another pro
2120: 63 65 73 73 0a 77 69 6c 6c 20 72 65 74 75 72 6e  cess.will return
2130: 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20 20 49   SQLITE_BUSY.  I
2140: 6e 20 62 6f 74 68 20 63 61 73 65 73 2c 20 74 68  n both cases, th
2150: 65 20 77 72 69 74 65 20 6f 72 20 71 75 65 72 79  e write or query
2160: 20 61 74 74 65 6d 70 74 0a 63 61 6e 20 62 65 20   attempt.can be 
2170: 72 65 74 72 69 65 64 20 61 66 74 65 72 20 74 68  retried after th
2180: 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 20  e other process 
2190: 66 69 6e 69 73 68 65 73 2e 3c 2f 70 3e 0a 3c 70  finishes.</p>.<p
21a0: 3e 4e 6f 74 65 20 74 68 61 74 20 6c 6f 63 6b 69  >Note that locki
21b0: 6e 67 20 69 73 20 64 6f 6e 65 20 61 74 20 74 68  ng is done at th
21c0: 65 20 66 69 6c 65 20 6c 65 76 65 6c 2e 20 20 4f  e file level.  O
21d0: 6e 65 20 70 72 6f 63 65 73 73 20 63 61 6e 0a 77  ne process can.w
21e0: 72 69 74 65 20 74 6f 20 74 61 62 6c 65 20 41 42  rite to table AB
21f0: 43 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 29 20  C (for example) 
2200: 77 68 69 6c 65 20 61 6e 6f 74 68 65 72 20 70 72  while another pr
2210: 6f 63 65 73 73 20 73 69 6d 75 6c 74 61 6e 65 6f  ocess simultaneo
2220: 75 73 6c 79 0a 72 65 61 64 73 20 66 72 6f 6d 20  usly.reads from 
2230: 61 20 64 69 66 66 65 72 65 6e 74 20 74 61 62 6c  a different tabl
2240: 65 20 58 59 5a 2e 20 20 42 75 74 20 79 6f 75 20  e XYZ.  But you 
2250: 63 61 6e 6e 6f 74 20 68 61 76 65 20 74 77 6f 20  cannot have two 
2260: 70 72 6f 63 65 73 73 65 73 20 72 65 61 64 69 6e  processes readin
2270: 67 0a 61 6e 64 20 77 72 69 74 69 6e 67 20 74 61  g.and writing ta
2280: 62 6c 65 20 41 42 43 20 61 74 20 74 68 65 20 73  ble ABC at the s
2290: 61 6d 65 20 74 69 6d 65 2e 0a 3c 2f 70 3e 3c 2f  ame time..</p></
22a0: 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45 5f 4e  dd>.<dt>SQLITE_N
22b0: 4f 4d 45 4d 3c 2f 64 74 3e 0a 3c 64 64 3e 3c 70  OMEM</dt>.<dd><p
22c0: 3e 54 68 69 73 20 76 61 6c 75 65 20 69 73 20 72  >This value is r
22d0: 65 74 75 72 6e 65 64 20 69 66 20 61 20 63 61 6c  eturned if a cal
22e0: 6c 20 74 6f 20 3c 62 3e 6d 61 6c 6c 6f 63 28 29  l to <b>malloc()
22f0: 3c 2f 62 3e 20 66 61 69 6c 73 2e 0a 3c 2f 70 3e  </b> fails..</p>
2300: 3c 2f 64 64 3e 0a 3c 64 74 3e 53 51 4c 49 54 45  </dd>.<dt>SQLITE
2310: 5f 52 45 41 44 4f 4e 4c 59 3c 2f 64 74 3e 0a 3c  _READONLY</dt>.<
2320: 64 64 3e 3c 70 3e 54 68 69 73 20 72 65 74 75 72  dd><p>This retur
2330: 6e 20 63 6f 64 65 20 69 6e 64 69 63 61 74 65 73  n code indicates
2340: 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
2350: 20 77 61 73 20 6d 61 64 65 20 74 6f 20 77 72 69   was made to wri
2360: 74 65 20 74 6f 0a 61 20 64 61 74 61 62 61 73 65  te to.a database
2370: 20 66 69 6c 65 20 74 68 61 74 20 77 61 73 20 6f   file that was o
2380: 72 69 67 69 6e 61 6c 6c 79 20 6f 70 65 6e 65 64  riginally opened
2390: 20 66 6f 72 20 72 65 61 64 69 6e 67 20 6f 6e 6c   for reading onl
23a0: 79 2e 20 20 54 68 69 73 20 63 61 6e 0a 68 61 70  y.  This can.hap
23b0: 70 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 62  pen if the callb
23c0: 61 63 6b 20 66 72 6f 6d 20 61 20 71 75 65 72 79  ack from a query
23d0: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 75 70 64   attempts to upd
23e0: 61 74 65 20 74 68 65 20 74 61 62 6c 65 0a 62 65  ate the table.be
23f0: 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 3c 2f 70  ing queried..</p
2400: 3e 3c 2f 64 64 3e 0a 3c 2f 64 6c 3e 0a 3c 2f 62  ></dd>.</dl>.</b
2410: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 68 32 3e  lockquote>..<h2>
2420: 51 75 65 72 79 69 6e 67 20 77 69 74 68 6f 75 74  Querying without
2430: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 62 61 63   using a callbac
2440: 6b 20 66 75 6e 63 74 69 6f 6e 3c 2f 68 32 3e 0a  k function</h2>.
2450: 0a 3c 70 3e 54 68 65 20 3c 62 3e 73 71 6c 69 74  .<p>The <b>sqlit
2460: 65 5f 67 65 74 5f 74 61 62 6c 65 28 29 3c 2f 62  e_get_table()</b
2470: 3e 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20  > function is a 
2480: 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 3c  wrapper around.<
2490: 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 28 29 3c  b>sqlite_exec()<
24a0: 2f 62 3e 20 74 68 61 74 20 63 6f 6c 6c 65 63 74  /b> that collect
24b0: 73 20 61 6c 6c 20 74 68 65 20 69 6e 66 6f 72 6d  s all the inform
24c0: 61 74 69 6f 6e 20 66 72 6f 6d 20 73 75 63 63 65  ation from succe
24d0: 73 73 69 76 65 0a 63 61 6c 6c 62 61 63 6b 73 20  ssive.callbacks 
24e0: 61 6e 64 20 77 72 69 74 65 20 69 74 20 69 6e 74  and write it int
24f0: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
2500: 64 20 66 72 6f 6d 20 6d 61 6c 6c 6f 63 28 29 2e  d from malloc().
2510: 20 20 54 68 69 73 0a 69 73 20 61 20 63 6f 6e 76    This.is a conv
2520: 65 6e 69 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e  enience function
2530: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 74 68 65   that allows the
2540: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
2550: 67 65 74 20 74 68 65 0a 65 6e 74 69 72 65 20 72  get the.entire r
2560: 65 73 75 6c 74 20 6f 66 20 61 20 64 61 74 61 62  esult of a datab
2570: 61 73 65 20 71 75 65 72 79 20 77 69 74 68 20 61  ase query with a
2580: 20 73 69 6e 67 6c 65 20 66 75 6e 63 74 69 6f 6e   single function
2590: 20 63 61 6c 6c 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54   call.</p>..<p>T
25a0: 68 65 20 6d 61 69 6e 20 72 65 73 75 6c 74 20 66  he main result f
25b0: 72 6f 6d 20 3c 62 3e 73 71 6c 69 74 65 5f 67 65  rom <b>sqlite_ge
25c0: 74 5f 74 61 62 6c 65 28 29 3c 2f 62 3e 20 69 73  t_table()</b> is
25d0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
25e0: 6e 74 65 72 73 0a 74 6f 20 73 74 72 69 6e 67 73  nters.to strings
25f0: 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20  .  There is one 
2600: 65 6c 65 6d 65 6e 74 20 69 6e 20 74 68 69 73 20  element in this 
2610: 61 72 72 61 79 20 66 6f 72 20 65 61 63 68 20 63  array for each c
2620: 6f 6c 75 6d 6e 20 6f 66 0a 65 61 63 68 20 72 6f  olumn of.each ro
2630: 77 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e  w in the result.
2640: 20 20 4e 55 4c 4c 20 72 65 73 75 6c 74 73 20 61    NULL results a
2650: 72 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  re represented b
2660: 79 20 61 20 4e 55 4c 4c 0a 70 6f 69 6e 74 65 72  y a NULL.pointer
2670: 2e 20 49 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f  . In addition to
2680: 20 74 68 65 20 72 65 67 75 6c 61 72 20 64 61 74   the regular dat
2690: 61 2c 20 74 68 65 72 65 20 69 73 20 61 6e 20 61  a, there is an a
26a0: 64 64 65 64 20 72 6f 77 20 61 74 20 74 68 65 20  dded row at the 
26b0: 0a 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 74 68  .beginning of th
26c0: 65 20 61 72 72 61 79 20 74 68 61 74 20 63 6f 6e  e array that con
26d0: 74 61 69 6e 73 20 74 68 65 20 6e 61 6d 65 73 20  tains the names 
26e0: 6f 66 20 65 61 63 68 20 63 6f 6c 75 6d 6e 20 6f  of each column o
26f0: 66 20 74 68 65 0a 72 65 73 75 6c 74 2e 3c 2f 70  f the.result.</p
2700: 3e 0a 0a 3c 70 3e 41 73 20 61 6e 20 65 78 61 6d  >..<p>As an exam
2710: 70 6c 65 2c 20 63 6f 6e 73 69 64 65 72 20 74 68  ple, consider th
2720: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72  e following quer
2730: 79 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75  y:</p>..<blockqu
2740: 6f 74 65 3e 0a 53 45 4c 45 43 54 20 65 6d 70 6c  ote>.SELECT empl
2750: 6f 79 65 65 5f 6e 61 6d 65 2c 20 6c 6f 67 69 6e  oyee_name, login
2760: 2c 20 68 6f 73 74 20 46 52 4f 4d 20 75 73 65 72  , host FROM user
2770: 73 20 57 48 45 52 45 20 6c 6f 67 69 63 20 4c 49  s WHERE logic LI
2780: 4b 45 20 27 64 25 27 3b 0a 3c 2f 62 6c 6f 63 6b  KE 'd%';.</block
2790: 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 69 73 20  quote>..<p>This 
27a0: 71 75 65 72 79 20 77 69 6c 6c 20 72 65 74 75 72  query will retur
27b0: 6e 20 74 68 65 20 6e 61 6d 65 2c 20 6c 6f 67 69  n the name, logi
27c0: 6e 20 61 6e 64 20 68 6f 73 74 20 63 6f 6d 70 75  n and host compu
27d0: 74 65 72 20 6e 61 6d 65 0a 66 6f 72 20 65 76 65  ter name.for eve
27e0: 72 79 20 65 6d 70 6c 6f 79 65 65 20 77 68 6f 73  ry employee whos
27f0: 65 20 6c 6f 67 69 6e 20 62 65 67 69 6e 73 20 77  e login begins w
2800: 69 74 68 20 74 68 65 20 6c 65 74 74 65 72 20 22  ith the letter "
2810: 64 22 2e 20 20 49 66 20 74 68 69 73 0a 71 75 65  d".  If this.que
2820: 72 79 20 69 73 20 73 75 62 6d 69 74 74 65 64 20  ry is submitted 
2830: 74 6f 20 3c 62 3e 73 71 6c 69 74 65 5f 67 65 74  to <b>sqlite_get
2840: 5f 74 61 62 6c 65 28 29 3c 2f 62 3e 20 74 68 65  _table()</b> the
2850: 20 72 65 73 75 6c 74 20 6d 69 67 68 74 0a 6c 6f   result might.lo
2860: 6f 6b 20 6c 69 6b 65 20 74 68 69 73 3a 3c 2f 70  ok like this:</p
2870: 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  >..<blockquote>.
2880: 6e 72 6f 77 20 3d 20 32 3c 62 72 3e 0a 6e 63 6f  nrow = 2<br>.nco
2890: 6c 75 6d 6e 20 3d 20 33 3c 62 72 3e 0a 72 65 73  lumn = 3<br>.res
28a0: 75 6c 74 5b 30 5d 20 3d 20 22 65 6d 70 6c 6f 79  ult[0] = "employ
28b0: 65 65 5f 6e 61 6d 65 22 3c 62 72 3e 0a 72 65 73  ee_name"<br>.res
28c0: 75 6c 74 5b 31 5d 20 3d 20 22 6c 6f 67 69 6e 22  ult[1] = "login"
28d0: 3c 62 72 3e 0a 72 65 73 75 6c 74 5b 32 5d 20 3d  <br>.result[2] =
28e0: 20 22 68 6f 73 74 22 3c 62 72 3e 0a 72 65 73 75   "host"<br>.resu
28f0: 6c 74 5b 33 5d 20 3d 20 22 64 75 6d 6d 79 22 3c  lt[3] = "dummy"<
2900: 62 72 3e 0a 72 65 73 75 6c 74 5b 34 5d 20 3d 20  br>.result[4] = 
2910: 22 4e 6f 20 73 75 63 68 20 75 73 65 72 22 3c 62  "No such user"<b
2920: 72 3e 0a 72 65 73 75 6c 74 5b 35 5d 20 3d 20 30  r>.result[5] = 0
2930: 3c 62 72 3e 0a 72 65 73 75 6c 74 5b 36 5d 20 3d  <br>.result[6] =
2940: 20 22 44 2e 20 52 69 63 68 61 72 64 20 48 69 70   "D. Richard Hip
2950: 70 22 3c 62 72 3e 0a 72 65 73 75 6c 74 5b 37 5d  p"<br>.result[7]
2960: 20 3d 20 22 64 72 68 22 3c 62 72 3e 0a 72 65 73   = "drh"<br>.res
2970: 75 6c 74 5b 38 5d 20 3d 20 22 7a 61 64 6f 6b 22  ult[8] = "zadok"
2980: 0a 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a  .</blockquote>..
2990: 3c 70 3e 4e 6f 74 69 63 65 20 74 68 61 74 20 74  <p>Notice that t
29a0: 68 65 20 22 68 6f 73 74 22 20 76 61 6c 75 65 20  he "host" value 
29b0: 66 6f 72 20 74 68 65 20 22 64 75 6d 6d 79 22 20  for the "dummy" 
29c0: 72 65 63 6f 72 64 20 69 73 20 4e 55 4c 4c 20 73  record is NULL s
29d0: 6f 0a 74 68 65 20 72 65 73 75 6c 74 5b 5d 20 61  o.the result[] a
29e0: 72 72 61 79 20 63 6f 6e 74 61 69 6e 73 20 61 20  rray contains a 
29f0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 74 20  NULL pointer at 
2a00: 74 68 61 74 20 73 6c 6f 74 2e 3c 2f 70 3e 0a 0a  that slot.</p>..
2a10: 3c 70 3e 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c  <p>Memory to hol
2a20: 64 20 74 68 65 20 69 6e 66 6f 72 6d 61 74 69 6f  d the informatio
2a30: 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 3c 62  n returned by <b
2a40: 3e 73 71 6c 69 74 65 5f 67 65 74 5f 74 61 62 6c  >sqlite_get_tabl
2a50: 65 28 29 3c 2f 62 3e 0a 69 73 20 6f 62 74 61 69  e()</b>.is obtai
2a60: 6e 65 64 20 66 72 6f 6d 20 6d 61 6c 6c 6f 63 28  ned from malloc(
2a70: 29 2e 20 20 42 75 74 20 74 68 65 20 63 61 6c 6c  ).  But the call
2a80: 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ing function sho
2a90: 75 6c 64 20 6e 6f 74 20 74 72 79 0a 74 6f 20 66  uld not try.to f
2aa0: 72 65 65 20 74 68 69 73 20 69 6e 66 6f 72 6d 61  ree this informa
2ab0: 74 69 6f 6e 20 64 69 72 65 63 74 6c 79 2e 20 20  tion directly.  
2ac0: 49 6e 73 74 65 61 64 2c 20 70 61 73 73 20 74 68  Instead, pass th
2ad0: 65 20 63 6f 6d 70 6c 65 74 65 20 74 61 62 6c 65  e complete table
2ae0: 0a 74 6f 20 3c 62 3e 73 71 6c 69 74 65 5f 66 72  .to <b>sqlite_fr
2af0: 65 65 5f 74 61 62 6c 65 28 29 3c 2f 62 3e 20 77  ee_table()</b> w
2b00: 68 65 6e 20 74 68 65 20 74 61 62 6c 65 20 69 73  hen the table is
2b10: 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65   no longer neede
2b20: 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 3c  d.</p>..<p>The <
2b30: 62 3e 73 71 6c 69 74 65 5f 67 65 74 5f 74 61 62  b>sqlite_get_tab
2b40: 6c 65 28 29 3c 2f 62 3e 20 72 6f 75 74 69 6e 65  le()</b> routine
2b50: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 61 6d   returns the sam
2b60: 65 20 69 6e 74 65 67 65 72 0a 72 65 73 75 6c 74  e integer.result
2b70: 20 63 6f 64 65 20 61 73 20 3c 62 3e 73 71 6c 69   code as <b>sqli
2b80: 74 65 5f 65 78 65 63 28 29 3c 2f 62 3e 2e 3c 2f  te_exec()</b>.</
2b90: 70 3e 0a 0a 3c 68 32 3e 54 65 73 74 69 6e 67 20  p>..<h2>Testing 
2ba0: 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 20 53  for a complete S
2bb0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 3c 2f 68 32  QL statement</h2
2bc0: 3e 0a 0a 3c 70 3e 54 68 65 20 6c 61 73 74 20 69  >..<p>The last i
2bd0: 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
2be0: 20 74 6f 20 53 51 4c 69 74 65 20 69 73 20 61 20   to SQLite is a 
2bf0: 63 6f 6e 76 65 6e 69 65 6e 63 65 20 66 75 6e 63  convenience func
2c00: 74 69 6f 6e 20 75 73 65 64 0a 74 6f 20 74 65 73  tion used.to tes
2c10: 74 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  t whether or not
2c20: 20 61 20 73 74 72 69 6e 67 20 66 6f 72 6d 73 20   a string forms 
2c30: 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
2c40: 74 61 74 65 6d 65 6e 74 2e 0a 49 66 20 74 68 65  tatement..If the
2c50: 20 3c 62 3e 73 71 6c 69 74 65 5f 63 6f 6d 70 6c   <b>sqlite_compl
2c60: 65 74 65 28 29 3c 2f 62 3e 20 66 75 6e 63 74 69  ete()</b> functi
2c70: 6f 6e 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  on returns true 
2c80: 77 68 65 6e 20 69 74 73 20 69 6e 70 75 74 0a 69  when its input.i
2c90: 73 20 61 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  s a string, then
2ca0: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 66 6f   the argument fo
2cb0: 72 6d 73 20 61 20 63 6f 6d 70 6c 65 74 65 20 53  rms a complete S
2cc0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 54 68  QL statement..Th
2cd0: 65 72 65 20 61 72 65 20 6e 6f 20 67 75 61 72 61  ere are no guara
2ce0: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73  ntees that the s
2cf0: 79 6e 74 61 78 20 6f 66 20 74 68 61 74 20 73 74  yntax of that st
2d00: 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 72 72 65  atement is corre
2d10: 63 74 2c 0a 62 75 74 20 77 65 20 61 74 20 6c 65  ct,.but we at le
2d20: 61 73 74 20 6b 6e 6f 77 20 74 68 65 20 73 74 61  ast know the sta
2d30: 74 65 6d 65 6e 74 20 69 73 20 63 6f 6d 70 6c 65  tement is comple
2d40: 74 65 2e 20 20 49 66 20 3c 62 3e 73 71 6c 69 74  te.  If <b>sqlit
2d50: 65 5f 63 6f 6d 70 6c 65 74 65 28 29 3c 2f 62 3e  e_complete()</b>
2d60: 0a 72 65 74 75 72 6e 73 20 66 61 6c 73 65 2c 20  .returns false, 
2d70: 74 68 65 6e 20 6d 6f 72 65 20 74 65 78 74 20 69  then more text i
2d80: 73 20 72 65 71 75 69 72 65 64 20 74 6f 20 63 6f  s required to co
2d90: 6d 70 6c 65 74 65 20 74 68 65 20 53 51 4c 20 73  mplete the SQL s
2da0: 74 61 74 65 6d 65 6e 74 2e 3c 2f 70 3e 0a 0a 3c  tatement.</p>..<
2db0: 70 3e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73  p>For the purpos
2dc0: 65 20 6f 66 20 74 68 65 20 3c 62 3e 73 71 6c 69  e of the <b>sqli
2dd0: 74 65 5f 63 6f 6d 70 6c 65 74 65 28 29 3c 2f 62  te_complete()</b
2de0: 3e 20 66 75 6e 63 74 69 6f 6e 2c 20 61 6e 20 53  > function, an S
2df0: 51 4c 0a 73 74 61 74 65 6d 65 6e 74 20 69 73 20  QL.statement is 
2e00: 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65  complete if it e
2e10: 6e 64 73 20 69 6e 20 61 20 73 65 6d 69 63 6f 6c  nds in a semicol
2e20: 6f 6e 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20  on.</p>..<p>The 
2e30: 3c 62 3e 73 71 6c 69 74 65 3c 2f 62 3e 20 63 6f  <b>sqlite</b> co
2e40: 6d 6d 61 6e 64 2d 6c 69 6e 65 20 75 74 69 6c 69  mmand-line utili
2e50: 74 79 20 75 73 65 73 20 74 68 65 20 3c 62 3e 73  ty uses the <b>s
2e60: 71 6c 69 74 65 5f 63 6f 6d 70 6c 65 74 65 28 29  qlite_complete()
2e70: 3c 2f 62 3e 0a 66 75 6e 63 74 69 6f 6e 20 74 6f  </b>.function to
2e80: 20 6b 6e 6f 77 20 77 68 65 6e 20 69 74 20 6e 65   know when it ne
2e90: 65 64 73 20 74 6f 20 63 61 6c 6c 20 3c 62 3e 73  eds to call <b>s
2ea0: 71 6c 69 74 65 5f 65 78 65 63 28 29 3c 2f 62 3e  qlite_exec()</b>
2eb0: 2e 20 20 41 66 74 65 72 20 65 61 63 68 0a 6c 69  .  After each.li
2ec0: 6e 65 20 6f 66 20 69 6e 70 75 74 20 69 73 20 72  ne of input is r
2ed0: 65 63 65 69 76 65 64 2c 20 3c 62 3e 73 71 6c 69  eceived, <b>sqli
2ee0: 74 65 3c 2f 62 3e 20 63 61 6c 6c 73 20 3c 62 3e  te</b> calls <b>
2ef0: 73 71 6c 69 74 65 5f 63 6f 6d 70 6c 65 74 65 28  sqlite_complete(
2f00: 29 3c 2f 62 3e 0a 6f 6e 20 61 6c 6c 20 69 6e 70  )</b>.on all inp
2f10: 75 74 20 69 6e 20 69 74 73 20 62 75 66 66 65 72  ut in its buffer
2f20: 2e 20 20 49 66 20 3c 62 3e 73 71 6c 69 74 65 5f  .  If <b>sqlite_
2f30: 63 6f 6d 70 6c 65 74 65 28 29 3c 2f 62 3e 20 72  complete()</b> r
2f40: 65 74 75 72 6e 73 20 74 72 75 65 2c 20 0a 74 68  eturns true, .th
2f50: 65 6e 20 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65  en <b>sqlite_exe
2f60: 63 28 29 3c 2f 62 3e 20 69 73 20 63 61 6c 6c 65  c()</b> is calle
2f70: 64 20 61 6e 64 20 74 68 65 20 69 6e 70 75 74 20  d and the input 
2f80: 62 75 66 66 65 72 20 69 73 20 72 65 73 65 74 2e  buffer is reset.
2f90: 20 20 49 66 0a 3c 62 3e 73 71 6c 69 74 65 5f 63    If.<b>sqlite_c
2fa0: 6f 6d 70 6c 65 74 65 28 29 3c 2f 62 3e 20 72 65  omplete()</b> re
2fb0: 74 75 72 6e 73 20 66 61 6c 73 65 2c 20 74 68 65  turns false, the
2fc0: 6e 20 74 68 65 20 70 72 6f 6d 70 74 20 69 73 20  n the prompt is 
2fd0: 63 68 61 6e 67 65 64 20 74 6f 0a 74 68 65 20 63  changed to.the c
2fe0: 6f 6e 74 69 6e 75 61 74 69 6f 6e 20 70 72 6f 6d  ontinuation prom
2ff0: 70 74 20 61 6e 64 20 61 6e 6f 74 68 65 72 20 6c  pt and another l
3000: 69 6e 65 20 6f 66 20 74 65 78 74 20 69 73 20 72  ine of text is r
3010: 65 61 64 20 61 6e 64 20 61 64 64 65 64 20 74 6f  ead and added to
3020: 0a 74 68 65 20 69 6e 70 75 74 20 62 75 66 66 65  .the input buffe
3030: 72 2e 3c 2f 70 3e 0a 0a 3c 68 32 3e 4c 69 62 72  r.</p>..<h2>Libr
3040: 61 72 79 20 76 65 72 73 69 6f 6e 20 73 74 72 69  ary version stri
3050: 6e 67 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 68 65 20  ng</h2>..<p>The 
3060: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 65  SQLite library e
3070: 78 70 6f 72 74 73 20 74 68 65 20 73 74 72 69 6e  xports the strin
3080: 67 20 63 6f 6e 73 74 61 6e 74 20 6e 61 6d 65 64  g constant named
3090: 0a 3c 62 3e 73 71 6c 69 74 65 5f 76 65 72 73 69  .<b>sqlite_versi
30a0: 6f 6e 3c 2f 62 3e 20 77 68 69 63 68 20 63 6f 6e  on</b> which con
30b0: 74 61 69 6e 73 20 74 68 65 20 76 65 72 73 69 6f  tains the versio
30c0: 6e 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 65 0a  n number of the.
30d0: 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 68 65  library.  The he
30e0: 61 64 65 72 20 66 69 6c 65 20 63 6f 6e 74 61 69  ader file contai
30f0: 6e 73 20 61 20 6d 61 63 72 6f 20 53 51 4c 49 54  ns a macro SQLIT
3100: 45 5f 56 45 52 53 49 4f 4e 0a 77 69 74 68 20 74  E_VERSION.with t
3110: 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
3120: 69 6f 6e 2e 20 20 49 66 20 64 65 73 69 72 65 64  ion.  If desired
3130: 2c 20 61 20 70 72 6f 67 72 61 6d 20 63 61 6e 20  , a program can 
3140: 63 6f 6d 70 61 72 65 0a 74 68 65 20 53 51 4c 49  compare.the SQLI
3150: 54 45 5f 56 45 52 53 49 4f 4e 20 6d 61 63 72 6f  TE_VERSION macro
3160: 20 61 67 61 69 6e 73 74 20 74 68 65 20 3c 62 3e   against the <b>
3170: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 3c 2f  sqlite_version</
3180: 62 3e 0a 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  b>.string consta
3190: 6e 74 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  nt to verify tha
31a0: 74 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75  t the version nu
31b0: 6d 62 65 72 20 6f 66 20 74 68 65 0a 68 65 61 64  mber of the.head
31c0: 65 72 20 66 69 6c 65 20 61 6e 64 20 74 68 65 20  er file and the 
31d0: 6c 69 62 72 61 72 79 20 6d 61 74 63 68 2e 3c 2f  library match.</
31e0: 70 3e 20 0a 0a 3c 68 32 3e 43 68 61 6e 67 69 6e  p> ..<h2>Changin
31f0: 67 20 74 68 65 20 6c 69 62 72 61 72 69 65 73 20  g the libraries 
3200: 72 65 73 70 6f 6e 73 65 20 74 6f 20 6c 6f 63 6b  response to lock
3210: 65 64 20 66 69 6c 65 73 3c 2f 68 32 3e 0a 0a 3c  ed files</h2>..<
3220: 70 3e 54 68 65 20 47 44 42 4d 20 6c 69 62 72 61  p>The GDBM libra
3230: 72 79 20 73 75 70 70 6f 72 74 73 20 64 61 74 61  ry supports data
3240: 62 61 73 65 20 6c 6f 63 6b 73 20 61 74 20 74 68  base locks at th
3250: 65 20 66 69 6c 65 20 6c 65 76 65 6c 2e 0a 49 66  e file level..If
3260: 20 61 20 47 44 42 4d 20 64 61 74 61 62 61 73 65   a GDBM database
3270: 20 66 69 6c 65 20 69 73 20 6f 70 65 6e 65 64 20   file is opened 
3280: 66 6f 72 20 72 65 61 64 69 6e 67 2c 20 74 68 65  for reading, the
3290: 6e 20 74 68 61 74 20 73 61 6d 65 0a 66 69 6c 65  n that same.file
32a0: 20 63 61 6e 6e 6f 74 20 62 65 20 72 65 6f 70 65   cannot be reope
32b0: 6e 65 64 20 66 6f 72 20 77 72 69 74 69 6e 67 20  ned for writing 
32c0: 75 6e 74 69 6c 20 61 6c 6c 20 72 65 61 64 65 72  until all reader
32d0: 73 20 68 61 76 65 20 63 6c 6f 73 65 64 0a 74 68  s have closed.th
32e0: 65 20 66 69 6c 65 2e 20 20 49 66 20 61 20 47 44  e file.  If a GD
32f0: 42 4d 20 66 69 6c 65 20 69 73 20 6f 70 65 6e 20  BM file is open 
3300: 66 6f 72 20 77 72 69 74 69 6e 67 2c 20 74 68 65  for writing, the
3310: 6e 20 74 68 65 20 66 69 6c 65 20 63 61 6e 6e 6f  n the file canno
3320: 74 0a 62 65 20 72 65 6f 70 65 6e 65 64 20 66 6f  t.be reopened fo
3330: 72 20 72 65 61 64 69 6e 67 20 6f 72 20 77 72 69  r reading or wri
3340: 74 69 6e 67 20 75 6e 74 69 6c 20 69 74 20 69 73  ting until it is
3350: 20 63 6c 6f 73 65 64 2e 3c 2f 70 3e 0a 0a 3c 70   closed.</p>..<p
3360: 3e 49 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c  >If the SQLite l
3370: 69 62 72 61 72 79 20 61 74 74 65 6d 70 74 73 20  ibrary attempts 
3380: 74 6f 20 6f 70 65 6e 20 61 20 47 44 42 4d 20 66  to open a GDBM f
3390: 69 6c 65 20 61 6e 64 20 66 69 6e 64 73 20 74 68  ile and finds th
33a0: 61 74 0a 74 68 65 20 66 69 6c 65 20 69 73 20 6c  at.the file is l
33b0: 6f 63 6b 65 64 2c 20 74 68 65 20 64 65 66 61 75  ocked, the defau
33c0: 6c 74 20 61 63 74 69 6f 6e 20 69 73 20 74 6f 20  lt action is to 
33d0: 61 62 6f 72 74 20 74 68 65 20 63 75 72 72 65 6e  abort the curren
33e0: 74 0a 6f 70 65 72 61 74 69 6f 6e 20 61 6e 64 20  t.operation and 
33f0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 42 55  return SQLITE_BU
3400: 53 59 2e 20 20 42 75 74 20 74 68 69 73 20 69 73  SY.  But this is
3410: 20 6e 6f 74 20 61 6c 77 61 79 73 20 74 68 65 20   not always the 
3420: 6d 6f 73 74 0a 63 6f 6e 76 65 6e 69 65 6e 74 20  most.convenient 
3430: 62 65 68 61 76 69 6f 72 2c 20 73 6f 20 61 20 6d  behavior, so a m
3440: 65 63 68 61 6e 69 73 6d 20 65 78 69 73 74 73 20  echanism exists 
3450: 74 6f 20 63 68 61 6e 67 65 20 69 74 2e 3c 2f 70  to change it.</p
3460: 3e 0a 0a 3c 70 3e 54 68 65 20 3c 62 3e 73 71 6c  >..<p>The <b>sql
3470: 69 74 65 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  ite_busy_handler
3480: 28 29 3c 2f 62 3e 20 70 72 6f 63 65 64 75 72 65  ()</b> procedure
3490: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
34a0: 72 65 67 69 73 74 65 72 0a 61 20 62 75 73 79 20  register.a busy 
34b0: 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 6e  callback with an
34c0: 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74   open SQLite dat
34d0: 61 62 61 73 65 2e 20 20 54 68 65 20 62 75 73 79  abase.  The busy
34e0: 20 63 61 6c 6c 62 61 63 6b 20 77 69 6c 6c 0a 62   callback will.b
34f0: 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
3500: 65 72 20 53 51 4c 69 74 65 20 74 72 69 65 73 20  er SQLite tries 
3510: 74 6f 20 6f 70 65 6e 20 61 20 47 44 42 4d 20 66  to open a GDBM f
3520: 69 6c 65 20 74 68 61 74 20 69 73 20 6c 6f 63 6b  ile that is lock
3530: 65 64 2e 0a 54 68 65 20 63 61 6c 6c 62 61 63 6b  ed..The callback
3540: 20 77 69 6c 6c 20 74 79 70 69 63 61 6c 6c 79 20   will typically 
3550: 64 6f 20 73 6f 6d 65 20 6f 74 68 65 72 20 75 73  do some other us
3560: 65 66 75 6c 20 77 6f 72 6b 2c 20 6f 72 20 70 65  eful work, or pe
3570: 72 68 61 70 73 20 73 6c 65 65 70 2c 0a 69 6e 20  rhaps sleep,.in 
3580: 6f 72 64 65 72 20 74 6f 20 67 69 76 65 20 74 68  order to give th
3590: 65 20 6c 6f 63 6b 20 61 20 63 68 61 6e 63 65 20  e lock a chance 
35a0: 74 6f 20 63 6c 65 61 72 2e 20 20 49 66 20 74 68  to clear.  If th
35b0: 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
35c0: 6e 73 0a 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns.non-zero, the
35d0: 6e 20 53 51 4c 69 74 65 20 74 72 69 65 73 20 61  n SQLite tries a
35e0: 67 61 69 6e 20 74 6f 20 6f 70 65 6e 20 74 68 65  gain to open the
35f0: 20 47 44 42 4d 20 66 69 6c 65 20 61 6e 64 20 74   GDBM file and t
3600: 68 65 20 63 79 63 6c 65 0a 72 65 70 65 61 74 73  he cycle.repeats
3610: 2e 20 20 49 66 20 74 68 65 20 63 61 6c 6c 62 61  .  If the callba
3620: 63 6b 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  ck returns zero,
3630: 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 62 6f   then SQLite abo
3640: 72 74 73 20 74 68 65 20 63 75 72 72 65 6e 74 0a  rts the current.
3650: 6f 70 65 72 61 74 69 6f 6e 20 61 6e 64 20 72 65  operation and re
3660: 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 42 55 53  turns SQLITE_BUS
3670: 59 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 61  Y.</p>..<p>The a
3680: 72 67 75 6d 65 6e 74 73 20 74 6f 20 3c 62 3e 73  rguments to <b>s
3690: 71 6c 69 74 65 5f 62 75 73 79 5f 68 61 6e 64 6c  qlite_busy_handl
36a0: 65 72 28 29 3c 2f 62 3e 20 61 72 65 20 74 68 65  er()</b> are the
36b0: 20 6f 70 61 71 75 65 0a 73 74 72 75 63 74 75 72   opaque.structur
36c0: 65 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  e returned from 
36d0: 3c 62 3e 73 71 6c 69 74 65 5f 6f 70 65 6e 28 29  <b>sqlite_open()
36e0: 3c 2f 62 3e 2c 20 61 20 70 6f 69 6e 74 65 72 20  </b>, a pointer 
36f0: 74 6f 20 74 68 65 20 62 75 73 79 0a 63 61 6c 6c  to the busy.call
3700: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2c 20 61  back function, a
3710: 6e 64 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69  nd a generic poi
3720: 6e 74 65 72 20 74 68 61 74 20 77 69 6c 6c 20 62  nter that will b
3730: 65 20 70 61 73 73 65 64 20 61 73 0a 74 68 65 20  e passed as.the 
3740: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
3750: 6f 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  o the busy callb
3760: 61 63 6b 2e 20 20 57 68 65 6e 20 53 51 4c 69 74  ack.  When SQLit
3770: 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 0a 62 75  e invokes the.bu
3780: 73 79 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20  sy callback, it 
3790: 73 65 6e 64 73 20 69 74 20 74 68 72 65 65 20 61  sends it three a
37a0: 72 67 75 6d 65 6e 74 73 3a 20 20 74 68 65 20 67  rguments:  the g
37b0: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 0a 74  eneric pointer.t
37c0: 68 61 74 20 77 61 73 20 70 61 73 73 65 64 20 69  hat was passed i
37d0: 6e 20 61 73 20 74 68 65 20 74 68 69 72 64 20 61  n as the third a
37e0: 72 67 75 6d 65 6e 74 20 74 6f 20 3c 62 3e 73 71  rgument to <b>sq
37f0: 6c 69 74 65 5f 62 75 73 79 5f 68 61 6e 64 6c 65  lite_busy_handle
3800: 72 3c 2f 62 3e 2c 0a 74 68 65 20 6e 61 6d 65 20  r</b>,.the name 
3810: 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
3820: 74 61 62 6c 65 20 6f 72 20 69 6e 64 65 78 20 74  table or index t
3830: 68 61 74 20 74 68 65 20 6c 69 62 72 61 72 79 20  hat the library 
3840: 69 73 20 74 72 79 69 6e 67 0a 74 6f 20 6f 70 65  is trying.to ope
3850: 6e 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  n, and the numbe
3860: 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20  r of times that 
3870: 74 68 65 20 6c 69 62 72 61 72 79 20 68 61 73 20  the library has 
3880: 61 74 74 65 6d 70 74 65 64 20 74 6f 0a 6f 70 65  attempted to.ope
3890: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  n the database t
38a0: 61 62 6c 65 20 6f 72 20 69 6e 64 65 78 2e 3c 2f  able or index.</
38b0: 70 3e 0a 0a 3c 70 3e 46 6f 72 20 74 68 65 20 63  p>..<p>For the c
38c0: 6f 6d 6d 6f 6e 20 63 61 73 65 20 77 68 65 72 65  ommon case where
38d0: 20 77 65 20 77 61 6e 74 20 74 68 65 20 62 75 73   we want the bus
38e0: 79 20 63 61 6c 6c 62 61 63 6b 20 74 6f 20 73 6c  y callback to sl
38f0: 65 65 70 2c 0a 74 68 65 20 53 51 4c 69 74 65 20  eep,.the SQLite 
3900: 6c 69 62 72 61 72 79 20 70 72 6f 76 69 64 65 73  library provides
3910: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 72   a convenience r
3920: 6f 75 74 69 6e 65 20 3c 62 3e 73 71 6c 69 74 65  outine <b>sqlite
3930: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 3c  _busy_timeout()<
3940: 2f 62 3e 2e 0a 54 68 65 20 66 69 72 73 74 20 61  /b>..The first a
3950: 72 67 75 6d 65 6e 74 20 74 6f 20 3c 62 3e 73 71  rgument to <b>sq
3960: 6c 69 74 65 5f 62 75 73 79 5f 74 69 6d 65 6f 75  lite_busy_timeou
3970: 74 28 29 3c 2f 62 3e 20 69 73 20 61 20 70 6f 69  t()</b> is a poi
3980: 6e 74 65 72 20 74 6f 0a 61 6e 20 6f 70 65 6e 20  nter to.an open 
3990: 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
39a0: 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61  and the second a
39b0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 6e 75 6d  rgument is a num
39c0: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
39d0: 6e 64 73 2e 0a 41 66 74 65 72 20 3c 62 3e 73 71  nds..After <b>sq
39e0: 6c 69 74 65 5f 62 75 73 79 5f 74 69 6d 65 6f 75  lite_busy_timeou
39f0: 74 28 29 3c 2f 62 3e 20 68 61 73 20 62 65 65 6e  t()</b> has been
3a00: 20 65 78 65 63 75 74 65 64 2c 20 74 68 65 20 53   executed, the S
3a10: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 0a 77 69  QLite library.wi
3a20: 6c 6c 20 77 61 69 74 20 66 6f 72 20 74 68 65 20  ll wait for the 
3a30: 6c 6f 63 6b 20 74 6f 20 63 6c 65 61 72 20 66 6f  lock to clear fo
3a40: 72 20 61 74 20 6c 65 61 73 74 20 74 68 65 20 6e  r at least the n
3a50: 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
3a60: 63 6f 6e 64 73 20 0a 73 70 65 63 69 66 69 65 64  conds .specified
3a70: 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
3a80: 6e 73 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 20  ns SQLITE_BUSY. 
3a90: 20 53 70 65 63 69 66 79 69 6e 67 20 7a 65 72 6f   Specifying zero
3aa0: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 66 6f   milliseconds fo
3ab0: 72 0a 74 68 65 20 74 69 6d 65 6f 75 74 20 72 65  r.the timeout re
3ac0: 73 74 6f 72 65 73 20 74 68 65 20 64 65 66 61 75  stores the defau
3ad0: 6c 74 20 62 65 68 61 76 69 6f 72 2e 3c 2f 70 3e  lt behavior.</p>
3ae0: 0a 0a 3c 68 32 3e 55 73 69 6e 67 20 74 68 65 20  ..<h2>Using the 
3af0: 3c 74 74 3e 5f 70 72 69 6e 74 66 28 29 3c 2f 74  <tt>_printf()</t
3b00: 74 3e 20 77 72 61 70 70 65 72 20 66 75 6e 63 74  t> wrapper funct
3b10: 69 6f 6e 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 68  ions</h2>..<p>Th
3b20: 65 20 66 6f 75 72 20 75 74 69 6c 69 74 79 20 66  e four utility f
3b30: 75 6e 63 74 69 6f 6e 73 3c 2f 70 3e 0a 0a 3c 70  unctions</p>..<p
3b40: 3e 0a 3c 75 6c 3e 0a 3c 6c 69 3e 3c 62 3e 73 71  >.<ul>.<li><b>sq
3b50: 6c 69 74 65 5f 65 78 65 63 5f 70 72 69 6e 74 66  lite_exec_printf
3b60: 28 29 3c 2f 62 3e 3c 2f 6c 69 3e 0a 3c 6c 69 3e  ()</b></li>.<li>
3b70: 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 5f 76  <b>sqlite_exec_v
3b80: 70 72 69 6e 74 66 28 29 3c 2f 62 3e 3c 2f 6c 69  printf()</b></li
3b90: 3e 0a 3c 6c 69 3e 3c 62 3e 73 71 6c 69 74 65 5f  >.<li><b>sqlite_
3ba0: 67 65 74 5f 74 61 62 6c 65 5f 70 72 69 6e 74 66  get_table_printf
3bb0: 28 29 3c 2f 62 3e 3c 2f 6c 69 3e 0a 3c 6c 69 3e  ()</b></li>.<li>
3bc0: 3c 62 3e 73 71 6c 69 74 65 5f 67 65 74 5f 74 61  <b>sqlite_get_ta
3bd0: 62 6c 65 5f 76 70 72 69 6e 74 66 28 29 3c 2f 62  ble_vprintf()</b
3be0: 3e 3c 2f 6c 69 3e 0a 3c 2f 75 6c 3e 0a 3c 2f 70  ></li>.</ul>.</p
3bf0: 3e 0a 0a 3c 70 3e 69 6d 70 6c 65 6d 65 6e 74 20  >..<p>implement 
3c00: 74 68 65 20 73 61 6d 65 20 71 75 65 72 79 20 66  the same query f
3c10: 75 6e 63 74 69 6f 6e 61 6c 69 74 79 20 61 73 20  unctionality as 
3c20: 3c 62 3e 73 71 6c 69 74 65 5f 65 78 65 63 28 29  <b>sqlite_exec()
3c30: 3c 2f 62 3e 0a 61 6e 64 20 3c 62 3e 73 71 6c 69  </b>.and <b>sqli
3c40: 74 65 5f 67 65 74 5f 74 61 62 6c 65 28 29 3c 2f  te_get_table()</
3c50: 62 3e 2e 20 20 42 75 74 20 69 6e 73 74 65 61 64  b>.  But instead
3c60: 20 6f 66 20 74 61 6b 69 6e 67 20 61 20 63 6f 6d   of taking a com
3c70: 70 6c 65 74 65 0a 53 51 4c 20 73 74 61 74 65 6d  plete.SQL statem
3c80: 65 6e 74 20 61 73 20 74 68 65 69 72 20 73 65 63  ent as their sec
3c90: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 74 68  ond argument, th
3ca0: 65 20 66 6f 75 72 20 3c 62 3e 5f 70 72 69 6e 74  e four <b>_print
3cb0: 66 3c 2f 62 3e 0a 72 6f 75 74 69 6e 65 73 20 74  f</b>.routines t
3cc0: 61 6b 65 20 61 20 70 72 69 6e 74 66 2d 73 74 79  ake a printf-sty
3cd0: 6c 65 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67  le format string
3ce0: 2e 20 20 54 68 65 20 53 51 4c 20 73 74 61 74 65  .  The SQL state
3cf0: 6d 65 6e 74 20 74 6f 0a 62 65 20 65 78 65 63 75  ment to.be execu
3d00: 74 65 64 20 69 73 20 67 65 6e 65 72 61 74 65 64  ted is generated
3d10: 20 66 72 6f 6d 20 74 68 69 73 20 66 6f 72 6d 61   from this forma
3d20: 74 20 73 74 72 69 6e 67 20 61 6e 64 20 66 72 6f  t string and fro
3d30: 6d 20 77 68 61 74 65 76 65 72 0a 61 64 64 69 74  m whatever.addit
3d40: 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20  ional arguments 
3d50: 61 72 65 20 61 74 74 61 63 68 65 64 20 74 6f 20  are attached to 
3d60: 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66  the end of the f
3d70: 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 2e 3c 2f 70  unction call.</p
3d80: 3e 0a 0a 3c 70 3e 54 68 65 72 65 20 61 72 65 20  >..<p>There are 
3d90: 74 77 6f 20 61 64 76 61 6e 74 61 67 65 73 20 74  two advantages t
3da0: 6f 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 69  o using the SQLi
3db0: 74 65 20 70 72 69 6e 74 66 0a 66 75 6e 63 74 69  te printf.functi
3dc0: 6f 6e 73 20 69 6e 73 74 65 61 64 20 6f 66 20 3c  ons instead of <
3dd0: 62 3e 73 70 72 69 6e 74 66 28 29 3c 2f 62 3e 2e  b>sprintf()</b>.
3de0: 20 20 46 69 72 73 74 20 6f 66 20 61 6c 6c 2c 20    First of all, 
3df0: 77 69 74 68 20 74 68 65 0a 53 51 4c 69 74 65 20  with the.SQLite 
3e00: 70 72 69 6e 74 66 20 72 6f 75 74 69 6e 65 73 2c  printf routines,
3e10: 20 74 68 65 72 65 20 69 73 20 6e 65 76 65 72 20   there is never 
3e20: 61 20 64 61 6e 67 65 72 20 6f 66 20 6f 76 65 72  a danger of over
3e30: 66 6c 6f 77 69 6e 67 20 61 0a 73 74 61 74 69 63  flowing a.static
3e40: 20 62 75 66 66 65 72 20 61 73 20 74 68 65 72 65   buffer as there
3e50: 20 69 73 20 77 69 74 68 20 3c 62 3e 73 70 72 69   is with <b>spri
3e60: 6e 74 66 28 29 3c 2f 62 3e 2e 20 20 54 68 65 20  ntf()</b>.  The 
3e70: 53 51 4c 69 74 65 0a 70 72 69 6e 74 66 20 72 6f  SQLite.printf ro
3e80: 75 74 69 6e 65 73 20 61 75 74 6f 6d 61 74 69 63  utines automatic
3e90: 61 6c 6c 79 20 61 6c 6c 6f 63 61 74 65 20 28 61  ally allocate (a
3ea0: 6e 64 20 6c 61 74 65 72 20 66 72 65 65 29 0a 61  nd later free).a
3eb0: 73 20 6d 75 63 68 20 6d 65 6d 6f 72 79 20 61 73  s much memory as
3ec0: 20 69 73 20 0a 6e 65 63 65 73 73 61 72 79 20 74   is .necessary t
3ed0: 6f 20 68 6f 6c 64 20 74 68 65 20 53 51 4c 20 73  o hold the SQL s
3ee0: 74 61 74 65 6d 65 6e 74 73 20 67 65 6e 65 72 61  tatements genera
3ef0: 74 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65  ted.</p>..<p>The
3f00: 20 73 65 63 6f 6e 64 20 61 64 76 61 6e 74 61 67   second advantag
3f10: 65 20 74 68 65 20 53 51 4c 69 74 65 20 70 72 69  e the SQLite pri
3f20: 6e 74 66 20 72 6f 75 74 69 6e 65 73 20 68 61 76  ntf routines hav
3f30: 65 20 6f 76 65 72 0a 3c 62 3e 73 70 72 69 6e 74  e over.<b>sprint
3f40: 66 28 29 3c 2f 62 3e 20 69 73 20 61 20 6e 65 77  f()</b> is a new
3f50: 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
3f60: 6f 6e 20 73 70 65 63 69 66 69 63 61 6c 6c 79 20  on specifically 
3f70: 64 65 73 69 67 6e 65 64 0a 74 6f 20 73 75 70 70  designed.to supp
3f80: 6f 72 74 20 73 74 72 69 6e 67 20 6c 69 74 65 72  ort string liter
3f90: 61 6c 73 20 69 6e 20 53 51 4c 2e 20 20 57 69 74  als in SQL.  Wit
3fa0: 68 69 6e 20 74 68 65 20 66 6f 72 6d 61 74 20 73  hin the format s
3fb0: 74 72 69 6e 67 2c 0a 74 68 65 20 25 71 20 66 6f  tring,.the %q fo
3fc0: 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
3fd0: 77 6f 72 6b 73 20 76 65 72 79 20 6d 75 63 68 20  works very much 
3fe0: 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20  like %s in that 
3ff0: 69 74 0a 72 65 61 64 73 20 61 20 6e 75 6c 6c 2d  it.reads a null-
4000: 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
4010: 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d  g from the argum
4020: 65 6e 74 20 6c 69 73 74 20 61 6e 64 20 69 6e 73  ent list and ins
4030: 65 72 74 73 0a 69 74 20 69 6e 74 6f 20 74 68 65  erts.it into the
4040: 20 72 65 73 75 6c 74 2e 20 20 42 75 74 20 25 71   result.  But %q
4050: 20 74 72 61 6e 73 6c 61 74 65 73 20 74 68 65 20   translates the 
4060: 69 6e 73 65 72 74 65 64 20 73 74 72 69 6e 67 20  inserted string 
4070: 62 79 0a 6d 61 6b 69 6e 67 20 74 77 6f 20 63 6f  by.making two co
4080: 70 69 65 73 20 6f 66 20 65 76 65 72 79 20 73 69  pies of every si
4090: 6e 67 6c 65 2d 71 75 6f 74 65 20 28 27 29 20 63  ngle-quote (') c
40a0: 68 61 72 61 63 74 65 72 20 69 6e 20 74 68 65 0a  haracter in the.
40b0: 73 75 62 73 74 69 74 75 74 65 64 20 73 74 72 69  substituted stri
40c0: 6e 67 2e 20 20 54 68 69 73 20 68 61 73 20 74 68  ng.  This has th
40d0: 65 20 65 66 66 65 63 74 20 6f 66 20 65 73 63 61  e effect of esca
40e0: 70 69 6e 67 20 74 68 65 20 65 6e 64 2d 6f 66 2d  ping the end-of-
40f0: 73 74 72 69 6e 67 0a 6d 65 61 6e 69 6e 67 20 6f  string.meaning o
4100: 66 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 20 77  f single-quote w
4110: 69 74 68 69 6e 20 61 20 73 74 72 69 6e 67 20 6c  ithin a string l
4120: 69 74 65 72 61 6c 2e 0a 3c 2f 70 3e 0a 0a 3c 70  iteral..</p>..<p
4130: 3e 43 6f 6e 73 69 64 65 72 20 61 6e 20 65 78 61  >Consider an exa
4140: 6d 70 6c 65 2e 20 20 53 75 70 70 6f 73 65 20 79  mple.  Suppose y
4150: 6f 75 20 61 72 65 20 74 72 79 69 6e 67 20 74 6f  ou are trying to
4160: 20 69 6e 73 65 72 74 20 61 20 73 74 72 69 6e 67   insert a string
4170: 0a 76 61 6c 75 65 73 20 69 6e 74 6f 20 61 20 64  .values into a d
4180: 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 77 68  atabase table wh
4190: 65 72 65 20 74 68 65 20 73 74 72 69 6e 67 20 76  ere the string v
41a0: 61 6c 75 65 20 77 61 73 20 6f 62 74 61 69 6e 65  alue was obtaine
41b0: 64 20 66 72 6f 6d 0a 75 73 65 72 20 69 6e 70 75  d from.user inpu
41c0: 74 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  t.  Suppose the 
41d0: 73 74 72 69 6e 67 20 74 6f 20 62 65 20 69 6e 73  string to be ins
41e0: 65 72 74 65 64 20 69 73 20 73 74 6f 72 65 64 20  erted is stored 
41f0: 69 6e 20 61 20 76 61 72 69 61 62 6c 65 0a 6e 61  in a variable.na
4200: 6d 65 64 20 7a 53 74 72 69 6e 67 2e 20 20 54 68  med zString.  Th
4210: 65 20 63 6f 64 65 20 74 6f 20 69 6e 73 65 72 74  e code to insert
4220: 20 74 68 69 73 20 73 74 72 69 6e 67 20 6d 69 67   this string mig
4230: 68 74 20 6c 6f 6f 6b 20 6c 69 6b 65 20 74 68 69  ht look like thi
4240: 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75  s:</p>..<blockqu
4250: 6f 74 65 3e 3c 70 72 65 3e 0a 73 71 6c 69 74 65  ote><pre>.sqlite
4260: 5f 65 78 65 63 5f 70 72 69 6e 74 66 28 64 62 2c  _exec_printf(db,
4270: 0a 20 20 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  .  "INSERT INTO 
4280: 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 25  table1 VALUES('%
4290: 73 27 29 22 2c 0a 20 20 30 2c 20 30 2c 20 30 2c  s')",.  0, 0, 0,
42a0: 20 7a 53 74 72 69 6e 67 29 3b 0a 3c 2f 70 72 65   zString);.</pre
42b0: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a  ></blockquote>..
42c0: 3c 70 3e 49 66 20 74 68 65 20 7a 53 74 72 69 6e  <p>If the zStrin
42d0: 67 20 76 61 72 69 61 62 6c 65 20 68 6f 6c 64 73  g variable holds
42e0: 20 74 65 78 74 20 6c 69 6b 65 20 22 48 65 6c 6c   text like "Hell
42f0: 6f 22 2c 20 74 68 65 6e 20 74 68 69 73 20 73 74  o", then this st
4300: 61 74 65 6d 65 6e 74 0a 77 69 6c 6c 20 77 6f 72  atement.will wor
4310: 6b 20 6a 75 73 74 20 66 69 6e 65 2e 20 20 42 75  k just fine.  Bu
4320: 74 20 73 75 70 70 6f 73 65 20 74 68 65 20 75 73  t suppose the us
4330: 65 72 20 65 6e 74 65 72 73 20 61 20 73 74 72 69  er enters a stri
4340: 6e 67 20 6c 69 6b 65 20 0a 22 48 69 20 79 27 61  ng like ."Hi y'a
4350: 6c 6c 21 22 2e 20 20 54 68 65 20 53 51 4c 20 73  ll!".  The SQL s
4360: 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 74  tatement generat
4370: 65 64 20 72 65 61 64 73 20 61 73 20 66 6f 6c 6c  ed reads as foll
4380: 6f 77 73 3a 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74  ows:..<blockquot
4390: 65 3e 3c 70 72 65 3e 0a 49 4e 53 45 52 54 20 49  e><pre>.INSERT I
43a0: 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
43b0: 53 28 27 48 69 20 79 27 61 6c 6c 27 29 0a 3c 2f  S('Hi y'all').</
43c0: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
43d0: 3e 0a 0a 3c 70 3e 54 68 69 73 20 69 73 20 6e 6f  >..<p>This is no
43e0: 74 20 76 61 6c 69 64 20 53 51 4c 20 62 65 63 61  t valid SQL beca
43f0: 75 73 65 20 6f 66 20 74 68 65 20 61 70 6f 73 74  use of the apost
4400: 72 6f 70 68 79 20 69 6e 20 74 68 65 20 77 6f 72  rophy in the wor
4410: 64 20 22 79 27 61 6c 6c 22 2e 0a 42 75 74 20 69  d "y'all"..But i
4420: 66 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 74  f the %q formatt
4430: 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  ing option is us
4440: 65 64 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  ed instead of %s
4450: 2c 20 6c 69 6b 65 20 74 68 69 73 3a 3c 2f 70 3e  , like this:</p>
4460: 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  ..<blockquote><p
4470: 72 65 3e 0a 73 71 6c 69 74 65 5f 65 78 65 63 5f  re>.sqlite_exec_
4480: 70 72 69 6e 74 66 28 64 62 2c 0a 20 20 22 49 4e  printf(db,.  "IN
4490: 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
44a0: 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 0a   VALUES('%q')",.
44b0: 20 20 30 2c 20 30 2c 20 30 2c 20 7a 53 74 72 69    0, 0, 0, zStri
44c0: 6e 67 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ng);.</pre></blo
44d0: 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65  ckquote>..<p>The
44e0: 6e 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20  n the generated 
44f0: 53 51 4c 20 77 69 6c 6c 20 6c 6f 6f 6b 20 6c 69  SQL will look li
4500: 6b 65 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ke the following
4510: 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f  :</p>..<blockquo
4520: 74 65 3e 3c 70 72 65 3e 0a 49 4e 53 45 52 54 20  te><pre>.INSERT 
4530: 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
4540: 45 53 28 27 48 69 20 79 27 27 61 6c 6c 27 29 0a  ES('Hi y''all').
4550: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
4560: 74 65 3e 0a 0a 3c 70 3e 48 65 72 65 20 74 68 65  te>..<p>Here the
4570: 20 61 70 6f 73 74 72 6f 70 68 79 20 68 61 73 20   apostrophy has 
4580: 62 65 65 6e 20 65 73 63 61 70 65 64 20 61 6e 64  been escaped and
4590: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
45a0: 6e 74 20 69 73 20 77 65 6c 6c 2d 66 6f 72 6d 65  nt is well-forme
45b0: 64 2e 0a 57 68 65 6e 20 67 65 6e 65 72 61 74 69  d..When generati
45c0: 6e 67 20 53 51 4c 20 6f 6e 2d 74 68 65 2d 66 6c  ng SQL on-the-fl
45d0: 79 20 66 72 6f 6d 20 64 61 74 61 20 74 68 61 74  y from data that
45e0: 20 6d 69 67 68 74 20 63 6f 6e 74 61 69 6e 20 61   might contain a
45f0: 0a 73 69 6e 67 6c 65 2d 71 75 6f 74 65 20 63 68  .single-quote ch
4600: 61 72 61 63 74 65 72 20 28 27 29 2c 20 69 74 20  aracter ('), it 
4610: 69 73 20 61 6c 77 61 79 73 20 61 20 67 6f 6f 64  is always a good
4620: 20 69 64 65 61 20 74 6f 20 75 73 65 20 74 68 65   idea to use the
4630: 0a 53 51 4c 69 74 65 20 70 72 69 6e 74 66 20 72  .SQLite printf r
4640: 6f 75 74 69 6e 65 73 20 61 6e 64 20 74 68 65 20  outines and the 
4650: 25 71 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  %q formatting op
4660: 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20  tion instead of 
4670: 3c 62 3e 73 70 72 69 6e 74 66 3c 2f 62 3e 2e 0a  <b>sprintf</b>..
4680: 3c 2f 70 3e 0a 0a 3c 68 32 3e 55 73 61 67 65 20  </p>..<h2>Usage 
4690: 45 78 61 6d 70 6c 65 73 3c 2f 68 32 3e 0a 0a 3c  Examples</h2>..<
46a0: 70 3e 46 6f 72 20 65 78 61 6d 70 6c 65 73 20 6f  p>For examples o
46b0: 66 20 68 6f 77 20 74 68 65 20 53 51 4c 69 74 65  f how the SQLite
46c0: 20 43 2f 43 2b 2b 20 69 6e 74 65 72 66 61 63 65   C/C++ interface
46d0: 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 72 65   can be used,.re
46e0: 66 65 72 20 74 6f 20 74 68 65 20 73 6f 75 72 63  fer to the sourc
46f0: 65 20 63 6f 64 65 20 66 6f 72 20 74 68 65 20 3c  e code for the <
4700: 62 3e 73 71 6c 69 74 65 3c 2f 62 3e 20 70 72 6f  b>sqlite</b> pro
4710: 67 72 61 6d 20 69 6e 20 74 68 65 0a 66 69 6c 65  gram in the.file
4720: 20 3c 62 3e 73 72 63 2f 73 68 65 6c 6c 2e 63 3c   <b>src/shell.c<
4730: 2f 62 3e 20 6f 66 20 74 68 65 20 73 6f 75 72 63  /b> of the sourc
4740: 65 20 74 72 65 65 2e 0a 41 64 64 69 74 69 6f 6e  e tree..Addition
4750: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  al information a
4760: 62 6f 75 74 20 73 71 6c 69 74 65 20 69 73 20 61  bout sqlite is a
4770: 76 61 69 6c 61 62 6c 65 20 61 74 0a 3c 61 20 68  vailable at.<a h
4780: 72 65 66 3d 22 73 71 6c 69 74 65 2e 68 74 6d 6c  ref="sqlite.html
4790: 22 3e 73 71 6c 69 74 65 2e 68 74 6d 6c 3c 2f 61  ">sqlite.html</a
47a0: 3e 2e 0a 53 65 65 20 61 6c 73 6f 20 74 68 65 20  >..See also the 
47b0: 73 6f 75 72 63 65 73 20 74 6f 20 74 68 65 20 54  sources to the T
47c0: 63 6c 20 69 6e 74 65 72 66 61 63 65 20 66 6f 72  cl interface for
47d0: 20 53 51 4c 69 74 65 20 69 6e 0a 74 68 65 20 73   SQLite in.the s
47e0: 6f 75 72 63 65 20 66 69 6c 65 20 3c 62 3e 73 72  ource file <b>sr
47f0: 63 2f 74 63 6c 73 71 6c 69 74 65 2e 63 3c 2f 62  c/tclsqlite.c</b
4800: 3e 2e 3c 2f 70 3e 0a 7d 0a 0a 70 75 74 73 20 7b  >.</p>.}..puts {
4810: 0a 3c 70 3e 3c 68 72 20 2f 3e 3c 2f 70 3e 0a 3c  .<p><hr /></p>.<
4820: 70 3e 3c 61 20 68 72 65 66 3d 22 69 6e 64 65 78  p><a href="index
4830: 2e 68 74 6d 6c 22 3e 3c 69 6d 67 20 73 72 63 3d  .html"><img src=
4840: 22 2f 67 6f 62 61 63 6b 2e 6a 70 67 22 20 62 6f  "/goback.jpg" bo
4850: 72 64 65 72 3d 30 20 2f 3e 0a 42 61 63 6b 20 74  rder=0 />.Back t
4860: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 48 6f 6d  o the SQLite Hom
4870: 65 20 50 61 67 65 3c 2f 61 3e 0a 3c 2f 70 3e 0a  e Page</a>.</p>.
4880: 0a 3c 2f 62 6f 64 79 3e 3c 2f 68 74 6d 6c 3e 7d  .</body></html>}
4890: 0a                                               .