@item visibility ("@var{visibility_type}")
@cindex @code{visibility} attribute
-The @code{visibility} attribute on ELF targets causes the declaration
-to be emitted with default, hidden, protected or internal visibility.
+This attribute affects the linkage of the declaration to which it is attached.
+There are four supported @var{visibility_type} values: default,
+hidden, protected or internal visibility.
@smallexample
void __attribute__ ((visibility ("protected")))
int i __attribute__ ((visibility ("hidden")));
@end smallexample
-See the ELF gABI for complete details, but the short story is:
+The possible values of @var{visibility_type} correspond to the
+visibility settings in the ELF gABI.
@table @dfn
@c keep this list of visibilities in alphabetical order.
@item default
-Default visibility is the normal case for ELF@. This value is
-available for the visibility attribute to override other options
-that may change the assumed visibility of symbols.
+Default visibility is the normal case for the object file format.
+This value is available for the visibility attribute to override other
+options that may change the assumed visibility of entities.
+
+On ELF, default visibility means that the declaration is visible to other
+modules and, in shared libraries, means that the declared entity may be
+overridden.
+
+On Darwin, default visibility means that the declaration is visible to
+other modules.
+
+Default visibility corresponds to ``external linkage'' in the language.
@item hidden
-Hidden visibility indicates that the symbol will not be placed into
-the dynamic symbol table, so no other @dfn{module} (executable or
-shared library) can reference it directly.
+Hidden visibility indicates that the entity declared will have a new
+form of linkage, which we'll call ``hidden linkage''. Two
+declarations of an object with hidden linkage refer to the same object
+if they are in the same shared object.
@item internal
Internal visibility is like hidden visibility, but with additional
-processor specific semantics. Unless otherwise specified by the psABI,
-GCC defines internal visibility to mean that the function is @emph{never}
-called from another module. Note that hidden symbols, while they cannot
-be referenced directly by other modules, can be referenced indirectly via
-function pointers. By indicating that a symbol cannot be called from
-outside the module, GCC may for instance omit the load of a PIC register
-since it is known that the calling function loaded the correct value.
+processor specific semantics. Unless otherwise specified by the
+psABI, GCC defines internal visibility to mean that a function is
+@emph{never} called from another module. Compare this with hidden
+functions which, while they cannot be referenced directly by other
+modules, can be referenced indirectly via function pointers. By
+indicating that a function cannot be called from outside the module,
+GCC may for instance omit the load of a PIC register since it is known
+that the calling function loaded the correct value.
@item protected
-Protected visibility indicates that the symbol will be placed in the
-dynamic symbol table, but that references within the defining module
-will bind to the local symbol. That is, the symbol cannot be overridden
-by another module.
+Protected visibility is like default visibility except that it
+indicates that references within the defining module will bind to the
+definition in that module. That is, the declared entity cannot be
+overridden by another module.
@end table
-Not all ELF targets support this attribute.
+All visibilities are supported on many, but not all, ELF targets
+(supported when the assembler supports the @samp{.visibility}
+pseudo-op). Default visibility is supported everywhere. Hidden
+visibility is supported on Darwin targets.
+
+The visibility attribute should be applied only to declarations which
+would otherwise have external linkage. The attribute should be applied
+consistently, so that the same entity should not be declared with
+different settings of the attribute.
+
+In C++, the visibility attribute applies to types as well as functions
+and objects, because in C++ types have linkage. There are some bugs
+in the C++ support for this flag, for example a template which has a
+hidden type as a parameter is not properly hidden.
+@c bugzilla 26612
+
+In C++, you can mark member functions and static member variables of a
+class with the visibility attribute. This is useful if if you know a
+particular method or static member variable should only be used from
+one shared object; then you can mark it hidden while the rest of the
+class has default visibility. Care must be taken to avoid breaking
+the One Definition Rule; for example, it is not useful to mark a
+method which is defined inside a class definition as hidden without
+marking the whole class as hidden.
@item warn_unused_result
@cindex @code{warn_unused_result} attribute
@item -fvisibility-inlines-hidden
@opindex fvisibility-inlines-hidden
-Causes all inlined methods to be marked with
+This switch declares that the user does not attempt to compare
+pointers to inline methods where the addresses of the two functions
+were taken in different shared objects.
+
+The effect of this is that GCC may, effectively, mark inline methods with
@code{__attribute__ ((visibility ("hidden")))} so that they do not
appear in the export table of a DSO and do not require a PLT indirection
when used within the DSO@. Enabling this option can have a dramatic effect
on load and link times of a DSO as it massively reduces the size of the
-dynamic export table when the library makes heavy use of templates. While
-it can cause bloating through duplication of code within each DSO where
-it is used, often the wastage is less than the considerable space occupied
-by a long symbol name in the export table which is typical when using
-templates and namespaces. For even more savings, combine with the
-@option{-fvisibility=hidden} switch.
+dynamic export table when the library makes heavy use of templates.
+
+The behaviour of this switch is not quite the same as marking the
+methods as hidden directly. Normally if there is a class with default
+visibility which has a hidden method, the effect of this is that the
+method must be defined in only one shared object. This switch does
+not have this restriction.
+
+You may mark a method as having a visibility explicitly to negate the
+effect of the switch for that method. For example, if you do want to
+compare pointers to a particular inline method, you might mark it as
+having default visibility.
@item -fno-weak
@opindex fno-weak
Note that due to ISO C++ specification requirements, operator new and
operator delete must always be of default visibility.
+Be aware that headers from outside your project, in particular system
+headers and headers from any other library you use, may not be
+expecting to be compiled with visibility other than the default. You
+may need to explicitly say @samp{#pragma GCC visibility push(default)}
+before including any such headers.
+
An overview of these techniques, their benefits and how to use them
is at @w{@uref{http://gcc.gnu.org/wiki/Visibility}}.
OSDN Git Service
