diff options
Diffstat (limited to 'gcc/doc')
| -rw-r--r-- | gcc/doc/cpp.texi | 27 | ||||
| -rw-r--r-- | gcc/doc/extend.texi | 31 | ||||
| -rw-r--r-- | gcc/doc/invoke.texi | 80 | ||||
| -rw-r--r-- | gcc/doc/md.texi | 4 | ||||
| -rw-r--r-- | gcc/doc/tm.texi | 48 | ||||
| -rw-r--r-- | gcc/doc/tm.texi.in | 35 |
6 files changed, 144 insertions, 81 deletions
diff --git a/gcc/doc/cpp.texi b/gcc/doc/cpp.texi index 44f59bdfb47..ed91767bc96 100644 --- a/gcc/doc/cpp.texi +++ b/gcc/doc/cpp.texi @@ -2247,6 +2247,33 @@ these macros directly; instead, include the appropriate headers. Some of these macros may not be defined on particular systems if GCC does not provide a @file{stdint.h} header on those systems. +@item __SCHAR_WIDTH__ +@itemx __SHRT_WIDTH__ +@itemx __INT_WIDTH__ +@itemx __LONG_WIDTH__ +@itemx __LONG_LONG_WIDTH__ +@itemx __PTRDIFF_WIDTH__ +@itemx __SIG_ATOMIC_WIDTH__ +@itemx __SIZE_WIDTH__ +@itemx __WCHAR_WIDTH__ +@itemx __WINT_WIDTH__ +@itemx __INT_LEAST8_WIDTH__ +@itemx __INT_LEAST16_WIDTH__ +@itemx __INT_LEAST32_WIDTH__ +@itemx __INT_LEAST64_WIDTH__ +@itemx __INT_FAST8_WIDTH__ +@itemx __INT_FAST16_WIDTH__ +@itemx __INT_FAST32_WIDTH__ +@itemx __INT_FAST64_WIDTH__ +@itemx __INTPTR_WIDTH__ +@itemx __INTMAX_WIDTH__ +Defined to the bit widths of the corresponding types. They exist to +make the implementations of @file{limits.h} and @file{stdint.h} behave +correctly. You should not use these macros directly; instead, include +the appropriate headers. Some of these macros may not be defined on +particular systems if GCC does not provide a @file{stdint.h} header on +those systems. + @item __SIZEOF_INT__ @itemx __SIZEOF_LONG__ @itemx __SIZEOF_LONG_LONG__ diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index 8cb93abfa09..299986d86e8 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -9486,7 +9486,7 @@ the pointer points. @end smallexample The object pointed to by the first argument must be of integer or pointer -type. It must not be a Boolean type. +type. It must not be a boolean type. @emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand} as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}. @@ -9772,7 +9772,7 @@ they are not scaled by the size of the type to which the pointer points. @end smallexample The object pointed to by the first argument must be of integer or pointer -type. It must not be a Boolean type. All memory orders are valid. +type. It must not be a boolean type. All memory orders are valid. @end deftypefn @@ -9881,10 +9881,10 @@ together with checking whether the operations overflowed. @deftypefn {Built-in Function} bool __builtin_add_overflow (@var{type1} a, @var{type2} b, @var{type3} *res) @deftypefnx {Built-in Function} bool __builtin_sadd_overflow (int a, int b, int *res) @deftypefnx {Built-in Function} bool __builtin_saddl_overflow (long int a, long int b, long int *res) -@deftypefnx {Built-in Function} bool __builtin_saddll_overflow (long long int a, long long int b, long int *res) +@deftypefnx {Built-in Function} bool __builtin_saddll_overflow (long long int a, long long int b, long long int *res) @deftypefnx {Built-in Function} bool __builtin_uadd_overflow (unsigned int a, unsigned int b, unsigned int *res) @deftypefnx {Built-in Function} bool __builtin_uaddl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res) -@deftypefnx {Built-in Function} bool __builtin_uaddll_overflow (unsigned long long int a, unsigned long long int b, unsigned long int *res) +@deftypefnx {Built-in Function} bool __builtin_uaddll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res) These built-in functions promote the first two operands into infinite precision signed type and perform addition on those promoted operands. The result is then @@ -9896,7 +9896,7 @@ behavior for all argument values. The first built-in function allows arbitrary integral types for operands and the result type must be pointer to some integral type other than enumerated or -Boolean type, the rest of the built-in functions have explicit integer types. +boolean type, the rest of the built-in functions have explicit integer types. The compiler will attempt to use hardware instructions to implement these built-in functions where possible, like conditional jump on overflow @@ -9907,10 +9907,10 @@ after addition, conditional jump on carry etc. @deftypefn {Built-in Function} bool __builtin_sub_overflow (@var{type1} a, @var{type2} b, @var{type3} *res) @deftypefnx {Built-in Function} bool __builtin_ssub_overflow (int a, int b, int *res) @deftypefnx {Built-in Function} bool __builtin_ssubl_overflow (long int a, long int b, long int *res) -@deftypefnx {Built-in Function} bool __builtin_ssubll_overflow (long long int a, long long int b, long int *res) +@deftypefnx {Built-in Function} bool __builtin_ssubll_overflow (long long int a, long long int b, long long int *res) @deftypefnx {Built-in Function} bool __builtin_usub_overflow (unsigned int a, unsigned int b, unsigned int *res) @deftypefnx {Built-in Function} bool __builtin_usubl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res) -@deftypefnx {Built-in Function} bool __builtin_usubll_overflow (unsigned long long int a, unsigned long long int b, unsigned long int *res) +@deftypefnx {Built-in Function} bool __builtin_usubll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res) These built-in functions are similar to the add overflow checking built-in functions above, except they perform subtraction, subtract the second argument @@ -9921,10 +9921,10 @@ from the first one, instead of addition. @deftypefn {Built-in Function} bool __builtin_mul_overflow (@var{type1} a, @var{type2} b, @var{type3} *res) @deftypefnx {Built-in Function} bool __builtin_smul_overflow (int a, int b, int *res) @deftypefnx {Built-in Function} bool __builtin_smull_overflow (long int a, long int b, long int *res) -@deftypefnx {Built-in Function} bool __builtin_smulll_overflow (long long int a, long long int b, long int *res) +@deftypefnx {Built-in Function} bool __builtin_smulll_overflow (long long int a, long long int b, long long int *res) @deftypefnx {Built-in Function} bool __builtin_umul_overflow (unsigned int a, unsigned int b, unsigned int *res) @deftypefnx {Built-in Function} bool __builtin_umull_overflow (unsigned long int a, unsigned long int b, unsigned long int *res) -@deftypefnx {Built-in Function} bool __builtin_umulll_overflow (unsigned long long int a, unsigned long long int b, unsigned long int *res) +@deftypefnx {Built-in Function} bool __builtin_umulll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res) These built-in functions are similar to the add overflow checking built-in functions above, except they perform multiplication, instead of addition. @@ -9942,7 +9942,7 @@ These built-in functions are similar to @code{__builtin_add_overflow}, @code{__builtin_sub_overflow}, or @code{__builtin_mul_overflow}, except that they don't store the result of the arithmetic operation anywhere and the last argument is not a pointer, but some expression with integral type other -than enumerated or Boolean type. +than enumerated or boolean type. The built-in functions promote the first two operands into infinite precision signed type and perform addition on those promoted operands. The result is then @@ -10030,8 +10030,15 @@ __atomic_store_n(&lockvar, 0, __ATOMIC_RELEASE|__ATOMIC_HLE_RELEASE); @findex __builtin___fprintf_chk @findex __builtin___vfprintf_chk -GCC implements a limited buffer overflow protection mechanism -that can prevent some buffer overflow attacks. +GCC implements a limited buffer overflow protection mechanism that can +prevent some buffer overflow attacks by determining the sizes of objects +into which data is about to be written and preventing the writes when +the size isn't sufficient. The built-in functions described below yield +the best results when used together and when optimization is enabled. +For example, to detect object sizes across function boundaries or to +follow pointer assignments through non-trivial control flow they rely +on various optimization passes enabled with @option{-O2}. However, to +a limited extent, they can be used without optimization as well. @deftypefn {Built-in Function} {size_t} __builtin_object_size (void * @var{ptr}, int @var{type}) is a built-in construct that returns a constant number of bytes from diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index 87da1f1c12b..8eb5eff098e 100644 --- a/gcc/doc/invoke.texi +++ b/gcc/doc/invoke.texi @@ -190,7 +190,7 @@ in the following sections. @item C++ Language Options @xref{C++ Dialect Options,,Options Controlling C++ Dialect}. @gccoptlist{-fabi-version=@var{n} -fno-access-control @gol --fargs-in-order=@var{n} -fcheck-new @gol +-faligned-new=@var{n} -fargs-in-order=@var{n} -fcheck-new @gol -fconstexpr-depth=@var{n} -fconstexpr-loop-limit=@var{n} @gol -ffriend-injection @gol -fno-elide-constructors @gol @@ -248,7 +248,7 @@ Objective-C and Objective-C++ Dialects}. -fdiagnostics-show-location=@r{[}once@r{|}every-line@r{]} @gol -fdiagnostics-color=@r{[}auto@r{|}never@r{|}always@r{]} @gol -fno-diagnostics-show-option -fno-diagnostics-show-caret @gol --fdiagnostics-parseable-fixits} +-fdiagnostics-parseable-fixits -fdiagnostics-generate-patch} @item Warning Options @xref{Warning Options,,Options to Request or Suppress Warnings}. @@ -2237,6 +2237,15 @@ option is used for the warning. Turn off all access checking. This switch is mainly useful for working around bugs in the access control code. +@item -faligned-new +@opindex faligned-new +Enable support for C++17 @code{new} of types that require more +alignment than @code{void* ::operator new(std::size_t)} provides. A +numeric argument such as @code{-faligned-new=32} can be used to +specify how much alignment (in bytes) is provided by that function, +but few users will need to override the default of +@code{alignof(std::max_align_t)}. + @item -fcheck-new @opindex fcheck-new Check that the pointer returned by @code{operator new} is non-null @@ -3343,7 +3352,9 @@ for 88-color and 256-color modes background colors. The default @env{GCC_COLORS} is @smallexample -error=01;31:warning=01;35:note=01;36:range1=32:range2=34:locus=01:quote=01:fixit-insert=32:fixit-delete=31 +error=01;31:warning=01;35:note=01;36:range1=32:range2=34:locus=01:quote=01:\ +fixit-insert=32:fixit-delete=31:\ +diff-filename=01:diff-hunk=32:diff-delete=31:diff-insert=32 @end smallexample @noindent where @samp{01;31} is bold red, @samp{01;35} is bold magenta, @@ -3391,6 +3402,22 @@ be inserted or replaced. @vindex fixit-delete GCC_COLORS @r{capability} SGR substring for fix-it hints suggesting text to be deleted. + +@item diff-filename= +@vindex diff-filename GCC_COLORS @r{capability} +SGR substring for filename headers within generated patches. + +@item diff-hunk= +@vindex diff-hunk GCC_COLORS @r{capability} +SGR substring for the starts of hunks within generated patches. + +@item diff-delete= +@vindex diff-delete GCC_COLORS @r{capability} +SGR substring for deleted lines within generated patches. + +@item diff-insert= +@vindex diff-insert GCC_COLORS @r{capability} +SGR substring for inserted lines within generated patches. @end table @item -fno-diagnostics-show-option @@ -3442,6 +3469,27 @@ An empty replacement string indicates that the given range is to be removed. An empty range (e.g. ``45:3-45:3'') indicates that the string is to be inserted at the given position. +@item -fdiagnostics-generate-patch +@opindex fdiagnostics-generate-patch +Print fix-it hints to stderr in unified diff format, after any diagnostics +are printed. For example: + +@smallexample +--- test.c ++++ test.c +@@ -42,5 +42,5 @@ + + void show_cb(GtkDialog *dlg) + @{ +- gtk_widget_showall(dlg); ++ gtk_widget_show_all(dlg); + @} + +@end smallexample + +The diff may or may not be colorized, following the same rules +as for diagnostics (see @option{-fdiagnostics-color}). + @end table @node Warning Options @@ -5023,6 +5071,18 @@ disables the warnings about non-ISO @code{printf} / @code{scanf} format width specifiers @code{I32}, @code{I64}, and @code{I} used on Windows targets, which depend on the MS runtime. +@item -Waligned-new +@opindex Waligned-new +@opindex Wno-aligned-new +Warn about a new-expression of a type that requires greater alignment +than the @code{alignof(std::max_align_t)} but uses an allocation +function without an explicit alignment parameter. This option is +enabled by @option{-Wall}. + +Normally this only warns about global allocation functions, but +@option{-Waligned-new=all} also warns about class member allocation +functions. + @item -Wplacement-new @itemx -Wplacement-new=@var{n} @opindex Wplacement-new @@ -5437,8 +5497,8 @@ if (a < 0 && a < 0) @{ @dots{} @} @opindex Wlogical-not-parentheses @opindex Wno-logical-not-parentheses Warn about logical not used on the left hand side operand of a comparison. -This option does not warn if the RHS operand is of a boolean type. Its -purpose is to detect suspicious code like the following: +This option does not warn if the right operand is considered to be a boolean +expression. Its purpose is to detect suspicious code like the following: @smallexample int a; @dots{} @@ -22807,16 +22867,16 @@ more efficient. The default behavior is to use atomic updates. @item -mdual-nops @itemx -mdual-nops=@var{n} @opindex mdual-nops -By default, GCC inserts nops to increase dual issue when it expects +By default, GCC inserts NOPs to increase dual issue when it expects it to increase performance. @var{n} can be a value from 0 to 10. A -smaller @var{n} inserts fewer nops. 10 is the default, 0 is the +smaller @var{n} inserts fewer NOPs. 10 is the default, 0 is the same as @option{-mno-dual-nops}. Disabled with @option{-Os}. @item -mhint-max-nops=@var{n} @opindex mhint-max-nops -Maximum number of nops to insert for a branch hint. A branch hint must +Maximum number of NOPs to insert for a branch hint. A branch hint must be at least 8 instructions away from the branch it is affecting. GCC -inserts up to @var{n} nops to enforce this, otherwise it does not +inserts up to @var{n} NOPs to enforce this, otherwise it does not generate the branch hint. @item -mhint-max-distance=@var{n} @@ -24601,7 +24661,7 @@ automatically patching and out calls. @itemx -mno-nop-mcount @opindex mnop-mcount If profiling is active (@option{-pg}), generate the calls to -the profiling functions as nops. This is useful when they +the profiling functions as NOPs. This is useful when they should be patched in later dynamically. This is likely only useful together with @option{-mrecord-mcount}. diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi index 996b1649251..c1015f09a82 100644 --- a/gcc/doc/md.texi +++ b/gcc/doc/md.texi @@ -700,7 +700,7 @@ predicates used with @code{match_operand} have names that end in @samp{_operand}, and those used with @code{match_operator} have names that end in @samp{_operator}. -All predicates are Boolean functions (in the mathematical sense) of +All predicates are boolean functions (in the mathematical sense) of two arguments: the RTL expression that is being considered at that position in the instruction pattern, and the machine mode that the @code{match_operand} or @code{match_operator} specifies. In this @@ -4274,7 +4274,7 @@ constraint. Docstrings are explained further below. @end deffn Non-register constraints are more like predicates: the constraint -definition gives a Boolean expression which indicates whether the +definition gives a boolean expression which indicates whether the constraint matches. @deffn {MD Expression} define_constraint name docstring exp diff --git a/gcc/doc/tm.texi b/gcc/doc/tm.texi index 58662606243..8d533d53083 100644 --- a/gcc/doc/tm.texi +++ b/gcc/doc/tm.texi @@ -1891,7 +1891,7 @@ This hook may conditionally modify five variables @code{fixed_regs}, @code{call_used_regs}, @code{global_regs}, @code{reg_names}, and @code{reg_class_contents}, to take into account any dependence of these register sets on target flags. The first three -of these are of type @code{char []} (interpreted as Boolean vectors). +of these are of type @code{char []} (interpreted as boolean vectors). @code{global_regs} is a @code{const char *[]}, and @code{reg_class_contents} is a @code{HARD_REG_SET}. Before the macro is called, @code{fixed_regs}, @code{call_used_regs}, @@ -2861,7 +2861,7 @@ A target hook which can change allocno class for given pseudo from @end deftypefn @deftypefn {Target Hook} bool TARGET_LRA_P (void) -A target hook which returns true if we use LRA instead of reload pass. The default version of this target hook returns always false, but new ports should use LRA. +A target hook which returns true if we use LRA instead of reload pass. The default version of this target hook returns always true. New ports should use LRA, and existing ports are encouraged to convert. @end deftypefn @deftypefn {Target Hook} int TARGET_REGISTER_PRIORITY (int) @@ -3624,7 +3624,7 @@ pointer. In certain cases, the compiler does not know how to produce valid code without a frame pointer. The compiler recognizes those cases and automatically gives the function a frame pointer regardless of what -@code{TARGET_FRAME_POINTER_REQUIRED} returns. You don't need to worry about +@code{targetm.frame_pointer_required} returns. You don't need to worry about them. In a function that does not require a frame pointer, the frame pointer @@ -3634,25 +3634,9 @@ fixed register. See @code{FIXED_REGISTERS} for more information. Default return value is @code{false}. @end deftypefn -@findex get_frame_size -@defmac INITIAL_FRAME_POINTER_OFFSET (@var{depth-var}) -A C statement to store in the variable @var{depth-var} the difference -between the frame pointer and the stack pointer values immediately after -the function prologue. The value would be computed from information -such as the result of @code{get_frame_size ()} and the tables of -registers @code{regs_ever_live} and @code{call_used_regs}. - -If @code{ELIMINABLE_REGS} is defined, this macro will be not be used and -need not be defined. Otherwise, it must be defined even if -@code{TARGET_FRAME_POINTER_REQUIRED} always returns true; in that -case, you may set @var{depth-var} to anything. -@end defmac - @defmac ELIMINABLE_REGS -If defined, this macro specifies a table of register pairs used to -eliminate unneeded registers that point into the stack frame. If it is not -defined, the only elimination attempted by the compiler is to replace -references to the frame pointer with references to the stack pointer. +This macro specifies a table of register pairs used to eliminate +unneeded registers that point into the stack frame. The definition of this macro is a list of structure initializations, each of which specifies an original and replacement register. @@ -3676,21 +3660,20 @@ specified first since that is the preferred elimination. @end defmac @deftypefn {Target Hook} bool TARGET_CAN_ELIMINATE (const int @var{from_reg}, const int @var{to_reg}) -This target hook should returns @code{true} if the compiler is allowed to +This target hook should return @code{true} if the compiler is allowed to try to replace register number @var{from_reg} with register number -@var{to_reg}. This target hook need only be defined if @code{ELIMINABLE_REGS} -is defined, and will usually be @code{true}, since most of the cases -preventing register elimination are things that the compiler already +@var{to_reg}. This target hook will usually be @code{true}, since most of the +cases preventing register elimination are things that the compiler already knows about. Default return value is @code{true}. @end deftypefn @defmac INITIAL_ELIMINATION_OFFSET (@var{from-reg}, @var{to-reg}, @var{offset-var}) -This macro is similar to @code{INITIAL_FRAME_POINTER_OFFSET}. It -specifies the initial difference between the specified pair of -registers. This macro must be defined if @code{ELIMINABLE_REGS} is -defined. +This macro returns the initial difference between the specified pair +of registers. The value would be computed from information +such as the result of @code{get_frame_size ()} and the tables of +registers @code{df_regs_ever_live_p} and @code{call_used_regs}. @end defmac @node Stack Arguments @@ -9735,10 +9718,11 @@ between the two given labels in system defined units, e.g. instruction slots on IA64 VMS, using an integer of the given size. @end defmac -@defmac ASM_OUTPUT_DWARF_OFFSET (@var{stream}, @var{size}, @var{label}, @var{section}) +@defmac ASM_OUTPUT_DWARF_OFFSET (@var{stream}, @var{size}, @var{label}, @var{offset}, @var{section}) A C statement to issue assembly directives that create a -section-relative reference to the given @var{label}, using an integer of the -given @var{size}. The label is known to be defined in the given @var{section}. +section-relative reference to the given @var{label} plus @var{offset}, using +an integer of the given @var{size}. The label is known to be defined in the +given @var{section}. @end defmac @defmac ASM_OUTPUT_DWARF_PCREL (@var{stream}, @var{size}, @var{label}) diff --git a/gcc/doc/tm.texi.in b/gcc/doc/tm.texi.in index da133a4b701..b1482381c9a 100644 --- a/gcc/doc/tm.texi.in +++ b/gcc/doc/tm.texi.in @@ -3177,25 +3177,9 @@ This is about eliminating the frame pointer and arg pointer. @hook TARGET_FRAME_POINTER_REQUIRED -@findex get_frame_size -@defmac INITIAL_FRAME_POINTER_OFFSET (@var{depth-var}) -A C statement to store in the variable @var{depth-var} the difference -between the frame pointer and the stack pointer values immediately after -the function prologue. The value would be computed from information -such as the result of @code{get_frame_size ()} and the tables of -registers @code{regs_ever_live} and @code{call_used_regs}. - -If @code{ELIMINABLE_REGS} is defined, this macro will be not be used and -need not be defined. Otherwise, it must be defined even if -@code{TARGET_FRAME_POINTER_REQUIRED} always returns true; in that -case, you may set @var{depth-var} to anything. -@end defmac - @defmac ELIMINABLE_REGS -If defined, this macro specifies a table of register pairs used to -eliminate unneeded registers that point into the stack frame. If it is not -defined, the only elimination attempted by the compiler is to replace -references to the frame pointer with references to the stack pointer. +This macro specifies a table of register pairs used to eliminate +unneeded registers that point into the stack frame. The definition of this macro is a list of structure initializations, each of which specifies an original and replacement register. @@ -3221,10 +3205,10 @@ specified first since that is the preferred elimination. @hook TARGET_CAN_ELIMINATE @defmac INITIAL_ELIMINATION_OFFSET (@var{from-reg}, @var{to-reg}, @var{offset-var}) -This macro is similar to @code{INITIAL_FRAME_POINTER_OFFSET}. It -specifies the initial difference between the specified pair of -registers. This macro must be defined if @code{ELIMINABLE_REGS} is -defined. +This macro returns the initial difference between the specified pair +of registers. The value would be computed from information +such as the result of @code{get_frame_size ()} and the tables of +registers @code{df_regs_ever_live_p} and @code{call_used_regs}. @end defmac @node Stack Arguments @@ -7075,10 +7059,11 @@ between the two given labels in system defined units, e.g. instruction slots on IA64 VMS, using an integer of the given size. @end defmac -@defmac ASM_OUTPUT_DWARF_OFFSET (@var{stream}, @var{size}, @var{label}, @var{section}) +@defmac ASM_OUTPUT_DWARF_OFFSET (@var{stream}, @var{size}, @var{label}, @var{offset}, @var{section}) A C statement to issue assembly directives that create a -section-relative reference to the given @var{label}, using an integer of the -given @var{size}. The label is known to be defined in the given @var{section}. +section-relative reference to the given @var{label} plus @var{offset}, using +an integer of the given @var{size}. The label is known to be defined in the +given @var{section}. @end defmac @defmac ASM_OUTPUT_DWARF_PCREL (@var{stream}, @var{size}, @var{label}) |