1.Dd $Mdocdate$ 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. 38.Pp 39The sqlite3_mprintf() and sqlite3_vmprintf() routines write their results 40into memory obtained from sqlite3_malloc(). 41The strings returned by these two routines should be released by sqlite3_free(). 42Both routines return a NULL pointer if sqlite3_malloc() 43is unable to allocate enough memory to hold the resulting string. 44.Pp 45The sqlite3_snprintf() routine is similar to "snprintf()" from the 46standard C library. 47The result is written into the buffer supplied as the second parameter 48whose size is given by the first parameter. 49Note that the order of the first two parameters is reversed from snprintf(). 50This is an historical accident that cannot be fixed without breaking 51backwards compatibility. 52Note also that sqlite3_snprintf() returns a pointer to its buffer instead 53of the number of characters actually written into the buffer. 54We admit that the number of characters written would be a more useful 55return value but we cannot change the implementation of sqlite3_snprintf() 56now without breaking compatibility. 57.Pp 58As long as the buffer size is greater than zero, sqlite3_snprintf() 59guarantees that the buffer is always zero-terminated. 60The first parameter "n" is the total size of the buffer, including 61space for the zero terminator. 62So the longest string that can be completely written will be n-1 characters. 63.Pp 64The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf(). 65.Pp 66These routines all implement some additional formatting options that 67are useful for constructing SQL statements. 68All of the usual printf() formatting options apply. 69In addition, there is are "%q", "%Q", and "%z" options. 70.Pp 71The %q option works like %s in that it substitutes a nul-terminated 72string from the argument list. 73But %q also doubles every '\'' character. 74%q is designed for use inside a string literal. 75By doubling each '\'' character it escapes that character and allows 76it to be inserted into the string. 77.Pp 78For example, assume the string variable zText contains text as follows: 79.Bd -ragged 80.Bd -literal 81char *zText = "It's a happy day!"; 82.Ed 83.Pp 84.Ed 85.Pp 86One can use this text in an SQL statement as follows: 87.Bd -ragged 88.Bd -literal 89char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText); 90sqlite3_exec(db, zSQL, 0, 0, 0); sqlite3_free(zSQL); 91.Ed 92.Pp 93.Ed 94.Pp 95Because the %q format string is used, the '\'' character in zText is 96escaped and the SQL generated is as follows: 97.Bd -ragged 98.Bd -literal 99INSERT INTO table1 VALUES('It''s a happy day!') 100.Ed 101.Pp 102.Ed 103.Pp 104This is correct. 105Had we used %s instead of %q, the generated SQL would have looked like 106this: 107.Bd -ragged 108.Bd -literal 109INSERT INTO table1 VALUES('It's a happy day!'); 110.Ed 111.Pp 112.Ed 113.Pp 114This second example is an SQL syntax error. 115As a general rule you should always use %q instead of %s when inserting 116text into a string literal. 117.Pp 118The %Q option works like %q except it also adds single quotes around 119the outside of the total string. 120Additionally, if the parameter in the argument list is a NULL pointer, 121%Q substitutes the text "NULL" (without single quotes). 122So, for example, one could say: 123.Bd -ragged 124.Bd -literal 125char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText); 126sqlite3_exec(db, zSQL, 0, 0, 0); sqlite3_free(zSQL); 127.Ed 128.Pp 129.Ed 130.Pp 131The code above will render a correct SQL statement in the zSQL variable 132even if the zText variable is a NULL pointer. 133.Pp 134The "%z" formatting option works like "%s" but with the addition that 135after the string has been read and copied into the result, sqlite3_free() 136is called on the input string. 137.Sh SEE ALSO 138.Xr sqlite3_malloc 3 139