snprintf()

Write formatted output to a character array, up to a given maximum number of characters

Synopsis:

#include <stdio.h>

int snprintf( char* buf,
              size_t count,
              const char* format,
              ... );

Arguments:

buf

A pointer to the buffer where you want to function to store the formatted string.

count

The maximum number of characters to store in the buffer, including a terminating null character.

format

A string that specifies the format of the output. The formatting string determines what additional arguments you need to provide. For more information, see printf().

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The snprintf() function is similar to fprintf(), except that snprintf() places the generated output (up to the specified maximum number of characters) into the character array pointed to by buf, instead of writing it to a file. The snprintf() function is similar to sprintf(), but with boundary checking. A null character is placed at the end of the generated character string.

Returns:

The number of characters that would have been written into the array, not counting the terminating null character, had count been large enough. It does this even if count is zero; in this case buf can be NULL.

If an error occurred, snprintf() returns a negative value and sets errno.

Examples:

#include <stdio.h>
#include <stdlib.h>

/* Create temporary file names using a counter */

char namebuf[13];
int  TempCount = 0;

char *make_temp_name( void )
{
    snprintf( namebuf, 13, "ZZ%.6o.TMP", 
              TempCount++ );
    return( namebuf );
}

int main( void )
{
    FILE *tf1, *tf2;

    tf1 = fopen( make_temp_name(), "w" );
    tf2 = fopen( make_temp_name(), "w" );
    fputs( "temp file 1", tf1 );
    fputs( "temp file 2", tf2 );
    fclose( tf1 );
    fclose( tf2 );

    return EXIT_SUCCESS;
}

Classification:

ANSI, POSIX 1003.1

Caveats:

It's safe to call this function in a signal handler if the data isn't floating point.

Be careful if you're using snprintf() to build a string one piece at a time. For example, this code:

len += snprintf(&buf[len], RECSIZE - 1 - len, ...);

could have a problem if snprintf() truncates the string. Without a separate test to compare len with RECSIZE, this code doesn't protect against a buffer overflow. After the call that truncates the output, len is larger than RECSIZE, and RECSIZE - 1 - len is a very large (unsigned) number; the next call generates unlimited output somewhere beyond the buffer.

See also:

errno, fprintf(), fwprintf(), printf(), sprintf(), swprintf(), vfprintf(), vfwprintf(), vprintf(), vsnprintf(), vsprintf(), vswprintf(), vwprintf(), wprintf()