lib/c-vsnprintf.h

   1 /* vsnprintf in C locale.
   2    Copyright (C) 2012-2025 Free Software Foundation, Inc.
   3
   4    This file is free software: you can redistribute it and/or modify
   5    it under the terms of the GNU Lesser General Public License as
   6    published by the Free Software Foundation; either version 2.1 of the
   7    License, or (at your option) any later version.
   8
   9    This file is distributed in the hope that it will be useful,
  10    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12    GNU Lesser General Public License for more details.
  13
  14    You should have received a copy of the GNU Lesser General Public License
  15    along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
  16
  17 #ifndef _C_VSNPRINTF_H
  18 #define _C_VSNPRINTF_H
  19
  20 /* This file uses _GL_ATTRIBUTE_FORMAT.  */
  21 #if !_GL_CONFIG_H_INCLUDED
  22  #error "Please include config.h first."
  23 #endif
  24
  25 /* Get size_t, ptrdiff_t.  */
  26 #include <stddef.h>
  27
  28 /* Get va_list. */
  29 #include <stdarg.h>
  30
  31 /* Get _GL_ATTRIBUTE_SPEC_PRINTF_STANDARD.  */
  32 #include <stdio.h>
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 /* Prints formatted output to string STR.  Similar to vsprintf, but the
  39    additional parameter SIZE limits how much is written into STR.
  40    STR may be NULL, in which case nothing will be written.
  41    Returns the string length of the formatted string (which may be larger
  42    than SIZE).  Upon failure, returns -1 with errno set.
  43
  44    Failure code EOVERFLOW can only occur when a width > INT_MAX is used.
  45    Therefore, if the format string is valid and does not use %ls/%lc
  46    directives nor widths, the only possible failure code is ENOMEM.
  47
  48    Formatting takes place in the C locale, that is, the decimal point
  49    used in floating-point formatting directives is always '.'. */
  50 extern ptrdiff_t c_vsnzprintf (char *restrict str, size_t size,
  51                                const char *format, va_list args)
  52        _GL_ATTRIBUTE_FORMAT ((_GL_ATTRIBUTE_SPEC_PRINTF_STANDARD, 3, 0));
  53
  54 /* Prints formatted output to string STR.  Similar to sprintf, but the
  55    additional parameter SIZE limits how much is written into STR.
  56    STR may be NULL, in which case nothing will be written.
  57    Returns the string length of the formatted string (which may be larger
  58    than SIZE).  Upon failure, returns -1 with errno set.
  59
  60    Formatting takes place in the C locale, that is, the decimal point
  61    used in floating-point formatting directives is always '.'. */
  62 extern int c_vsnprintf (char *restrict str, size_t size,
  63                         const char *format, va_list args)
  64        _GL_ATTRIBUTE_FORMAT ((_GL_ATTRIBUTE_SPEC_PRINTF_STANDARD, 3, 0));
  65
  66 #ifdef __cplusplus
  67 }
  68 #endif
  69
  70 #endif /* _C_VSNPRINTF_H */