cpp: Pragmas
1
1 7 Pragmas
1 *********
1
1 The '#pragma' directive is the method specified by the C standard for
1 providing additional information to the compiler, beyond what is
1 conveyed in the language itself. The forms of this directive (commonly
1 known as "pragmas") specified by C standard are prefixed with 'STDC'. A
1 C compiler is free to attach any meaning it likes to other pragmas. All
1 GNU-defined, supported pragmas have been given a 'GCC' prefix.
1
1 C99 introduced the '_Pragma' operator. This feature addresses a
1 major problem with '#pragma': being a directive, it cannot be produced
1 as the result of macro expansion. '_Pragma' is an operator, much like
1 'sizeof' or 'defined', and can be embedded in a macro.
1
1 Its syntax is '_Pragma (STRING-LITERAL)', where STRING-LITERAL can be
1 either a normal or wide-character string literal. It is destringized,
1 by replacing all '\\' with a single '\' and all '\"' with a '"'. The
1 result is then processed as if it had appeared as the right hand side of
1 a '#pragma' directive. For example,
1
1 _Pragma ("GCC dependency \"parse.y\"")
1
1 has the same effect as '#pragma GCC dependency "parse.y"'. The same
1 effect could be achieved using macros, for example
1
1 #define DO_PRAGMA(x) _Pragma (#x)
1 DO_PRAGMA (GCC dependency "parse.y")
1
1 The standard is unclear on where a '_Pragma' operator can appear.
1 The preprocessor does not accept it within a preprocessing conditional
1 directive like '#if'. To be safe, you are probably best keeping it out
1 of directives other than '#define', and putting it on a line of its own.
1
1 This manual documents the pragmas which are meaningful to the
1 preprocessor itself. Other pragmas are meaningful to the C or C++
1 compilers. They are documented in the GCC manual.
1
1 GCC plugins may provide their own pragmas.
1
1 '#pragma GCC dependency'
1 '#pragma GCC dependency' allows you to check the relative dates of
1 the current file and another file. If the other file is more
1 recent than the current file, a warning is issued. This is useful
1 if the current file is derived from the other file, and should be
1 regenerated. The other file is searched for using the normal
1 include search path. Optional trailing text can be used to give
1 more information in the warning message.
1
1 #pragma GCC dependency "parse.y"
1 #pragma GCC dependency "/usr/include/time.h" rerun fixincludes
1
1 '#pragma GCC poison'
1 Sometimes, there is an identifier that you want to remove
1 completely from your program, and make sure that it never creeps
1 back in. To enforce this, you can "poison" the identifier with
1 this pragma. '#pragma GCC poison' is followed by a list of
1 identifiers to poison. If any of those identifiers appears
1 anywhere in the source after the directive, it is a hard error.
1 For example,
1
1 #pragma GCC poison printf sprintf fprintf
1 sprintf(some_string, "hello");
1
1 will produce an error.
1
1 If a poisoned identifier appears as part of the expansion of a
1 macro which was defined before the identifier was poisoned, it will
1 _not_ cause an error. This lets you poison an identifier without
1 worrying about system headers defining macros that use it.
1
1 For example,
1
1 #define strrchr rindex
1 #pragma GCC poison rindex
1 strrchr(some_string, 'h');
1
1 will not produce an error.
1
1 '#pragma GCC system_header'
1 This pragma takes no arguments. It causes the rest of the code in
1 the current file to be treated as if it came from a system header.
1 ⇒System Headers.
1
1 '#pragma GCC warning'
1 '#pragma GCC error'
1 '#pragma GCC warning "message"' causes the preprocessor to issue a
1 warning diagnostic with the text 'message'. The message contained
1 in the pragma must be a single string literal. Similarly, '#pragma
1 GCC error "message"' issues an error message. Unlike the
1 '#warning' and '#error' directives, these pragmas can be embedded
1 in preprocessor macros using '_Pragma'.
1