gcc/doc/cpp/header-files/system-headers.rst

   1 ..
   2   Copyright 1988-2022 Free Software Foundation, Inc.
   3   This is part of the GCC manual.
   4   For copying conditions, see the copyright.rst file.
   5
   6 .. index:: system header files
   7
   8 .. _system-headers:
   9
  10 System Headers
  11 **************
  12
  13 The header files declaring interfaces to the operating system and
  14 runtime libraries often cannot be written in strictly conforming C.
  15 Therefore, GCC gives code found in :dfn:`system headers` special
  16 treatment.  All warnings, other than those generated by :samp:`#warning`
  17 (see :ref:`diagnostics`), are suppressed while GCC is processing a system
  18 header.  Macros defined in a system header are immune to a few warnings
  19 wherever they are expanded.  This immunity is granted on an ad-hoc
  20 basis, when we find that a warning generates lots of false positives
  21 because of code in macros defined in system headers.
  22
  23 Normally, only the headers found in specific directories are considered
  24 system headers.  These directories are determined when GCC is compiled.
  25 There are, however, two ways to make normal headers into system headers:
  26
  27 * Header files found in directories added to the search path with the
  28   :option:`-isystem` and :option:`-idirafter` command-line options are
  29   treated as system headers for the purposes of diagnostics.
  30
  31 *
  32   .. index:: #pragma GCC system_header
  33
  34   There is also a directive, ``#pragma GCC system_header``, which
  35   tells GCC to consider the rest of the current include file a system
  36   header, no matter where it was found.  Code that comes before the
  37   :samp:`#pragma` in the file is not affected.  ``#pragma GCC
  38   system_header`` has no effect in the primary source file.
  39
  40 On some targets, such as RS/6000 AIX, GCC implicitly surrounds all
  41 system headers with an :samp:`extern "C"` block when compiling as C++.