gcc attribute: cleanup

The cleanup attribute runs a function when a variable goes out of scope. This attribute can only be applied to auto function scope variables.

March 26, 2026

gcc attribute

gcc attribute: cleanup


Reqruies

Compiler: gcc 3.3.1 or later

If you look at the systemd project code, you'll see the attribute keyword frequently.

Among them, let's explore the cleanup attribute, which is immensely helpful for preventing resource leaks and writing safe, robust code.

The cleanup attribute is described in the GCC documentation as follows.

cleanup usage


gcc/Common-Variable-Attributes
Doc
The cleanup attribute runs a function when the variable goes out of scope.

This attribute can only be applied to auto function scope variables; it may not be applied to parameters or variables with static storage duration.

The function must take one parameter, a pointer to a type compatible with the variable.
The return value of the function (if any) is ignored.

If -fexceptions is enabled, then cleanup_function is run during the stack unwinding that happens during the processing of the exception.
Note that the cleanup attribute does not allow the exception to be caught, only to perform an action.
It is undefined what happens if cleanup_function does not return normally.
https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html

The following sentence from the documentation explains its most core feature:

The cleanup attribute runs a function when the variable goes out of scope

In other words, by leveraging this attribute, managing resources that must always be paired (like malloc/free or open/close) becomes much easier, preventing resource leaks caused by developer error.


Sample Source Code - usage.c
c


check result
bash

Looking at the assembly code, you can confirm that the code calling auto_function() has been automatically added by GCC.


Assembly - x86_64 AT&T (Usage)
bash

Practical uses of cleanup

Building on these features, we can write code that automatically calls fclose() when a file pointer goes out of scope.

Since the specified function must take a reference (pointer) to the variable's value rather than the variable itself, a wrapper must be defined to accept FILE ** (a pointer to FILE *) as an argument.


Sample Source Code - fclose
c

Timing of cleanup function call

The timing of when the function is called by the cleanup attribute is important.

The documentation states:

The cleanup attribute runs a function when the variable goes out of scope

Let's verify if this description is accurate.


Sample Source Code - scope.c
c


check result
bash

Checking the assembly code reveals that GCC automatically inserts the code to call freep() at the end of the block (scope) where the variable p is declared (just before printf is called).


Assembly - x86_64 AT&T (scope)
bash

Be careful with timing

While the cleanup attribute is powerful, it's crucial to understand its lifecycle characteristic: the function is called immediately the moment the variable leaves its assigned scope.

Neglecting this can lead to coding mistakes like the following:


Sample Source Code - scope_precautions.c
c


check result
bash

In the code above, the developer's original intention was to return the newly allocated memory. However, as soon as the new_buffer function terminates, the local variable p goes out of scope, causing the configured freep() to execute immediately.

As a result, the value pointer later received and used in the main function points to a memory area that has already been freed.

Consequently, attempting to copy a string into it triggers a Use-After-Free error, leading to an abnormal termination with a Segmentation fault as shown above.

Conclusion

The GCC cleanup attribute is an extremely useful feature that automatically calls a specified function to clean up resources when a variable goes out of scope.

It provides an effect similar to the RAII (Resource Acquisition Is Initialization) pattern in C++, serving as a means to safely release resources without omissions, even during complex exception or error handling processes.

In conclusion, if you accurately understand variable scope and resource lifecycles and use them appropriately, you can write structured and safe code in a C environment without being burdened by manual resource management.

PreviousNULL != 0

Nextgcc options: -Wformat