Pragma once

In the C and C++ programming languages, #pragma once is a non-standard but widely supported preprocessor directive designed to cause the current source file to be included only once in a single compilation. Thus, #pragma once serves the same purpose as include guards, but in less code and without the possibility for name clashes.

See the article on include guards for an example of a situation in which one or the other of these methods must be used. The solution using include guards is given on that page; the #pragma once solution would be:

;File "grandfather.h"
#pragma once

struct foo { int member;};;File "father.h"
#include "grandfather.h";File "child.c"
#include "grandfather.h"
#include "father.h"

Advantages and disadvantages

Using #pragma once instead of include guards will typically increase compilation speed since it is a higher-level mechanism; the compiler itself can compare filenames or inodes without having to invoke the C preprocessor to scan the header for #ifndef and #endif.

Some compilers such as GCC include special speedup code to recognize and optimize the handling of include guards, and thus little or no speedup benefit is obtained from the use of #pragma once. [http://gcc.gnu.org/onlinedocs/gcc-2.95.3/cpp_1.html#SEC8]

Again because the compiler itself is responsible for handling #pragma once, it is not necessary for the programmer to create new macro names such as GRANDFATHER_H in the Include guard article's example. This eliminates the risk of name clashes, meaning that no header file can "fail" to be included at least once. It also requires less typing than the include guard method.

However, this high-level handling cuts both ways; the programmer must rely on the compiler to handle #pragma once correctly. If the compiler makes a mistake, for example by failing to recognize that two symbolic links with different names point to the same file, then the compilation will fail. Compilers with #pragma once-related bugs included LCC-Win32 as of 2004 [http://groups.google.com/groups?selm=bvjqhn$q5o$[e-mail]] [http://groups.google.com/groups?selm=[e-mail]] and GCC as of 1998. [http://gcc.gnu.org/onlinedocs/gcc-2.95.3/cpp_1.html#SEC8] GCC originally gave a warning declaring #pragma once "obsolete" when compiling code that used it. However, with the 3.4 release of GCC, the #pragma once handling code was fixed to behave correctly with symbolic and hard links. The feature was "un-deprecated" and the warning removed. [http://gcc.gnu.org/onlinedocs/gcc-4.0.3/cpp/Obsolete-once_002donly-headers.html#Obsolete-once_002donly-headers] [http://gcc.gnu.org/gcc-3.4/changes.html]

You can use both #pragma once and include guards to write portable code that can also take advantage of #pragma once optimizations the compiler may support:

;File "grandfather.h"
#pragma once
#ifndef GRANDFATHER_H
#define GRANDFATHER_H

struct foo { int member;};

#endif /* GRANDFATHER_H */

External links

* [http://msdn2.microsoft.com/en-us/library/d9x1s805(vs.71).aspx "Pragma Directives (C/C++)"] at MSDN
* [http://gcc.gnu.org/onlinedocs/gcc/index.html GCC Pragma and other commands] at [http://gcc.gnu.org/ GNU Org]