I would appreciate any donations. Wishlist or send e-mail type donations to maekawa AT daemon-systems.org.

Thank you.


SQLITE3_MPRINTF(3)         Library Functions Manual         SQLITE3_MPRINTF(3)

NAME
     sqlite3_mprintf, sqlite3_vmprintf, sqlite3_snprintf, sqlite3_vsnprintf -
     Formatted String Printing Functions

SYNOPSIS
     char *
     sqlite3_mprintf(const char*, ...);

     char *
     sqlite3_vmprintf(const char*, va_list);

     char *
     sqlite3_snprintf(int, char*, const char*, ...);

     char *
     sqlite3_vsnprintf(int, char*, const char*, va_list);

DESCRIPTION
     These routines are work-alikes of the "printf()" family of functions from
     the standard C library.  These routines understand most of the common K&R
     formatting options, plus some additional non-standard formats, detailed
     below.  Note that some of the more obscure formatting options from recent
     C-library standards are omitted from this implementation.

     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.

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

     The sqlite3_vsnprintf() routine is a varargs version of
     sqlite3_snprintf().

     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", "%w" and
     "%z" options.

     The %q option works like %s in that it substitutes a nul-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).  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 "%w" formatting option is like "%q" except that it expects to be
     contained within double-quotes instead of single quotes, and it escapes
     the double-quote character instead of the single-quote character.  The
     "%w" formatting option is intended for safely inserting table and column
     names into a constructed SQL statement.

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

SEE ALSO
     sqlite3_malloc(3)

NetBSD 8.0                      March 11, 2017                      NetBSD 8.0