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