diff options
Diffstat (limited to 'gcc/doc/extend.texi')
| -rw-r--r-- | gcc/doc/extend.texi | 193 |
1 files changed, 153 insertions, 40 deletions
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index 40ccf22..70adf2d 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -31,6 +31,7 @@ extensions, accepted by GCC in C90 mode and in C++. * Thread-Local:: Per-thread variables. * OpenMP:: Multiprocessing extensions. * OpenACC:: Extensions for offloading code to accelerator devices. +* _Countof:: The number of elements of arrays. * Inline:: Defining inline functions (as fast as macros). * Volatiles:: What constitutes an access to a volatile object. * Using Assembly Language with C:: Instructions and extensions for interfacing C with assembler. @@ -2886,13 +2887,18 @@ my_memcpy (void *dest, const void *src, size_t len) @cindex @code{nonnull_if_nonzero} function attribute @item nonnull_if_nonzero @itemx nonnull_if_nonzero (@var{arg-index}, @var{arg2-index}) +@itemx nonnull_if_nonzero (@var{arg-index}, @var{arg2-index}, @var{arg3-index}) The @code{nonnull_if_nonzero} attribute is a conditional version of the -@code{nonnull} attribute. It has two arguments, the first argument +@code{nonnull} attribute. It has two or three arguments, the first argument shall be argument index of a pointer argument which must be in some cases non-null and the second argument shall be argument index of an integral argument (other than boolean). If the integral argument is zero, the pointer argument can be null, if it is non-zero, the pointer -argument must not be null. +argument must not be null. If three arguments are provided, the third +argument shall be argument index of another integral argument (other than +boolean) and the pointer argument can be null if either of the integral +arguments are zero and if both are non-zero, the pointer argument must not +be null. @smallexample extern void * @@ -2902,12 +2908,21 @@ extern void * my_memcpy2 (void *dest, const void *src, size_t len) __attribute__((nonnull_if_nonzero (1, 3), nonnull_if_nonzero (2, 3))); +extern size_t +my_fread (void *buf, size_t size, size_t count, FILE *stream) + __attribute__((nonnull (4), + nonnull_if_nonzero (1, 2, 3))); @end smallexample With these declarations, it is invalid to call @code{my_memcpy (NULL, NULL, 0);} or to -call @code{my_memcpy2 (NULL, NULL, 4);} but it is valid -to call @code{my_memcpy2 (NULL, NULL, 0);}. This attribute should be +call @code{my_memcpy2 (NULL, NULL, 4);} or to call +@code{my_fread(@var{buf}, 0, 0, NULL);} or to call +@code{my_fread(NULL, 1, 1, @var{stream});} but it is valid +to call @code{my_memcpy2 (NULL, NULL, 0);} or +@code{my_fread(NULL, 0, 0, @var{stream});} or +@code{my_fread(NULL, 0, 1, @var{stream});} or +@code{my_fread(NULL, 1, 0, @var{stream});}. This attribute should be used on declarations which have e.g.@: an exception for zero sizes, in which case null may be passed. @@ -3878,10 +3893,21 @@ behavior and permissible arguments are the same as for the command-line option @cindex @code{outline-atomics} function attribute, AArch64 @item outline-atomics +@itemx no-outline-atomics Enable or disable calls to out-of-line helpers to implement atomic operations. This corresponds to the behavior of the command-line options @option{-moutline-atomics} and @option{-mno-outline-atomics}. +@cindex @code{max-vectorization} function attribute, AArch64 +@item max-vectorization +@itemx no-max-vectorization +@code{max-vectorization} tells GCC's vectorizer to treat all vector +loops as being more profitable than the original scalar loops when +optimizing the current function. @code{no-max-vectorization} disables +this behavior. +This corresponds to the behavior of the command-line options +@option{-mmax-vectorization} and @option{-mno-max-vectorization}. + @cindex @code{indirect_return} function attribute, AArch64 @item indirect_return The @code{indirect_return} attribute can be applied to a function type @@ -6112,10 +6138,18 @@ pass arguments, unless it takes a variable number of arguments. @cindex @code{no_callee_saved_registers} function attribute, x86 @item no_callee_saved_registers Use this attribute to indicate that the specified function has no -callee-saved registers. That is, all registers can be used as scratch -registers. For example, this attribute can be used for a function -called from the interrupt handler assembly stub which will preserve -all registers and return from interrupt. +callee-saved registers. That is, all registers, except for stack and +frame pointers, can be used as scratch registers. For example, this +attribute can be used for a function called from the interrupt handler +assembly stub which will preserve all registers and return from +interrupt. + +@cindex @code{preserve_none} function attribute, x86 +@item preserve_none +This attribute is similar to @code{no_callee_saved_registers}, except +on x86-64, r12, r13, r14, r15, rdi and rsi registers are used for +integer parameter passing and this calling convention is subject to +change. @cindex @code{no_caller_saved_registers} function attribute, x86 @item no_caller_saved_registers @@ -6124,9 +6158,10 @@ caller-saved registers. That is, all registers are callee-saved. For example, this attribute can be used for a function called from an interrupt handler. The compiler generates proper function entry and exit sequences to save and restore any modified registers, except for -the EFLAGS register. Since GCC doesn't preserve SSE, MMX nor x87 -states, the GCC option @option{-mgeneral-regs-only} should be used to -compile functions with @code{no_caller_saved_registers} attribute. +the EFLAGS register. Since GCC doesn't preserve YMM nor ZMM registers, +@code{no_caller_saved_registers} attribute can't be used on functions +with AVX enabled. Note that MMX and x87 registers aren't preserved by +@code{no_caller_saved_registers} attribute. @cindex @code{interrupt} function attribute, x86 @item interrupt @@ -6684,23 +6719,10 @@ Enable/disable the generation of the USER_MSR instructions. Enable/disable the generation of the APX features, including EGPR, PUSH2POP2, NDD and PPX. -@cindex @code{target("avx10.1-256")} function attribute, x86 -@item avx10.1-256 -@itemx no-avx10.1-256 -Enable the generation of the AVX10.1 instructions with 256 bit support. -Disable the generation of the AVX10.1 instructions. - @cindex @code{target("avx10.1")} function attribute, x86 @item avx10.1 @itemx no-avx10.1 -Enable the generation of the AVX10.1 instructions with 512 bit support. -Disable the generation of the AVX10.1 instructions. - -@cindex @code{target("avx10.1-512")} function attribute, x86 -@item avx10.1-512 -@itemx no-avx10.1-512 -Enable the generation of the AVX10.1 instructions with 512 bit support. -Disable the generation of the AVX10.1 instructions. +Enable/Disable the generation of the AVX10.1 instructions. @cindex @code{target("avx10.2")} function attribute, x86 @item avx10.2 @@ -7116,9 +7138,11 @@ The @code{aligned} attribute can also be used for functions @cindex @code{counted_by} variable attribute @item counted_by (@var{count}) The @code{counted_by} attribute may be attached to the C99 flexible array -member of a structure. It indicates that the number of the elements of the -array is given by the field "@var{count}" in the same structure as the -flexible array member. +member, or a pointer field of a structure. It indicates that the number +of the elements of the array that is held by the flexible array member +field, or is pointed to by the pointer field, is given by the field +"@var{count}" in the same structure as the flexible array member or the +pointer field. This attribute is available only in C for now. In C++ this attribute is ignored. @@ -7139,8 +7163,22 @@ struct P @{ @end smallexample @noindent -specifies that the @code{array} is a flexible array member whose number of -elements is given by the field @code{count} in the same structure. +specifies that the @code{array} is a flexible array member whose number +of elements is given by the field @code{count} in the same structure. + +@smallexample +struct PP @{ + size_t count2; + char other1; + char *array2 __attribute__ ((counted_by (count2))); + int other2; +@} *pp; +@end smallexample + +@noindent +specifies that the @code{array2} is an array that is pointed by the +pointer field, and its number of elements is given by the field +@code{count2} in the same structure. The field that represents the number of the elements should have an integer type. Otherwise, the compiler reports an error and ignores @@ -7149,6 +7187,12 @@ the attribute. When the field that represents the number of the elements is assigned a negative integer value, the compiler treats the value as zero. +The @code{counted_by} attribute is not allowed for a pointer to @code{void}, +a pointer to function, or a pointer to a structure or union that includes +a flexible array member. However, it is allowed for a pointer to +non-void incomplete structure or union types, as long as the type could +be completed before the first reference to the pointer. + An explicit @code{counted_by} annotation defines a relationship between two objects, @code{p->array} and @code{p->count}, and there are the following requirements on the relationship between this pair: @@ -7164,6 +7208,13 @@ available all the time. This relationship must hold even after any of these related objects are updated during the program. @end itemize +In addition to the above requirements, there is one more requirement +between this pair if and only if @code{p->array} is an array that is +pointed by the pointer field: + +@code{p->array} and @code{p->count} can only be changed by changing the +whole structure at the same time. + It's the programmer's responsibility to make sure the above requirements to be kept all the time. Otherwise the compiler reports warnings and the results of the array bound sanitizer and the @@ -7185,6 +7236,8 @@ In the above, @code{ref1} uses @code{val1} as the number of the elements in @code{p->array}, and @code{ref2} uses @code{val2} as the number of elements in @code{p->array}. +Note, however, the above feature is not valid for the pointer field. + @cindex @code{alloc_size} variable attribute @item alloc_size (@var{position}) @itemx alloc_size (@var{position-1}, @var{position-2}) @@ -7336,7 +7389,7 @@ truncate the copy without appending the terminating @code{NUL} character. Using the attribute makes it possible to suppress the warning. However, when the array is declared with the attribute the call to @code{strlen} is diagnosed because when the array doesn't contain a @code{NUL}-terminated -string the call is undefined. To copy, compare, of search non-string +string the call is undefined. To copy, compare, or search non-string character arrays use the @code{memcpy}, @code{memcmp}, @code{memchr}, and other functions that operate on arrays of bytes. In addition, calling @code{strnlen} and @code{strndup} with such arrays is safe @@ -9188,7 +9241,7 @@ NoError: @item unused This feature is intended for program-generated code that may contain unused labels, but which is compiled with @option{-Wall}. It is -not normally appropriate to use in it human-written code, though it +not normally appropriate to use it in human-written code, though it could be useful in cases where the code that jumps to the label is contained within an @code{#ifdef} conditional. @@ -10393,6 +10446,11 @@ loop or a @code{#pragma GCC ivdep}, and applies only to the loop that follows. @var{n} is an integer constant expression specifying the unrolling factor. The values of @math{0} and @math{1} block any unrolling of the loop. +If the loop was vectorized the unroll factor specified will be used to seed the +vectorizer unroll factor. Whether the loop is unrolled or not will be +determined by target costing. The resulting vectorized loop may still be +unrolled more in later passes depending on the target costing. + @end table @node Thread-Local @@ -10679,7 +10737,7 @@ and @samp{[[omp::sequence(...)]]} in C and C++, GCC needs to be invoked with the @option{-fopenmp} option. This option also arranges for automatic linking of the OpenMP runtime library. -@xref{,,,libgomp,GNU Offloading and Multi Processing Runtime Library}. +@xref{Top,,,libgomp,GNU Offloading and Multi Processing Runtime Library}. @xref{OpenMP and OpenACC Options}, for additional options useful with @option{-fopenmp}. @@ -10701,11 +10759,41 @@ To enable the processing of OpenACC directives @samp{#pragma acc} in C and C++, GCC needs to be invoked with the @option{-fopenacc} option. This option also arranges for automatic linking of the OpenACC runtime library. -@xref{,,,libgomp,GNU Offloading and Multi Processing Runtime Library}. +@xref{Top,,,libgomp,GNU Offloading and Multi Processing Runtime Library}. @xref{OpenMP and OpenACC Options}, for additional options useful with @option{-fopenacc}. +@node _Countof +@section Determining the Number of Elements of Arrays +@cindex _Countof +@cindex number of elements + +The keyword @code{_Countof} determines +the number of elements of an array operand. +Its syntax is similar to @code{sizeof}. +The operand must be +a parenthesized complete array type name +or an expression of such a type. +For example: + +@smallexample +int a[n]; +_Countof (a); // returns n +_Countof (int [7][3]); // returns 7 +@end smallexample + +The result of this operator is an integer constant expression, +unless the array has a variable number of elements. +The operand is only evaluated +if the array has a variable number of elements. +For example: + +@smallexample +_Countof (int [7][n++]); // integer constant expression +_Countof (int [n++][7]); // run-time value; n++ is evaluated +@end smallexample + @node Inline @section An Inline Function is As Fast As a Macro @cindex inline functions @@ -14374,6 +14462,9 @@ a function call results in a compile-time error. @findex acoshf @findex acoshl @findex acosl +@findex acospi +@findex acospif +@findex acospil @findex alloca @findex asin @findex asinf @@ -14381,15 +14472,24 @@ a function call results in a compile-time error. @findex asinhf @findex asinhl @findex asinl +@findex asinpi +@findex asinpif +@findex asinpil @findex atan @findex atan2 @findex atan2f @findex atan2l +@findex atan2pi +@findex atan2pif +@findex atan2pil @findex atanf @findex atanh @findex atanhf @findex atanhl @findex atanl +@findex atanpi +@findex atanpif +@findex atanpil @findex bcmp @findex bzero @findex cabs @@ -14453,6 +14553,9 @@ a function call results in a compile-time error. @findex coshf @findex coshl @findex cosl +@findex cospi +@findex cospif +@findex cospil @findex cpow @findex cpowf @findex cpowl @@ -14688,6 +14791,9 @@ a function call results in a compile-time error. @findex sinhf @findex sinhl @findex sinl +@findex sinpi +@findex sinpif +@findex sinpil @findex snprintf @findex sprintf @findex sqrt @@ -14722,6 +14828,9 @@ a function call results in a compile-time error. @findex tanhf @findex tanhl @findex tanl +@findex tanpi +@findex tanpif +@findex tanpil @findex tgamma @findex tgammaf @findex tgammal @@ -14764,7 +14873,10 @@ a particular case, a call to the library function is emitted. @opindex std Outside strict ISO C mode (@option{-ansi}, @option{-std=c90}, @option{-std=c99} or @option{-std=c11}), the functions -@code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero}, +@code{_exit}, @code{alloca}, @code{acospi}, @code{acospif}, @code{acospil}, +@code{asinpi}, @code{asinpif}, @code{asinpil}, @code{atan2pi}, @code{atan2pif}, +@code{atan2pil}, @code{atanpi}, @code{atanpif}, @code{atanpil}, @code{bcmp}, +@code{bzero}, @code{cospi}, @code{cospif}, @code{cospil}, @code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml}, @code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll}, @code{ffsl}, @code{ffs}, @code{fprintf_unlocked}, @@ -14779,11 +14891,12 @@ Outside strict ISO C mode (@option{-ansi}, @option{-std=c90}, @code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32}, @code{signbitd64}, @code{signbitd128}, @code{significandf}, @code{significandl}, @code{significand}, @code{sincosf}, -@code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy}, -@code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp}, -@code{strndup}, @code{strnlen}, @code{toascii}, @code{y0f}, @code{y0l}, -@code{y0}, @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and -@code{yn} +@code{sincosl}, @code{sincos}, @code{sinpif}, @code{sinpil}, @code{sinpi}, +@code{stpcpy}, @code{stpncpy}, @code{strcasecmp}, @code{strdup}, +@code{strfmon}, @code{strncasecmp}, @code{strndup}, @code{strnlen}, +@code{tanpif}, @code{tanpil}, @code{tanpi}, @code{toascii}, @code{y0f}, +@code{y0l}, @code{y0}, @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, +@code{ynl} and @code{yn} may be handled as built-in functions. All these functions have corresponding versions prefixed with @code{__builtin_}, which may be used even in strict C90 |