gnu::format(3attr)

NAME
gnu::format - specify the style of format string

SYNOPSIS
[[gnu::format(style, fmt-idx, first-idx)]]

DESCRIPTION
This attribute can be applied to a function. It specifies that a function parameter is a format string, and specifies the style of the format string. This allows checking the syntax of the format string, as well as the types of the variadic arguments. The style can be one of the following.

printf
scanf
strftime
strfmon

fmt-idx is a 1-based index that specifies the position of the format string within the parameter list.

first-idx is a 1-based index that specifies the position of the first argument that corresponds to the format string. If the first argument is part of a va_list argument, it should be specified as 0.

VERSIONS

  GNU syntax

__attribute__((format(style, fmt-idx, first-idx)))

  Styles
On some targets, other styles are additionally supported.

MinGW
Microsoft Windows
    ms_printf
    ms_scanf
    ms_strftime

    These correspond to the formats supported by the msvcrt.dll library.

    GCC-only.

Solaris
    cmn_err

Darwin
    CFString

OpenBSD
    kprintf
    syslog
    syslog
        Clang-only.

FreeBSD
    freebsd_kprintf
        Clang-only.

In some languages, other styles are additionally supported.

Objective-C
    NSString

  Non-variadic functions
Clang accepts the attribute on non-variadic functions as an extension.

STANDARDS
GNU.

HISTORY
gcc, g++, clang 2.8, clang++ 2.8.

EXAMPLES
    [[gnu::format(printf, 3, 0)]]
    int
    vstprintf(int size;
        char buf[restrict size], int size,
        const char *restrict fmt, va_list args)
    {
    	int len;

    	if (size == 0) {
    		errno = EOVERFLOW;
    		return -1;
    	}

    	len = vsnprintf(buf, size, fmt, args);
    	if (len >= size) {
    		errno = E2BIG;
    		return -1;
    	}

    	return len;
    }

    [[gnu::format(printf, 3, 4)]]
    int
    stprintf(int size;
        char buf[restrict size], int size,
        const char *restrict fmt, ...)
    {
    	int len;
    	va_list args;

    	va_start(args, fmt);
    	len = vstprintf(buf, size, fmt, args);
    	va_end(args);

    	return len;
    }