From bd52db0b952d35ce793153e4a0c0b25f102a4395 Mon Sep 17 00:00:00 2001 From: Greg Ercolano Date: Fri, 19 Mar 2021 09:22:01 -0700 Subject: Added docs for public fl_vsnprintf() (STR #3413) Applied vsnprintf_v2.patch from STR#3413 which documents the previously undocumented function, so that it shows up here in the doxygen docs: Files -> File List -> vsnprintf.c -> fl_vsnprintf() This commit does not solve STR #3413, just adds the recommended documentation for fl_vsnprintf(). Other functions in src/vsnprintf.c could use docs too. See the bottom of comment #5 in the STR for recommendations to fully solve. --- src/vsnprintf.c | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) (limited to 'src') diff --git a/src/vsnprintf.c b/src/vsnprintf.c index 08aed7fc7..606e515c1 100644 --- a/src/vsnprintf.c +++ b/src/vsnprintf.c @@ -25,6 +25,39 @@ extern "C" { #endif +/** + \file vsnprintf.c + \brief Portable vsnprintf() implementation. +*/ + +/** + FLTK's platform independent wrapper for the vsnprintf() C library function. + + This function guarantees: + + - access to vsnprintf(), even on systems that don't have it (FLTK's own + built-in code is used) + + - Guarantees NUL termination. Even if string expands larger than the buffer, + a terminating NUL is included, unlike some implementations of vsnprintf(), + notably Microsoft Visual Studio (pre-2015), which can leave the string + unterminated when truncated. + + If the build environment for FLTK has vsnprintf(), fl_vsnprintf() + is just a wrapper around the compiler's provided function. Otherwise, + if the function is NOT available, FLTK's own built-in version is provided. + + The FLTK built in provides these style options: + + - %[ -+#'] + - * -- padding width + - .* -- precision width + - Data types: h, l, ll, L + - Floating point formats: E, G, e, f, g + - Integer formats: B, X, b, d, i, o, u, x + - Pointer format: p + - String/char: c, s, n +*/ int fl_vsnprintf(char* buffer, size_t bufsize, const char* format, va_list ap) { #if defined(HAVE_VSNPRINTF) && defined(__linux__) return vsnprintf(buffer, bufsize, format, ap); -- cgit v1.2.3