Small. Fast. Reliable.
Choose any three.

About Sitemap Documentation Download License News Developers Support

## SQLite C Interface

## Formatted String Printing Functions

>     char *sqlite3_mprintf(const char*,...);
>     char *sqlite3_vmprintf(const char*, va_list);
>     char *sqlite3_snprintf(int,char*,const char*, ...);

These routines are workalikes of the "printf()" family of functions from the standard C library.

The sqlite3_mprintf() and sqlite3_vmprintf() routines write their results into memory obtained from sqlite3_malloc(). The strings returned by these two routines should be released by sqlite3_free(). Both routines return a NULL pointer if sqlite3_malloc() is unable to allocate enough memory to hold the resulting string.

In 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.

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.

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.

The %q option works like %s in that it substitutes a null-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.

For example, assume the string variable zText contains text as follows:

>     char *zText = "It's a happy day!";

One can use this text in an SQL statement as follows:

>     char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
>     sqlite3_exec(db, zSQL, 0, 0, 0);
>     sqlite3_free(zSQL);

Because the %q format string is used, the '\'' character in zText is escaped and the SQL generated is as follows:

>     INSERT INTO table1 VALUES('It''s a happy day!')

This is correct. Had we used %s instead of %q, the generated SQL would have looked like this:

>     INSERT INTO table1 VALUES('It's a happy day!');

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.

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) in place of the %Q option. So, for example, one could say:

>     char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
>     sqlite3_exec(db, zSQL, 0, 0, 0);
>     sqlite3_free(zSQL);

The code above will render a correct SQL statement in the zSQL variable even if the zText variable is a NULL pointer.

The "%z" formatting option works exactly like "%s" with the addition that after the string has been read and copied into the result, sqlite3_free() is called on the input string.

### Invariants:

H17403 | The sqlite3_mprintf() and sqlite3_vmprintf() interfaces return either pointers to zero-terminated UTF-8 strings held in memory obtained from sqlite3_malloc() or NULL pointers if a call to sqlite3_malloc() fails.
H17406 | The sqlite3_snprintf() interface writes a zero-terminated UTF-8 string into the buffer pointed to by the second parameter provided that the first parameter is greater than zero.
H17407 | The sqlite3_snprintf() interface does not write slots of its output buffer (the second parameter) outside the range of 0 through N-1 (where N is the first parameter) regardless of the length of the string requested by the format specification.

See also lists of Objects, Constants, and Functions.

This page last modified 2008/08/11 17:57:43 UTC