gcc/doc/gcc/extensions-to-the-c-language-family/declaring-attributes-of-functions/microsoft-windows-function-attributes.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 .. _microsoft-windows-function-attributes:
   7
   8 Microsoft Windows Function Attributes
   9 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  10
  11 The following attributes are available on Microsoft Windows and Symbian OS
  12 targets.
  13
  14 .. index:: dllexport function attribute, __declspec(dllexport)
  15
  16 .. microsoft-windows-fn-attr:: dllexport
  17
  18   On Microsoft Windows targets and Symbian OS targets the
  19   :microsoft-windows-fn-attr:`dllexport` attribute causes the compiler to provide a global
  20   pointer to a pointer in a DLL, so that it can be referenced with the
  21   :microsoft-windows-fn-attr:`dllimport` attribute.  On Microsoft Windows targets, the pointer
  22   name is formed by combining ``_imp__`` and the function or variable
  23   name.
  24
  25   You can use ``__declspec(dllexport)`` as a synonym for
  26   ``__attribute__ ((dllexport))`` for compatibility with other
  27   compilers.
  28
  29   On systems that support the :microsoft-windows-fn-attr:`visibility` attribute, this
  30   attribute also implies 'default' visibility.  It is an error to
  31   explicitly specify any other visibility.
  32
  33   GCC's default behavior is to emit all inline functions with the
  34   :microsoft-windows-fn-attr:`dllexport` attribute.  Since this can cause object file-size bloat,
  35   you can use :option:`-fno-keep-inline-dllexport`, which tells GCC to
  36   ignore the attribute for inlined functions unless the
  37   :option:`-fkeep-inline-functions` flag is used instead.
  38
  39   The attribute is ignored for undefined symbols.
  40
  41   When applied to C++ classes, the attribute marks defined non-inlined
  42   member functions and static data members as exports.  Static consts
  43   initialized in-class are not marked unless they are also defined
  44   out-of-class.
  45
  46   For Microsoft Windows targets there are alternative methods for
  47   including the symbol in the DLL's export table such as using a
  48   :samp:`.def` file with an ``EXPORTS`` section or, with GNU ld, using
  49   the :option:`--export-all` linker flag.
  50
  51 .. index:: dllimport function attribute, __declspec(dllimport)
  52
  53 .. microsoft-windows-fn-attr:: dllimport
  54
  55   On Microsoft Windows and Symbian OS targets, the :microsoft-windows-fn-attr:`dllimport`
  56   attribute causes the compiler to reference a function or variable via
  57   a global pointer to a pointer that is set up by the DLL exporting the
  58   symbol.  The attribute implies ``extern``.  On Microsoft Windows
  59   targets, the pointer name is formed by combining ``_imp__`` and the
  60   function or variable name.
  61
  62   You can use ``__declspec(dllimport)`` as a synonym for
  63   ``__attribute__ ((dllimport))`` for compatibility with other
  64   compilers.
  65
  66   On systems that support the :microsoft-windows-fn-attr:`visibility` attribute, this
  67   attribute also implies 'default' visibility.  It is an error to
  68   explicitly specify any other visibility.
  69
  70   Currently, the attribute is ignored for inlined functions.  If the
  71   attribute is applied to a symbol *definition*, an error is reported.
  72   If a symbol previously declared :microsoft-windows-fn-attr:`dllimport` is later defined, the
  73   attribute is ignored in subsequent references, and a warning is emitted.
  74   The attribute is also overridden by a subsequent declaration as
  75   :microsoft-windows-fn-attr:`dllexport`.
  76
  77   When applied to C++ classes, the attribute marks non-inlined
  78   member functions and static data members as imports.  However, the
  79   attribute is ignored for virtual methods to allow creation of vtables
  80   using thunks.
  81
  82   On the SH Symbian OS target the :microsoft-windows-fn-attr:`dllimport` attribute also has
  83   another affect---it can cause the vtable and run-time type information
  84   for a class to be exported.  This happens when the class has a
  85   dllimported constructor or a non-inline, non-pure virtual function
  86   and, for either of those two conditions, the class also has an inline
  87   constructor or destructor and has a key function that is defined in
  88   the current translation unit.
  89
  90   For Microsoft Windows targets the use of the :microsoft-windows-fn-attr:`dllimport`
  91   attribute on functions is not necessary, but provides a small
  92   performance benefit by eliminating a thunk in the DLL.  The use of the
  93   :microsoft-windows-fn-attr:`dllimport` attribute on imported variables can be avoided by passing the
  94   :option:`--enable-auto-import` switch to the GNU linker.  As with
  95   functions, using the attribute for a variable eliminates a thunk in
  96   the DLL.
  97
  98   One drawback to using this attribute is that a pointer to a
  99   *variable* marked as :microsoft-windows-fn-attr:`dllimport` cannot be used as a constant
 100   address. However, a pointer to a *function* with the
 101   :microsoft-windows-fn-attr:`dllimport` attribute can be used as a constant initializer; in
 102   this case, the address of a stub function in the import lib is
 103   referenced.  On Microsoft Windows targets, the attribute can be disabled
 104   for functions by setting the :option:`-mnop-fun-dllimport` flag.