qdb_mprintf()

Print formatted output to a new string

Synopsis:

#include <qdb/qdb.h>

char * qdb_mprintf( const char* fmt,... );

Arguments:

fmt

A pointer to a formatting string to process. The formatting string determines what additional arguments you need to provide. For more information, see printf() in the Neutrino Library Reference.

Library:

qdb

Description:

This function is a variant of sprintf() from the standard C library. The resulting string is written into memory obtained from malloc(), so there is never a possibility of buffer overflow. This function also implements some additional formatting options that are useful for constructing SQL statements.

---

The qdb_statement() function also allows you to format strings in this way, and doesn't require that you remember to free the resulting string. However, qdb_mprintf() may be useful for building queries from multiple strings.

---

You should call free() to free the strings returned by this function.

All the usual printf() formatting options apply. In addition, there is a %q option. The %q option works like %s: it substitutes a null-terminated string from the argument list. But %q also doubles every \' character (every escaped single quotation). %q is designed for use inside a string literal. By doubling every \' character, it escapes that character and allows it to be inserted into the string.

For example, suppose some string variable contains text as follows:

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

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

      qdb_mprintf(db, "INSERT INTO table VALUES('%q')",
           zText);

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 you 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 that it also adds single quotes around the outside of the total string. Or, 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.

Returns:

An escaped string

Success.

NULL

An error occurred (errno is set).

Classification:

QNX Neutrino

See also:

qdb_snprintf(), qdb_vmprintf(), printf() in the Neutrino Library Reference