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
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html><head>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<link href="../sqlite.css" rel="stylesheet">
<title>Formatted String Printing Functions</title>
</head>
<body>
<div class=nosearch>
<a href="../index.html">
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite" border="0">
</a>
<div><!-- IE hack to prevent disappearing logo --></div>
<div class="tagline desktoponly">
Small. Fast. Reliable.<br>Choose any three.
</div>
<div class="menu mainmenu">
<ul>
<li><a href="../index.html">Home</a>
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
<li class='wideonly'><a href='../about.html'>About</a>
<li class='desktoponly'><a href="../docs.html">Documentation</a>
<li class='desktoponly'><a href="../download.html">Download</a>
<li class='wideonly'><a href='../copyright.html'>License</a>
<li class='desktoponly'><a href="../support.html">Support</a>
<li class='desktoponly'><a href="../prosupport.html">Purchase</a>
<li class='search' id='search_menubutton'>
<a href="javascript:void(0)" onclick='toggle_div("searchmenu")'>Search</a>
</ul>
</div>
<div class="menu submenu" id="submenu">
<ul>
<li><a href='../about.html'>About</a>
<li><a href='../docs.html'>Documentation</a>
<li><a href='../download.html'>Download</a>
<li><a href='../support.html'>Support</a>
<li><a href='../prosupport.html'>Purchase</a>
</ul>
</div>
<div class="searchmenu" id="searchmenu">
<form method="GET" action="search">
<span class="desktoponly">Search for:</span> <input type="text" name="q">
<input type="submit" value="Go">
</form>
</div>
</div>
<script>
function toggle_div(nm) {
var w = document.getElementById(nm);
if( w.style.display=="block" ){
w.style.display = "none";
}else{
w.style.display = "block";
}
}
function div_off(nm){document.getElementById(nm).style.display="none";}
window.onbeforeunload = function(e){div_off("submenu");}
/* Disable the Search feature if we are not operating from CGI, since */
/* Search is accomplished using CGI and will not work without it. */
if( !location.origin.match || !location.origin.match(/http/) ){
document.getElementById("search_menubutton").style.display = "none";
}
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */
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>
</div>
<!-- keywords: sqlite3_mprintf sqlite3_snprintf sqlite3_vmprintf sqlite3_vsnprintf -->
<div class=nosearch>
<a href="intro.html"><h2>SQLite C Interface</h2></a>
<h2>Formatted String Printing Functions</h2>
</div>
<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.
These routines understand most of the common K&R formatting options,
plus some additional non-standard formats, detailed below.
Note that some of the more obscure formatting options from recent
C-library standards are omitted from this implementation.</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", "%w" 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 "%w" formatting option is like "%q" except that it expects to
be contained within double-quotes instead of single quotes, and it
escapes the double-quote character instead of the single-quote
character. The "%w" formatting option is intended for safely inserting
table and column names into a constructed SQL statement.</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>
|
