1.Dd March 11, 2017 2.Dt SQLITE3_MPRINTF 3 3.Os 4.Sh NAME 5.Nm sqlite3_mprintf , 6.Nm sqlite3_vmprintf , 7.Nm sqlite3_snprintf , 8.Nm sqlite3_vsnprintf 9.Nd Formatted String Printing Functions 10.Sh SYNOPSIS 11.Ft char * 12.Fo sqlite3_mprintf 13.Fa "const char*" 14.Fa "..." 15.Fc 16.Ft char * 17.Fo sqlite3_vmprintf 18.Fa "const char*" 19.Fa "va_list" 20.Fc 21.Ft char * 22.Fo sqlite3_snprintf 23.Fa "int" 24.Fa "char*" 25.Fa "const char*" 26.Fa "..." 27.Fc 28.Ft char * 29.Fo sqlite3_vsnprintf 30.Fa "int" 31.Fa "char*" 32.Fa "const char*" 33.Fa "va_list" 34.Fc 35.Sh DESCRIPTION 36These routines are work-alikes of the "printf()" family of functions 37from the standard C library. 38These routines understand most of the common K&R formatting options, 39plus some additional non-standard formats, detailed below. 40Note that some of the more obscure formatting options from recent C-library 41standards are omitted from this implementation. 42.Pp 43The sqlite3_mprintf() and sqlite3_vmprintf() routines write their results 44into memory obtained from sqlite3_malloc(). 45The strings returned by these two routines should be released by sqlite3_free(). 46Both routines return a NULL pointer if sqlite3_malloc() 47is unable to allocate enough memory to hold the resulting string. 48.Pp 49The sqlite3_snprintf() routine is similar to "snprintf()" from the 50standard C library. 51The result is written into the buffer supplied as the second parameter 52whose size is given by the first parameter. 53Note that the order of the first two parameters is reversed from snprintf(). 54This is an historical accident that cannot be fixed without breaking 55backwards compatibility. 56Note also that sqlite3_snprintf() returns a pointer to its buffer instead 57of the number of characters actually written into the buffer. 58We admit that the number of characters written would be a more useful 59return value but we cannot change the implementation of sqlite3_snprintf() 60now without breaking compatibility. 61.Pp 62As long as the buffer size is greater than zero, sqlite3_snprintf() 63guarantees that the buffer is always zero-terminated. 64The first parameter "n" is the total size of the buffer, including 65space for the zero terminator. 66So the longest string that can be completely written will be n-1 characters. 67.Pp 68The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf(). 69.Pp 70These routines all implement some additional formatting options that 71are useful for constructing SQL statements. 72All of the usual printf() formatting options apply. 73In addition, there is are "%q", "%Q", "%w" and "%z" options. 74.Pp 75The %q option works like %s in that it substitutes a nul-terminated 76string from the argument list. 77But %q also doubles every '\'' character. 78%q is designed for use inside a string literal. 79By doubling each '\'' character it escapes that character and allows 80it to be inserted into the string. 81.Pp 82For example, assume the string variable zText contains text as follows: 83.Bd -ragged 84.Bd -literal 85char *zText = "It's a happy day!"; 86.Ed 87.Pp 88.Ed 89.Pp 90One can use this text in an SQL statement as follows: 91.Bd -ragged 92.Bd -literal 93char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText); 94sqlite3_exec(db, zSQL, 0, 0, 0); sqlite3_free(zSQL); 95.Ed 96.Pp 97.Ed 98.Pp 99Because the %q format string is used, the '\'' character in zText is 100escaped and the SQL generated is as follows: 101.Bd -ragged 102.Bd -literal 103INSERT INTO table1 VALUES('It''s a happy day!') 104.Ed 105.Pp 106.Ed 107.Pp 108This is correct. 109Had we used %s instead of %q, the generated SQL would have looked like 110this: 111.Bd -ragged 112.Bd -literal 113INSERT INTO table1 VALUES('It's a happy day!'); 114.Ed 115.Pp 116.Ed 117.Pp 118This second example is an SQL syntax error. 119As a general rule you should always use %q instead of %s when inserting 120text into a string literal. 121.Pp 122The %Q option works like %q except it also adds single quotes around 123the outside of the total string. 124Additionally, if the parameter in the argument list is a NULL pointer, 125%Q substitutes the text "NULL" (without single quotes). 126So, for example, one could say: 127.Bd -ragged 128.Bd -literal 129char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText); 130sqlite3_exec(db, zSQL, 0, 0, 0); sqlite3_free(zSQL); 131.Ed 132.Pp 133.Ed 134.Pp 135The code above will render a correct SQL statement in the zSQL variable 136even if the zText variable is a NULL pointer. 137.Pp 138The "%w" formatting option is like "%q" except that it expects to be 139contained within double-quotes instead of single quotes, and it escapes 140the double-quote character instead of the single-quote character. 141The "%w" formatting option is intended for safely inserting table and 142column names into a constructed SQL statement. 143.Pp 144The "%z" formatting option works like "%s" but with the addition that 145after the string has been read and copied into the result, sqlite3_free() 146is called on the input string. 147.Sh SEE ALSO 148.Xr sqlite3_malloc 3 149