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.

Note: 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 are %q, %Q and %z options.

The %q option works like %s: it substitutes a null-terminated string from the argument list; however, %q also doubles each single quote character ('). %q is designed for use inside a string literal. By doubling each single quote character, %q escapes that character and allows it to be inserted into the string.

The %Q option works like %q except that it also adds single quotes around the contents of the entire string. Or, if the parameter in the argument list is a NULL pointer, %Q substitutes the text "NULL" (without double quotes) in place of the %Q option.

The %z option works like %s except that after the source string (the argument referred to by %s) has been copied into the formatted string, the source string memory doesn't have to be freed.

Returns:

A pointer to an escaped string: Success.
NULL: An error occurred (errno is set).

Examples:

Suppose some string variable contains the following text:

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

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

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

Because the %q format string is used, the single quote character in zText is escaped, and the SQL generated is:

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.

Suppose you're unsure if your text reference is NULL. You can use this reference as follows:

char *zSQL = qdb_mprintf(
                "INSERT INTO table VALUES(%Q)",
                zText);

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

The %z option is handy for nested strings:

char id[] = "12345678";
char *nested = qdb_mprintf(
            "SELECT msid FROM mediastores \
                    WHERE id = %Q", id);
char *sql = qdb_mprintf(
            "DELETE FROM library \
                    WHERE msid = (%z);", nested);
qdb_exec(sql);
free(sql);

The nested string doesn't have to be freed after it gets copied into the formatted string and that SQL statement within that formatted string is executed.

Classification:

QNX Neutrino

Safety:
Interrupt handler	No
Signal handler	No
Thread	Yes