1.Dd December 19, 2018 2.Dt SQLITE3_MPRINTF 3 3.Os 4.Sh NAME 5.Nm sqlite3_mprintf , 6.Nm sqlite3_vmprintf , 7.Nm sqlite3_snprintf , 8.Nm sqlite3_vsnprintf 9.Nd Formatted String Printing Functions 10.Sh SYNOPSIS 11.Ft char * 12.Fo sqlite3_mprintf 13.Fa "const char*" 14.Fa "..." 15.Fc 16.Ft char * 17.Fo sqlite3_vmprintf 18.Fa "const char*" 19.Fa "va_list" 20.Fc 21.Ft char * 22.Fo sqlite3_snprintf 23.Fa "int" 24.Fa "char*" 25.Fa "const char*" 26.Fa "..." 27.Fc 28.Ft char * 29.Fo sqlite3_vsnprintf 30.Fa "int" 31.Fa "char*" 32.Fa "const char*" 33.Fa "va_list" 34.Fc 35.Sh DESCRIPTION 36These routines are work-alikes of the "printf()" family of functions 37from the standard C library. 38These routines understand most of the common formatting options from 39the standard library printf() plus some additional non-standard formats 40(%q, %Q, %w, and %z). 41See the built-in printf() documentation for details. 42.Pp 43The sqlite3_mprintf() and sqlite3_vmprintf() routines write their results 44into memory obtained from sqlite3_malloc64(). 45The strings returned by these two routines should be released by sqlite3_free(). 46Both routines return a NULL pointer if sqlite3_malloc64() 47is unable to allocate enough memory to hold the resulting string. 48.Pp 49The sqlite3_snprintf() routine is similar to "snprintf()" from the 50standard C library. 51The result is written into the buffer supplied as the second parameter 52whose size is given by the first parameter. 53Note that the order of the first two parameters is reversed from snprintf(). 54This is an historical accident that cannot be fixed without breaking 55backwards compatibility. 56Note also that sqlite3_snprintf() returns a pointer to its buffer instead 57of the number of characters actually written into the buffer. 58We admit that the number of characters written would be a more useful 59return value but we cannot change the implementation of sqlite3_snprintf() 60now without breaking compatibility. 61.Pp 62As long as the buffer size is greater than zero, sqlite3_snprintf() 63guarantees that the buffer is always zero-terminated. 64The first parameter "n" is the total size of the buffer, including 65space for the zero terminator. 66So the longest string that can be completely written will be n-1 characters. 67.Pp 68The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf(). 69.Pp 70.Sh SEE ALSO 71.Xr sqlite3_malloc 3 72