mirror of git://gcc.gnu.org/git/gcc.git
extend.texi (Function Attributes): Rewrite visibility attribute documentation.
* doc/extend.texi (Function Attributes): Rewrite visibility attribute documentation. * doc/invoke.texi (C++ Dialect Options): Rewrite -fvisibility-inlines-hidden documentation to describe something entirely different, although in practise compatible. (Code Gen Options): Warn about system headers in -fvisibiltity= documentation. From-SVN: r112653
This commit is contained in:
parent
493ae9af1b
commit
46bdbc0012
|
@ -4,6 +4,14 @@
|
||||||
|
|
||||||
2006-04-03 Geoffrey Keating <geoffk@apple.com>
|
2006-04-03 Geoffrey Keating <geoffk@apple.com>
|
||||||
|
|
||||||
|
* doc/extend.texi (Function Attributes): Rewrite visibility
|
||||||
|
attribute documentation.
|
||||||
|
* doc/invoke.texi (C++ Dialect Options): Rewrite
|
||||||
|
-fvisibility-inlines-hidden documentation to describe something
|
||||||
|
entirely different, although in practise compatible.
|
||||||
|
(Code Gen Options): Warn about system headers in -fvisibiltity=
|
||||||
|
documentation.
|
||||||
|
|
||||||
* doc/extend.texi (Other Builtins): Document that
|
* doc/extend.texi (Other Builtins): Document that
|
||||||
__builtin_nan is a compile-time constant only when its argument
|
__builtin_nan is a compile-time constant only when its argument
|
||||||
is valid.
|
is valid.
|
||||||
|
|
|
@ -2329,8 +2329,9 @@ inline assembly.
|
||||||
|
|
||||||
@item visibility ("@var{visibility_type}")
|
@item visibility ("@var{visibility_type}")
|
||||||
@cindex @code{visibility} attribute
|
@cindex @code{visibility} attribute
|
||||||
The @code{visibility} attribute on ELF targets causes the declaration
|
This attribute affects the linkage of the declaration to which it is attached.
|
||||||
to be emitted with default, hidden, protected or internal visibility.
|
There are four supported @var{visibility_type} values: default,
|
||||||
|
hidden, protected or internal visibility.
|
||||||
|
|
||||||
@smallexample
|
@smallexample
|
||||||
void __attribute__ ((visibility ("protected")))
|
void __attribute__ ((visibility ("protected")))
|
||||||
|
@ -2338,40 +2339,75 @@ f () @{ /* @r{Do something.} */; @}
|
||||||
int i __attribute__ ((visibility ("hidden")));
|
int i __attribute__ ((visibility ("hidden")));
|
||||||
@end smallexample
|
@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
|
@table @dfn
|
||||||
@c keep this list of visibilities in alphabetical order.
|
@c keep this list of visibilities in alphabetical order.
|
||||||
|
|
||||||
@item default
|
@item default
|
||||||
Default visibility is the normal case for ELF@. This value is
|
Default visibility is the normal case for the object file format.
|
||||||
available for the visibility attribute to override other options
|
This value is available for the visibility attribute to override other
|
||||||
that may change the assumed visibility of symbols.
|
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
|
@item hidden
|
||||||
Hidden visibility indicates that the symbol will not be placed into
|
Hidden visibility indicates that the entity declared will have a new
|
||||||
the dynamic symbol table, so no other @dfn{module} (executable or
|
form of linkage, which we'll call ``hidden linkage''. Two
|
||||||
shared library) can reference it directly.
|
declarations of an object with hidden linkage refer to the same object
|
||||||
|
if they are in the same shared object.
|
||||||
|
|
||||||
@item internal
|
@item internal
|
||||||
Internal visibility is like hidden visibility, but with additional
|
Internal visibility is like hidden visibility, but with additional
|
||||||
processor specific semantics. Unless otherwise specified by the psABI,
|
processor specific semantics. Unless otherwise specified by the
|
||||||
GCC defines internal visibility to mean that the function is @emph{never}
|
psABI, GCC defines internal visibility to mean that a function is
|
||||||
called from another module. Note that hidden symbols, while they cannot
|
@emph{never} called from another module. Compare this with hidden
|
||||||
be referenced directly by other modules, can be referenced indirectly via
|
functions which, while they cannot be referenced directly by other
|
||||||
function pointers. By indicating that a symbol cannot be called from
|
modules, can be referenced indirectly via function pointers. By
|
||||||
outside the module, GCC may for instance omit the load of a PIC register
|
indicating that a function cannot be called from outside the module,
|
||||||
since it is known that the calling function loaded the correct value.
|
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
|
@item protected
|
||||||
Protected visibility indicates that the symbol will be placed in the
|
Protected visibility is like default visibility except that it
|
||||||
dynamic symbol table, but that references within the defining module
|
indicates that references within the defining module will bind to the
|
||||||
will bind to the local symbol. That is, the symbol cannot be overridden
|
definition in that module. That is, the declared entity cannot be
|
||||||
by another module.
|
overridden by another module.
|
||||||
|
|
||||||
@end table
|
@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
|
@item warn_unused_result
|
||||||
@cindex @code{warn_unused_result} attribute
|
@cindex @code{warn_unused_result} attribute
|
||||||
|
|
|
@ -1598,17 +1598,27 @@ if the runtime routine is not available.
|
||||||
|
|
||||||
@item -fvisibility-inlines-hidden
|
@item -fvisibility-inlines-hidden
|
||||||
@opindex 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
|
@code{__attribute__ ((visibility ("hidden")))} so that they do not
|
||||||
appear in the export table of a DSO and do not require a PLT indirection
|
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
|
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
|
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
|
dynamic export table when the library makes heavy use of templates.
|
||||||
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
|
The behaviour of this switch is not quite the same as marking the
|
||||||
by a long symbol name in the export table which is typical when using
|
methods as hidden directly. Normally if there is a class with default
|
||||||
templates and namespaces. For even more savings, combine with the
|
visibility which has a hidden method, the effect of this is that the
|
||||||
@option{-fvisibility=hidden} switch.
|
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
|
@item -fno-weak
|
||||||
@opindex fno-weak
|
@opindex fno-weak
|
||||||
|
@ -13448,6 +13458,12 @@ abundantly clear also aids readability and self-documentation of the code.
|
||||||
Note that due to ISO C++ specification requirements, operator new and
|
Note that due to ISO C++ specification requirements, operator new and
|
||||||
operator delete must always be of default visibility.
|
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
|
An overview of these techniques, their benefits and how to use them
|
||||||
is at @w{@uref{http://gcc.gnu.org/wiki/Visibility}}.
|
is at @w{@uref{http://gcc.gnu.org/wiki/Visibility}}.
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue