diff options
Diffstat (limited to 'gcc/doc/extend.texi')
| -rw-r--r-- | gcc/doc/extend.texi | 267 |
1 files changed, 184 insertions, 83 deletions
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index 32fabae5ccf..16ca3cedd9e 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -427,7 +427,6 @@ extensions, accepted by GCC in C89 mode and in C++. * Labels as Values:: Getting pointers to labels, and computed gotos. * Nested Functions:: As in Algol and Pascal, lexical scoping of functions. * Constructing Calls:: Dispatching a call to another function. -* Naming Types:: Giving a name to the type of some expression. * Typeof:: @code{typeof}: referring to the type of an expression. * Lvalues:: Using @samp{?:}, @samp{,} and casts in lvalues. * Conditionals:: Omitting the middle operand of a @samp{?:} expression. @@ -538,8 +537,7 @@ the value of an enumeration constant, the width of a bit-field, or the initial value of a static variable. If you don't know the type of the operand, you can still do this, but you -must use @code{typeof} (@pxref{Typeof}) or type naming (@pxref{Naming -Types}). +must use @code{typeof} (@pxref{Typeof}). Statement expressions are not supported fully in G++, and their fate there is unclear. (It is possible that they will become fully supported @@ -782,7 +780,7 @@ GCC implements taking the address of a nested function using a technique called @dfn{trampolines}. A paper describing them is available as @noindent -@uref{http://people.debian.org/~karlheg/Usenix88-lexic.pdf}. +@uref{http://people.debian.org/~aaronl/Usenix88-lexic.pdf}. A nested function can jump to a label inherited from a containing function, provided the label was explicitly declared in the containing @@ -888,29 +886,6 @@ the containing function. You should specify, for @var{result}, a value returned by @code{__builtin_apply}. @end deftypefn -@node Naming Types -@section Naming an Expression's Type -@cindex naming types - -You can give a name to the type of an expression using a @code{typedef} -declaration with an initializer. Here is how to define @var{name} as a -type name for the type of @var{exp}: - -@example -typedef @var{name} = @var{exp}; -@end example - -This is useful in conjunction with the statements-within-expressions -feature. Here is how the two together can be used to define a safe -``maximum'' macro that operates on any arithmetic type: - -@example -#define max(a,b) \ - (@{typedef _ta = (a), _tb = (b); \ - _ta _a = (a); _tb _b = (b); \ - _a > _b ? _a : _b; @}) -@end example - @cindex underscores in variables in macros @cindex @samp{_} in variables in macros @cindex local variables in macros @@ -962,6 +937,21 @@ A @code{typeof}-construct can be used anywhere a typedef name could be used. For example, you can use it in a declaration, in a cast, or inside of @code{sizeof} or @code{typeof}. +@code{typeof} is often useful in conjunction with the +statements-within-expressions feature. Here is how the two together can +be used to define a safe ``maximum'' macro that operates on any +arithmetic type and evaluates each of its arguments exactly once: + +@example +#define max(a,b) \ + (@{ typeof (a) _a = (a); \ + typeof (b) _b = (b); \ + _a > _b ? _a : _b; @}) +@end example + +@noindent +Some more examples of the use of @code{typeof}: + @itemize @bullet @item This declares @code{y} with the type of what @code{x} points to. @@ -1011,6 +1001,26 @@ Thus, @code{array (pointer (char), 4)} is the type of arrays of 4 pointers to @code{char}. @end itemize +@emph{Compatibility Note:} In addition to @code{typeof}, GCC 2 supported +a more limited extension which permitted one to write + +@example +typedef @var{T} = @var{expr}; +@end example + +@noindent +with the effect of declaring @var{T} to have the type of the expression +@var{expr}. This extension does not work with GCC 3 (versions between +3.0 and 3.2 will crash; 3.2.1 and later give an error). Code which +relies on it should be rewritten to use @code{typeof}: + +@example +typedef typeof(@var{expr}) @var{T}; +@end example + +@noindent +This will work with all versions of GCC@. + @node Lvalues @section Generalized Lvalues @cindex compound expressions as lvalues @@ -1445,9 +1455,9 @@ variable number of arguments much as a function can. The syntax for defining the macro is similar to that of a function. Here is an example: -@example +@smallexample #define debug(format, ...) fprintf (stderr, format, __VA_ARGS__) -@end example +@end smallexample Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of such a macro, it represents the zero or more tokens until the closing @@ -1486,9 +1496,9 @@ string. To help solve this problem, CPP behaves specially for variable arguments used with the token paste operator, @samp{##}. If instead you write -@example +@smallexample #define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__) -@end example +@end smallexample and if the variable arguments are omitted or empty, the @samp{##} operator causes the preprocessor to remove the comma before it. If you @@ -1798,9 +1808,9 @@ nested subobject to initialize; the list is taken relative to the subobject corresponding to the closest surrounding brace pair. For example, with the @samp{struct point} declaration above: -@example +@smallexample struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @}; -@end example +@end smallexample @noindent If the same field is initialized multiple times, it will have value from @@ -2332,6 +2342,15 @@ since it is known that the calling function loaded the correct value. Not all ELF targets support this attribute. +@item tls_model ("@var{tls_model}") +@cindex @code{tls_model} attribute +The @code{tls_model} attribute sets thread-local storage model +(@pxref{Thread-Local}) of a particular @code{__thread} variable, +overriding @code{-ftls-model=} command line switch on a per-variable +basis. +The @var{tls_model} argument should be one of @code{global-dynamic}, +@code{local-dynamic}, @code{initial-exec} or @code{local-exec}. + @item regparm (@var{number}) @cindex functions that are passed arguments in registers on the 386 On the Intel 386, the @code{regparm} attribute causes the compiler to @@ -3235,7 +3254,7 @@ typedef int more_aligned_int __attribute__ ((aligned (8))); @noindent force the compiler to insure (as far as it can) that each variable whose type is @code{struct S} or @code{more_aligned_int} will be allocated and -aligned @emph{at least} on a 8-byte boundary. On a Sparc, having all +aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all variables of type @code{struct S} aligned to 8-byte boundaries allows the compiler to use the @code{ldd} and @code{std} (doubleword load and store) instructions when copying one variable of type @code{struct S} to @@ -3420,7 +3439,7 @@ any other type of objects, just like the @code{char} type. See Example of use: -@example +@smallexample typedef short __attribute__((__may_alias__)) short_a; int @@ -3436,7 +3455,7 @@ main (void) exit(0); @} -@end example +@end smallexample If you replaced @code{short_a} with @code{short} in the variable declaration, the above program would abort when compiled with @@ -3700,7 +3719,10 @@ asm volatile ("movc3 %0,%1,%2" You may not write a clobber description in a way that overlaps with an input or output operand. For example, you may not have an operand describing a register class with one member if you mention that register -in the clobber list. There is no way for you to specify that an input +in the clobber list. Variables declared to live in specific registers +(@pxref{Explicit Reg Vars}), and used as asm input or output operands must +have no part mentioned in the clobber description. +There is no way for you to specify that an input operand is modified without also specifying it as an output operand. Note that if all the output operands you specify are for this purpose (and hence unused), you will then also need to specify @@ -4140,7 +4162,7 @@ being used for other purposes in the preceding functions. Global register variables may not have initial values, because an executable file has no means to supply initial contents for a register. -On the Sparc, there are reports that g3 @dots{} g7 are suitable +On the SPARC, there are reports that g3 @dots{} g7 are suitable registers, but certain library functions, such as @code{getwd}, as well as the subroutines for division and remainder, modify g3 and g4. g1 and g2 are local temporaries. @@ -4421,9 +4443,6 @@ A floating point value, as wide as a SI mode integer, usually 32 bits. A floating point value, as wide as a DI mode integer, usually 64 bits. @end table -There are no @code{V1xx} vector modes - they would be identical to the -corresponding base mode. - Specifying a combination that is not valid for the current architecture will cause gcc to synthesize the instructions using a narrower mode. For example, if you specify a variable of type @code{V4SI} and your @@ -4549,6 +4568,21 @@ v4si f (v4si a, v4si b, v4si c) @findex strrchr @findex strspn @findex strstr +@findex floor +@findex floorf +@findex floorl +@findex ceil +@findex ceilf +@findex ceill +@findex round +@findex roundf +@findex roundl +@findex trunc +@findex truncf +@findex truncl +@findex nearbyint +@findex nearbyintf +@findex nearbyintl GCC provides a large number of built-in functions other than the ones mentioned above. Some of these are for internal use in the processing @@ -4584,28 +4618,29 @@ built-in functions. All these functions have corresponding versions prefixed with @code{__builtin_}, which may be used even in strict C89 mode. -The ISO C99 functions @code{conj}, @code{conjf}, @code{conjl}, -@code{creal}, @code{crealf}, @code{creall}, @code{cimag}, @code{cimagf}, -@code{cimagl}, @code{llabs} and @code{imaxabs} are handled as built-in -functions except in strict ISO C90 mode. There are also built-in -versions of the ISO C99 functions @code{cosf}, @code{cosl}, -@code{expf}, @code{expl}, @code{fabsf}, @code{fabsl}, -@code{logf}, @code{logl}, @code{sinf}, @code{sinl}, @code{sqrtf}, and -@code{sqrtl}, that are recognized in any mode since ISO C90 reserves -these names for the purpose to which ISO C99 puts them. All these -functions have corresponding versions prefixed with @code{__builtin_}. +The ISO C99 functions @code{conj}, @code{conjf}, @code{conjl}, @code{creal}, +@code{crealf}, @code{creall}, @code{cimag}, @code{cimagf}, @code{cimagl}, +@code{llabs}, @code{imaxabs}, @code{round}, @code{trunc}, @code{nearbyint}, +@code{roundf}, @code{truncf}, @code{nearbyintf}, @code{roundl}, @code{truncl} and +@code{nearbyintl} are handled as built-in functions except in strict ISO C90 mode. +There are also built-in versions of the ISO C99 functions @code{cosf}, +@code{cosl}, @code{expf}, @code{expl}, @code{fabsf}, @code{fabsl}, @code{logf}, +@code{logl}, @code{sinf}, @code{sinl}, @code{sqrtf}, @code{sqrtl}, +@code{ceilf}, @code{ceill}, @code{floorf} and @code{floorl} that are recognized +in any mode since ISO C90 reserves these names for the purpose to which ISO C99 +puts them. All these functions have corresponding versions prefixed with +@code{__builtin_}. The ISO C90 functions @code{abs}, @code{cos}, @code{exp}, @code{fabs}, -@code{fprintf}, @code{fputs}, @code{labs}, @code{log}, -@code{memcmp}, @code{memcpy}, -@code{memset}, @code{printf}, @code{sin}, @code{sqrt}, @code{strcat}, -@code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn}, -@code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy}, -@code{strpbrk}, @code{strrchr}, @code{strspn}, and @code{strstr} are all -recognized as built-in functions unless @option{-fno-builtin} is -specified (or @option{-fno-builtin-@var{function}} is specified for an -individual function). All of these functions have corresponding -versions prefixed with @code{__builtin_}. +@code{fprintf}, @code{fputs}, @code{labs}, @code{log}, @code{floor}, +@code{ceil} @code{memcmp}, @code{memcpy}, @code{memset}, @code{printf}, +@code{sin}, @code{sqrt}, @code{strcat}, @code{strchr}, @code{strcmp}, +@code{strcpy}, @code{strcspn}, @code{strlen}, @code{strncat}, @code{strncmp}, +@code{strncpy}, @code{strpbrk}, @code{strrchr}, @code{strspn}, and +@code{strstr} are all recognized as built-in functions unless +@option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}} is +specified for an individual function). All of these functions have +corresponding versions prefixed with @code{__builtin_}. GCC provides built-in versions of the ISO C99 floating point comparison macros that avoid raising exceptions for unordered operands. They have @@ -4688,13 +4723,15 @@ as @var{exp2}. Example: @smallexample -#define foo(x) \ - __builtin_choose_expr (__builtin_types_compatible_p (typeof (x), double), \ - foo_double (x), \ - __builtin_choose_expr (__builtin_types_compatible_p (typeof (x), float), \ - foo_float (x), \ - /* @r{The void expression results in a compile-time error} \ - @r{when assigning the result to something.} */ \ +#define foo(x) \ + __builtin_choose_expr ( \ + __builtin_types_compatible_p (typeof (x), double), \ + foo_double (x), \ + __builtin_choose_expr ( \ + __builtin_types_compatible_p (typeof (x), float), \ + foo_float (x), \ + /* @r{The void expression results in a compile-time error} \ + @r{when assigning the result to something.} */ \ (void)0)) @end smallexample @@ -4831,6 +4868,74 @@ is evaluated if it includes side effects but no other code is generated and GCC does not issue a warning. @end deftypefn +@deftypefn {Built-in Function} double __builtin_huge_val (void) +Returns a positive infinity, if supported by the floating-point format, +else @code{DBL_MAX}. This function is suitable for implementing the +ISO C macro @code{HUGE_VAL}. +@end deftypefn + +@deftypefn {Built-in Function} float __builtin_huge_valf (void) +Similar to @code{__builtin_huge_val}, except the return type is @code{float}. +@end deftypefn + +@deftypefn {Built-in Function} long double __builtin_huge_vall (void) +Similar to @code{__builtin_huge_val}, except the return +type is @code{long double}. +@end deftypefn + +@deftypefn {Built-in Function} double __builtin_inf (void) +Similar to @code{__builtin_huge_val}, except a warning is generated +if the target floating-point format does not support infinities. +This function is suitable for implementing the ISO C99 macro @code{INFINITY}. +@end deftypefn + +@deftypefn {Built-in Function} float __builtin_inff (void) +Similar to @code{__builtin_inf}, except the return type is @code{float}. +@end deftypefn + +@deftypefn {Built-in Function} long double __builtin_infl (void) +Similar to @code{__builtin_inf}, except the return +type is @code{long double}. +@end deftypefn + +@deftypefn {Built-in Function} double __builtin_nan (const char *str) +This is an implementation of the ISO C99 function @code{nan}. + +Since ISO C99 defines this function in terms of @code{strtod}, which we +do not implement, a desription of the parsing is in order. The string +is parsed as by @code{strtol}; that is, the base is recognized by +leading @samp{0} or @samp{0x} prefixes. The number parsed is placed +in the significand such that the least significant bit of the number +is at the least significant bit of the significand. The number is +truncated to fit the significand field provided. The significand is +forced to be a quiet NaN. + +This function, if given a string literal, is evaluated early enough +that it is considered a compile-time constant. +@end deftypefn + +@deftypefn {Built-in Function} float __builtin_nanf (const char *str) +Similar to @code{__builtin_nan}, except the return type is @code{float}. +@end deftypefn + +@deftypefn {Built-in Function} long double __builtin_nanl (const char *str) +Similar to @code{__builtin_nan}, except the return type is @code{long double}. +@end deftypefn + +@deftypefn {Built-in Function} double __builtin_nans (const char *str) +Similar to @code{__builtin_nan}, except the significand is forced +to be a signaling NaN. The @code{nans} function is proposed by +@uref{http://std.dkuug.dk/JTC1/SC22/WG14/www/docs/n965.htm,,WG14 N965}. +@end deftypefn + +@deftypefn {Built-in Function} float __builtin_nansf (const char *str) +Similar to @code{__builtin_nans}, except the return type is @code{float}. +@end deftypefn + +@deftypefn {Built-in Function} long double __builtin_nansl (const char *str) +Similar to @code{__builtin_nans}, except the return type is @code{long double}. +@end deftypefn + @node Target Builtins @section Built-in Functions Specific to Particular Target Machines @@ -5049,14 +5154,10 @@ v4si __builtin_ia32_cmpordps (v4sf, v4sf) v4si __builtin_ia32_cmpeqss (v4sf, v4sf) v4si __builtin_ia32_cmpltss (v4sf, v4sf) v4si __builtin_ia32_cmpless (v4sf, v4sf) -v4si __builtin_ia32_cmpgtss (v4sf, v4sf) -v4si __builtin_ia32_cmpgess (v4sf, v4sf) v4si __builtin_ia32_cmpunordss (v4sf, v4sf) v4si __builtin_ia32_cmpneqss (v4sf, v4sf) v4si __builtin_ia32_cmpnlts (v4sf, v4sf) v4si __builtin_ia32_cmpnless (v4sf, v4sf) -v4si __builtin_ia32_cmpngtss (v4sf, v4sf) -v4si __builtin_ia32_cmpngess (v4sf, v4sf) v4si __builtin_ia32_cmpordss (v4sf, v4sf) v4sf __builtin_ia32_maxps (v4sf, v4sf) v4sf __builtin_ia32_maxss (v4sf, v4sf) @@ -6745,12 +6846,12 @@ the minimum value of variables @var{i} and @var{j}. However, side effects in @code{X} or @code{Y} may cause unintended behavior. For example, @code{MIN (i++, j++)} will fail, incrementing -the smaller counter twice. A GNU C extension allows you to write safe -macros that avoid this kind of problem (@pxref{Naming Types,,Naming an -Expression's Type}). However, writing @code{MIN} and @code{MAX} as -macros also forces you to use function-call notation for a -fundamental arithmetic operation. Using GNU C++ extensions, you can -write @w{@samp{int min = i <? j;}} instead. +the smaller counter twice. The GNU C @code{typeof} extension allows you +to write safe macros that avoid this kind of problem (@pxref{Typeof}). +However, writing @code{MIN} and @code{MAX} as macros also forces you to +use function-call notation for a fundamental arithmetic operation. +Using GNU C++ extensions, you can write @w{@samp{int min = i <? j;}} +instead. Since @code{<?} and @code{>?} are built into the compiler, they properly handle expressions with side-effects; @w{@samp{int min = i++ <? j++;}} @@ -7289,10 +7390,10 @@ inclusive. Lower numbers indicate a higher priority. In the following example, @code{A} would normally be created before @code{B}, but the @code{init_priority} attribute has reversed that order: -@example +@smallexample Some_Class A __attribute__ ((init_priority (2000))); Some_Class B __attribute__ ((init_priority (543))); -@end example +@end smallexample @noindent Note that the particular values of @var{priority} do not matter; only their @@ -7318,7 +7419,7 @@ appropriately. However, if C++ code only needs to execute destructors when Java exceptions are thrown through it, GCC will guess incorrectly. Sample problematic code is: -@example +@smallexample struct S @{ ~S(); @}; extern void bar(); // is written in Java, and may throw exceptions void foo() @@ -7326,7 +7427,7 @@ Sample problematic code is: S s; bar(); @} -@end example +@end smallexample @noindent The usual effect of an incorrect guess is a link failure, complaining of @@ -7383,7 +7484,7 @@ Floating and complex non-type template parameters have been deprecated, and are now removed from g++. The implicit typename extension has been deprecated and will be removed -from g++ at some point. In some cases g++ determines that a dependant +from g++ at some point. In some cases g++ determines that a dependent type such as @code{TPL<T>::X} is a type without needing a @code{typename} keyword, contrary to the standard. |