1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html><head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Formatted String Printing Functions</title>
<style type="text/css">
body {
margin: auto;
font-family: Verdana, sans-serif;
padding: 8px 1%;
}
a { color: #044a64 }
a:visited { color: #734559 }
.logo { position:absolute; margin:3px; }
.tagline {
float:right;
text-align:right;
font-style:italic;
width:300px;
margin:12px;
margin-top:58px;
}
.menubar {
clear: both;
border-radius: 8px;
background: #044a64;
padding: 0px;
margin: 0px;
cell-spacing: 0px;
}
.toolbar {
text-align: center;
line-height: 1.6em;
margin: 0;
padding: 0px 8px;
}
.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }
.toolbar a:visited { color: white; }
.toolbar a:hover { color: #044a64; background: white; }
.content { margin: 5%; }
.content dt { font-weight:bold; }
.content dd { margin-bottom: 25px; margin-left:20%; }
.content ul { padding:0px; padding-left: 15px; margin:0px; }
/* Things for "fancyformat" documents start here. */
.fancy img+p {font-style:italic}
.fancy .codeblock i { color: darkblue; }
.fancy h1,.fancy h2,.fancy h3,.fancy h4 {font-weight:normal;color:#044a64}
.fancy h2 { margin-left: 10px }
.fancy h3 { margin-left: 20px }
.fancy h4 { margin-left: 30px }
.fancy th {white-space:nowrap;text-align:left;border-bottom:solid 1px #444}
.fancy th, .fancy td {padding: 0.2em 1ex; vertical-align:top}
.fancy #toc a { color: darkblue ; text-decoration: none }
.fancy .todo { color: #AA3333 ; font-style : italic }
.fancy .todo:before { content: 'TODO:' }
.fancy p.todo { border: solid #AA3333 1px; padding: 1ex }
.fancy img { display:block; }
.fancy :link:hover, .fancy :visited:hover { background: wheat }
.fancy p,.fancy ul,.fancy ol { margin: 1em 5ex }
.fancy li p { margin: 1em 0 }
/* End of "fancyformat" specific rules. */
</style>
</head>
<body>
<div><!-- container div to satisfy validator -->
<a href="../index.html">
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite Logo"
border="0"></a>
<div><!-- IE hack to prevent disappearing logo--></div>
<div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div>
<table width=100% class="menubar"><tr>
<td width=100%>
<div class="toolbar">
<a href="../about.html">About</a>
<a href="../sitemap.html">Sitemap</a>
<a href="../docs.html">Documentation</a>
<a href="../download.html">Download</a>
<a href="../copyright.html">License</a>
<a href="../news.html">News</a>
<a href="../support.html">Support</a>
</div>
<script>
gMsg = "Search SQLite Docs..."
function entersearch() {
var q = document.getElementById("q");
if( q.value == gMsg ) { q.value = "" }
q.style.color = "black"
q.style.fontStyle = "normal"
}
function leavesearch() {
var q = document.getElementById("q");
if( q.value == "" ) {
q.value = gMsg
q.style.color = "#044a64"
q.style.fontStyle = "italic"
}
}
function hideorshow(btn,obj){
var x = document.getElementById(obj);
var b = document.getElementById(btn);
if( x.style.display!='none' ){
x.style.display = 'none';
b.innerHTML='show';
}else{
x.style.display = '';
b.innerHTML='hide';
}
return false;
}
</script>
<td>
<div style="padding:0 1em 0px 0;white-space:nowrap">
<form name=f method="GET" action="http://www.sqlite.org/search">
<input id=q name=q type=text
onfocus="entersearch()" onblur="leavesearch()" style="width:24ex;padding:1px 1ex; border:solid white 1px; font-size:0.9em ; font-style:italic;color:#044a64;" value="Search SQLite Docs...">
<input type=submit value="Go" style="border:solid white 1px;background-color:#044a64;color:white;font-size:0.9em;padding:0 1ex">
</form>
</div>
</table>
<div class=startsearch></div>
<a href="intro.html"><h2>SQLite C Interface</h2></a><h2>Formatted String Printing Functions</h2><blockquote><pre>char *sqlite3_mprintf(const char*,...);
char *sqlite3_vmprintf(const char*, va_list);
char *sqlite3_snprintf(int,char*,const char*, ...);
char *sqlite3_vsnprintf(int,char*,const char*, va_list);
</pre></blockquote><p>
These routines are work-alikes of the "printf()" family of functions
from the standard C library.</p>
<p>The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
results into memory obtained from <a href="../c3ref/free.html">sqlite3_malloc()</a>.
The strings returned by these two routines should be
released by <a href="../c3ref/free.html">sqlite3_free()</a>. Both routines return a
NULL pointer if <a href="../c3ref/free.html">sqlite3_malloc()</a> is unable to allocate enough
memory to hold the resulting string.</p>
<p>The sqlite3_snprintf() routine is similar to "snprintf()" from
the standard C library. The result is written into the
buffer supplied as the second parameter whose size is given by
the first parameter. Note that the order of the
first two parameters is reversed from snprintf(). This is an
historical accident that cannot be fixed without breaking
backwards compatibility. Note also that sqlite3_snprintf()
returns a pointer to its buffer instead of the number of
characters actually written into the buffer. We admit that
the number of characters written would be a more useful return
value but we cannot change the implementation of sqlite3_snprintf()
now without breaking compatibility.</p>
<p>As long as the buffer size is greater than zero, sqlite3_snprintf()
guarantees that the buffer is always zero-terminated. The first
parameter "n" is the total size of the buffer, including space for
the zero terminator. So the longest string that can be completely
written will be n-1 characters.</p>
<p>The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().</p>
<p>These routines all implement some additional formatting
options that are useful for constructing SQL statements.
All of the usual printf() formatting options apply. In addition, there
is are "%q", "%Q", and "%z" options.</p>
<p>The %q option works like %s in that it substitutes a nul-terminated
string from the argument list. But %q also doubles every '\'' character.
%q is designed for use inside a string literal. By doubling each '\''
character it escapes that character and allows it to be inserted into
the string.</p>
<p>For example, assume the string variable zText contains text as follows:</p>
<p><blockquote><pre>
char *zText = "It's a happy day!";
</pre></blockquote></p>
<p>One can use this text in an SQL statement as follows:</p>
<p><blockquote><pre>
char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
sqlite3_exec(db, zSQL, 0, 0, 0);
sqlite3_free(zSQL);
</pre></blockquote></p>
<p>Because the %q format string is used, the '\'' character in zText
is escaped and the SQL generated is as follows:</p>
<p><blockquote><pre>
INSERT INTO table1 VALUES('It''s a happy day!')
</pre></blockquote></p>
<p>This is correct. Had we used %s instead of %q, the generated SQL
would have looked like this:</p>
<p><blockquote><pre>
INSERT INTO table1 VALUES('It's a happy day!');
</pre></blockquote></p>
<p>This second example is an SQL syntax error. As a general rule you should
always use %q instead of %s when inserting text into a string literal.</p>
<p>The %Q option works like %q except it also adds single quotes around
the outside of the total string. Additionally, if the parameter in the
argument list is a NULL pointer, %Q substitutes the text "NULL" (without
single quotes). So, for example, one could say:</p>
<p><blockquote><pre>
char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
sqlite3_exec(db, zSQL, 0, 0, 0);
sqlite3_free(zSQL);
</pre></blockquote></p>
<p>The code above will render a correct SQL statement in the zSQL
variable even if the zText variable is a NULL pointer.</p>
<p>The "%z" formatting option works like "%s" but with the
addition that after the string has been read and copied into
the result, <a href="../c3ref/free.html">sqlite3_free()</a> is called on the input string.
</p><p>See also lists of
<a href="objlist.html">Objects</a>,
<a href="constlist.html">Constants</a>, and
<a href="funclist.html">Functions</a>.</p>
|
