SAS/C Library Reference, Vol. 1

vsnprintf -- Write a Limited Portion of Formatted Output to a String

SYNOPSIS

 #include <stdarg.h>
 #include <lcio.h>

 int vsnprintf(char *dest, size_t maxlen, const char *format,
               va_list arg);

DESCRIPTION

The vsnprintf function is equivalent to the snprintf function, except that arg replaces the variable-argument list. arg must have been initialized by the va_start macro and possibly va_arg calls. The vsnprintf function does not invoke the va_end macro. See va_arg, va_end, and va_start for details on varying-length argument-list functions. The vsnprintf function writes formatted output to the area addressed by dest under control of the string addressed by format until either all format conversion specifications have been satisfied or until maxlen characters have been written. If the maxlen limit is reached

a terminating-null character is not added
the number of characters placed in the output area will be the value of maxlen
the remainder of the format string is ignored
The vsnprintf function returns a negative value whose magnitude is equal to the value of maxlen.

In all other respects, vsnprintf behaves identically to vsprintf. The string pointed to by format is in the same form as that used by fprintf. Refer to the fprintf function description for detailed information concerning the format conversions.

RETURN VALUE

The vsnprintf function returns an integer value that equals in magnitude the number of characters written to the area addressed by dest. If the value returned is negative, then either the maxlen character limit was reached or some other error, such as an invalid format specification, has occurred. The one exception to this is if an error occurs before any characters are stored, vsnprintf returns INT_MIN (-2**31).

CAUTION

If the maxlen value is 0, no characters are written, and vsnprintf returns 0. If the value is greater than INT_MAX, then vsnprintf behaves identically to vsprintf in that no limit checking is done on the number of characters written to the output area. No warnings concerning length errors are produced by vsnprintf, and the only indication that the output may have been truncated or is incomplete is a negative return value.

IMPLEMENTATION

When invoked with a limit greater than 512 characters, the vsnprintf function calls malloc to obtain a temporary spill buffer equal in size to the limit specified. If insufficient storage is available, vsnprintf attempts to process the format specifications with an internal 512-byte spill buffer. In this case, individual conversion specifiers that produce more than 512 characters may fail, and vsnprintf processing can terminate prematurely.

EXAMPLE

  #include <stdlib.h>
  #include <lcio.h>
  #include <stdarg.h>

  static void format_msg(char *, size_t, char *, ...);

  #define NOTE 0
  #define WARNING 1
  #define MESSAGE_LEN 80

  static const char *msgs[] = {
    "Msgno%04d  This is message number zero",
    "Msgno%04d  This message requires a %s"
  };

  main()
  {
     char msgbuf(|84|);

     format_msg(msgbuf, MESSAGE_LEN, msgs[NOTE], NOTE);
     printf("The formatted message is: "%s" n", msgbuf);
     format_msg(msgbuf, MESSAGE_LEN, msg[WARNING], WARNING,
                "a replacement string");
     printf("The formatted message is: "%s" n", msgbuf);
     return;
  }

  static void format_msg(char *buf, size_t limit, char *format,...)
  {
     va_list args;
     va_start(args, format),
     vsnprintf(buf, limit, format, args);
     va_end(args);
  }

RELATED FUNCTIONS

snprintf, va_start, vsprintf