gcc attribute: format, format_arg

The format attribute specifies that a function takes printf, scanf, strftime or strfmon style arguments which should be type-checked against a format string.

April 8, 2026

gcc attribute

gcc attribute: format, format_arg


Reqruies

Compiler: gcc 2.8.0 later

Prior knowledge

Using the GCC compiler option -Wformat provides a significant advantage: it allows us to detect potential mistakes, such as argument mismatches, at compile-time when calling functions that handle variable arguments like printf or scanf.

But what if we could apply the type-checking capabilities of the -Wformat option to our own custom functions?

For example, suppose we wrote the following code:


sample source code - format
c


Compile with -Wformat
bash

The code above successfully compiles without any warnings, even though the number of format specifiers in the format string passed to the report function does not match the number of variable arguments.

How can we apply the -Wformat inspection feature to our custom report() function to prevent such mistakes?

format attribute

If you look closely at the GCC documentation, you can find an attribute called format.


format (archetype, string-index, first-to-check)
Doc
The format attribute specifies that a function takes printf, scanf, strftime or strfmon style arguments which should be type-checked against a format string.
https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html

To summarize briefly, by using this attribute, we can apply -Wformat compile-time checks to any custom function we define.

usage

Now, let's modify the previous example code by adding the attribute format so that issues can be detected at compile-time.


sample source code - format.c
c

If we try compiling again, the following warning will be generated:


Compile with -Wformat
bash

The issue in our custom report function was successfully detected by the -Wformat option.

The usage is quite simple.

archetype: You can specify functions like printf, scanf, strftime, etc. Depending on the target, you might also use glibc's gnu_* or MinGW's ms_*.
string-index: Specifies the position of the format string parameter that the compiler uses as a baseline when inspecting the syntax. Note that the index starts at 1, not 0.
first-to-check: Specifies the position of the first variable argument to be checked for type and count according to the format string.

variable argument list

For functions like vprintf that take a va_list instead of a variable argument list (...), the compiler cannot directly check the types or count of the received variable arguments. In such cases, if you set first-to-check to 0, the compiler will handle it appropriately.


sample source code - format_vprintf.c
c


Compile with -Wformat
bash

In this case, the compiler only checks for structural errors within the format string itself.
In other words, since it cannot directly access the count or types of the variable arguments passed, it cannot detect situations where the number of format specifiers and variable arguments mismatch, as shown below:


-Wformat-extra-args is not detected
c

strftime is also used in the same way by setting first-to-check to 0.


sample source code - strftime.c
c


Compile with -Wformat
bash

function declaration

You can also specify the attribute in function declarations as follows:

This attribute is quite old and was already included in the GCC 2.8.0 release.
At that time, it only supported two archetypes: printf and scanf.


gcc 2.8.0 release - c-common.c
c

Support for strftime was added in GCC 2.95.

format_arg

While examining GCC-related source files or documentation, you might also frequently encounter the format_arg attribute.
This attribute is assigned to functions that process a format string and return a new format string.

For example, it is useful when writing a function that prepends a specific prefix to the original format string or returns a translated format string.


sample source code - format_arg.c
c


Compile with -Wformat
bash

conclusion

Personally, I think -Wformat is an extremely useful and powerful option because it allows us to catch format string-related bugs—which can lead to critical runtime errors (e.g., memory reference errors, segmentation faults)—early during the compilation stage.

Therefore, when writing code, it is highly recommended to use -Werror=format to escalate format-related warnings into compilation errors whenever possible.

However, it is easy to forget to assign these attributes when defining custom functions. To prevent this, GCC also provides the -Wmissing-format-attribute option.

In conclusion, when designing a function that takes a format string as an argument, I strongly recommend actively applying the format attribute to minimize developer errors and improve software stability.

Nextgcc builtin: choose_expr