1 /*
2 ** 2001 September 22
3 **
4 ** The author disclaims copyright to this source code.  In place of
5 ** a legal notice, here is a blessing:
6 **
7 **    May you do good and not evil.
8 **    May you find forgiveness for yourself and forgive others.
9 **    May you share freely, never taking more than you give.
10 **
11 *************************************************************************
12 */
13 #ifndef SWITCH_MPRINTF_H
14 #define SWITCH_MPRINTF_H
15 
16 SWITCH_BEGIN_EXTERN_C
17 /**
18  * This routine is a variant of the "sprintf()" from the
19  * standard C library.  The resulting string is written into memory
20  * obtained from malloc() so that there is never a possiblity of buffer
21  * overflow.  This routine also implement some additional formatting
22  * options that are useful for constructing SQL statements.
23  *
24  * The strings returned by this routine should be freed by calling
25  * free().
26  *
27  * All of the usual printf formatting options apply.  In addition, there
28  * is a "%q" option.  %q works like %s in that it substitutes a null-terminated
29  * string from the argument list.  But %q also doubles every '\'' character.
30  * %q is designed for use inside a string literal.  By doubling each '\''
31  * character it escapes that character and allows it to be inserted into
32  * the string.
33  *
34  * For example, so some string variable contains text as follows:
35  *
36  *      char *zText = "It's a happy day!";
37  *
38  * We can use this text in an SQL statement as follows:
39  *
40  *      char *z = switch_mprintf("INSERT INTO TABLES('%q')", zText);
41  *      switch_core_db_exec(db, z, callback1, 0, 0);
42  *      free(z);
43  *
44  * Because the %q format string is used, the '\'' character in zText
45  * is escaped and the SQL generated is as follows:
46  *
47  *      INSERT INTO table1 VALUES('It''s a happy day!')
48  *
49  * This is correct.  Had we used %s instead of %q, the generated SQL
50  * would have looked like this:
51  *
52  *      INSERT INTO table1 VALUES('It's a happy day!');
53  *
54  * This second example is an SQL syntax error.  As a general rule you
55  * should always use %q instead of %s when inserting text into a string
56  * literal.
57  */
58 SWITCH_DECLARE(char *) switch_mprintf(const char *zFormat, ...);
59 SWITCH_DECLARE(char *) switch_vmprintf(const char *zFormat, va_list ap);
60 SWITCH_DECLARE(char *) switch_snprintfv(char *zBuf, int n, const char *zFormat, ...);
61 
62 SWITCH_END_EXTERN_C
63 #endif /* SWITCH_MPRINTF_H */
64