OpenE2K/gcc
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

extend.texi (Function Attributes): Rewrite visibility attribute documentation.

Browse Source 
* 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:
Geoffrey Keating 2006-04-04 00:28:33 +00:00 committed by Geoffrey Keating
parent 493ae9af1b
commit 46bdbc0012
3 changed files with 88 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
gcc/ChangeLog
View File

@ -4,6 +4,14 @@
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
__builtin_nan is a compile-time constant only when its argument
is valid.

78
gcc/doc/extend.texi
View File

@ -2329,8 +2329,9 @@ inline assembly.
@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")))
@ -2338,40 +2339,75 @@ f () @{ /* @r{Do something.} */; @}
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

30
gcc/doc/invoke.texi
View File

@ -1598,17 +1598,27 @@ if the runtime routine is not available.
@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
@ -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
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}}.