1.Dd January 24, 2024 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.In sqlite3.h 12.Ft char * 13.Fo sqlite3_mprintf 14.Fa "const char*" 15.Fa "..." 16.Fc 17.Ft char * 18.Fo sqlite3_vmprintf 19.Fa "const char*" 20.Fa "va_list" 21.Fc 22.Ft char * 23.Fo sqlite3_snprintf 24.Fa "int" 25.Fa "char*" 26.Fa "const char*" 27.Fa "..." 28.Fc 29.Ft char * 30.Fo sqlite3_vsnprintf 31.Fa "int" 32.Fa "char*" 33.Fa "const char*" 34.Fa "va_list" 35.Fc 36.Sh DESCRIPTION 37These routines are work-alikes of the "printf()" family of functions 38from the standard C library. 39These routines understand most of the common formatting options from 40the standard library printf() plus some additional non-standard formats 41(%q, %Q, %w, and %z). 42See the 43.Fn built-in printf 44documentation for details. 45.Pp 46The sqlite3_mprintf() and sqlite3_vmprintf() routines write their results 47into memory obtained from 48.Fn sqlite3_malloc64 . 49The strings returned by these two routines should be released by 50.Fn sqlite3_free . 51Both routines return a NULL pointer if 52.Fn sqlite3_malloc64 53is unable to allocate enough memory to hold the resulting string. 54.Pp 55The sqlite3_snprintf() routine is similar to "snprintf()" from the 56standard C library. 57The result is written into the buffer supplied as the second parameter 58whose size is given by the first parameter. 59Note that the order of the first two parameters is reversed from snprintf(). 60This is an historical accident that cannot be fixed without breaking 61backwards compatibility. 62Note also that sqlite3_snprintf() returns a pointer to its buffer instead 63of the number of characters actually written into the buffer. 64We admit that the number of characters written would be a more useful 65return value but we cannot change the implementation of sqlite3_snprintf() 66now without breaking compatibility. 67.Pp 68As long as the buffer size is greater than zero, sqlite3_snprintf() 69guarantees that the buffer is always zero-terminated. 70The first parameter "n" is the total size of the buffer, including 71space for the zero terminator. 72So the longest string that can be completely written will be n-1 characters. 73.Pp 74The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf(). 75.Pp 76.Sh IMPLEMENTATION NOTES 77These declarations were extracted from the 78interface documentation at line 2948. 79.Bd -literal 80SQLITE_API char *sqlite3_mprintf(const char*,...); 81SQLITE_API char *sqlite3_vmprintf(const char*, va_list); 82SQLITE_API char *sqlite3_snprintf(int,char*,const char*, ...); 83SQLITE_API char *sqlite3_vsnprintf(int,char*,const char*, va_list); 84.Ed 85.Sh SEE ALSO 86.Xr sqlite3_malloc 3 87