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)