SS8_SPRINTF(3)                   Ssstr Manual                   SS8_SPRINTF(3)



NAME
       ss8_sprintf,     ss8_snprintf,    ss8_cat_sprintf,    ss8_cat_snprintf,
       ss8_vsprintf, ss8_vsnprintf, ss8_cat_vsprintf, ss8_cat_vsnprintf - for‐
       mat an ssstr byte string

SYNOPSIS
       #include <ss8str.h>

       ss8str *ss8_sprintf(ss8str *restrict dest,
                           char const *restrict fmt, ...);
       ss8str *ss8_snprintf(ss8str *restrict dest, size_t maxlen,
                           char const *restrict fmt, ...);

       ss8str *ss8_cat_sprintf(ss8str *restrict dest,
                           char const *restrict fmt, ...);
       ss8str *ss8_cat_snprintf(ss8str *restrict dest,
                           size_t maxlen, char const *restrict fmt,
                           ...);

       ss8str *ss8_vsprintf(ss8str *restrict dest,
                           char const *restrict fmt, va_list args);
       ss8str *ss8_vsnprintf(ss8str *restrict dest, size_t maxlen,
                           char const *restrict fmt, va_list args);

       ss8str *ss8_cat_vsprintf(ss8str *restrict dest,
                           char const *restrict fmt, va_list args);
       ss8str *ss8_cat_vsnprintf(ss8str *restrict dest,
                           size_t maxlen, char const *restrict fmt,
                           va_list args);

DESCRIPTION
       ss8_sprintf()  sets the ss8str at dest to the formatted string produced
       according to the format string fmt  and  the  arguments  following  it.
       String formatting is performed by internally calling vsnprintf(3).

       Behavior  is undefined unless dest points to a valid ss8str object, fmt
       is a null-terminated string, the variable arguments  follow  the  rules
       specified  by  sprintf(3), the contents of fmt and any (wide) string or
       character arguments are valid under the string  encoding  used  by  vs‐
       nprintf(3),  and  the  length of the resulting formatted string is less
       than INT_MAX.

       ss8_snprintf() is like ss8_sprintf(), except that the resulting  string
       is  truncated  at maxlen bytes.  Behavior is undefined unless, in addi‐
       tion to  the  requirements  for  ss8_sprintf(),  maxlen  is  less  than
       INT_MAX.

       ss8_cat_sprintf()  and  ss8_cat_snprintf()  are  like ss8_sprintf() and
       ss8_snprintf(), respectively, except that  rather  than  replacing  the
       string  in  dest,  they append the formatted string to the end of dest.
       The length limit (maxlen or, implicitly for correctness, INT_MAX  -  1)
       applies  to  the  result of formatting, not the whole string after con‐
       catenation.

       ss8_vsprintf(), ss8_vsnprintf(),  ss8_cat_vsprintf(),  and  ss8_cat_vs‐
       nprintf()  are  like  the  corresponding functions without the v in the
       name, except that they take a va_list args instead of the variable  ar‐
       guments.

RETURN VALUE
       All 8 functions return dest.

BUGS
       Calling  these  functions  with any combination of arguments that could
       produce a string longer than INT_MAX - 1 will result in  undefined  be‐
       havior, regardless of the value of maxlen.  This is due to vsnprintf(3)
       returning an int containing the formatted length.

       Callers should avoid passing strings of unbound length for the %s  con‐
       version specifier, and use great care if dynamically generating fmt.

SEE ALSO
       ss8_cat(3), ss8_copy(3), ssstr(7)



SSSTR                             2023-12-30                    SS8_SPRINTF(3)