From 46bdbc0012b7ac304f1810c23611d8c6f1f81186 Mon Sep 17 00:00:00 2001 From: Geoffrey Keating Date: Tue, 4 Apr 2006 00:28:33 +0000 Subject: 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 --- gcc/ChangeLog | 8 ++++++ gcc/doc/extend.texi | 78 ++++++++++++++++++++++++++++++++++++++--------------- gcc/doc/invoke.texi | 30 ++++++++++++++++----- 3 files changed, 88 insertions(+), 28 deletions(-) (limited to 'gcc') diff --git a/gcc/ChangeLog b/gcc/ChangeLog index 7f38918..79b0ee5 100644 --- a/gcc/ChangeLog +++ b/gcc/ChangeLog @@ -4,6 +4,14 @@ 2006-04-03 Geoffrey Keating + * 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. diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index ae3a7f2..a72fb7f 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -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 diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index 97885ef..ede037b 100644 --- a/gcc/doc/invoke.texi +++ b/gcc/doc/invoke.texi @@ -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}}. -- cgit v1.1