X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=binutils%2Fdoc%2Fbinutils.texi;h=e0e6288ec6328bffbd75a3ad2e72d5bb8de71fa8;hb=f927cc8faff0d2e39561c90f5182ebe99b2f77f6;hp=cd707914900f05f288f8fd0ed5a0b117700b6448;hpb=de564eb5cc8c67fc38f9910937935eef5ebc17d8;p=deliverable%2Fbinutils-gdb.git diff --git a/binutils/doc/binutils.texi b/binutils/doc/binutils.texi index cd70791490..e0e6288ec6 100644 --- a/binutils/doc/binutils.texi +++ b/binutils/doc/binutils.texi @@ -10,7 +10,7 @@ @copying @c man begin COPYRIGHT -Copyright @copyright{} 1991-2018 Free Software Foundation, Inc. +Copyright @copyright{} 1991-2019 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 @@ -42,7 +42,7 @@ section entitled ``GNU Free Documentation License''. * size: (binutils)size. List section sizes and total size. * strings: (binutils)strings. List printable strings from files. * strip: (binutils)strip. Discard symbols. -* elfedit: (binutils)elfedit. Update the ELF header of ELF files. +* elfedit: (binutils)elfedit. Update ELF header and property of ELF files. * windmc: (binutils)windmc. Generator for Windows message resources. * windres: (binutils)windres. Manipulate Windows resources. @end direntry @@ -111,7 +111,7 @@ List printable strings from files Discard symbols @item elfedit -Update the ELF header of ELF files. +Update the ELF header and program property of ELF files. @item c++filt Demangle encoded C++ symbols (on MS-DOS, this program is named @@ -151,7 +151,7 @@ in the section entitled ``GNU Free Documentation License''. * windres:: Manipulate Windows resources * dlltool:: Create files needed to build and use DLLs * readelf:: Display the contents of ELF format files -* elfedit:: Update the ELF header of ELF files +* elfedit:: Update ELF header and property of ELF files * Common Options:: Command-line options for all utilities * Selecting the Target System:: How these utilities determine the target * Reporting Bugs:: Reporting Bugs @@ -465,7 +465,7 @@ option. @item P Use the full path name when matching names in the archive. @sc{gnu} @command{ar} can not create an archive with a full path name (such archives -are not POSIX complaint), but other archive creators can. This option +are not POSIX compliant), but other archive creators can. This option will cause @sc{gnu} @command{ar} to match file names using a complete path name, which can be convenient when extracting a single file from an archive created by another tool. @@ -769,7 +769,9 @@ nm [@option{-A}|@option{-o}|@option{--print-file-name}] [@option{-a}|@option{--d [@option{-s}|@option{--print-armap}] [@option{-t} @var{radix}|@option{--radix=}@var{radix}] [@option{-u}|@option{--undefined-only}] [@option{-V}|@option{--version}] [@option{-X 32_64}] [@option{--defined-only}] [@option{--no-demangle}] - [@option{--plugin} @var{name}] [@option{--size-sort}] [@option{--special-syms}] + [@option{--plugin} @var{name}] + [@option{--no-recurse-limit}|@option{--recurse-limit}]] + [@option{--size-sort}] [@option{--special-syms}] [@option{--synthetic}] [@option{--with-symbol-versions}] [@option{--target=}@var{bfdname}] [@var{objfile}@dots{}] @c man end @@ -939,6 +941,22 @@ for more information on demangling. @item --no-demangle Do not demangle low-level symbol names. This is the default. +@item --recurse-limit +@itemx --no-recurse-limit +@itemx --recursion-limit +@itemx --no-recursion-limit +Enables or disables a limit on the amount of recursion performed +whilst demangling strings. Since the name mangling formats allow for +an inifinite level of recursion it is possible to create strings whose +decoding will exhaust the amount of stack space available on the host +machine, triggering a memory fault. The limit tries to prevent this +from happening by restricting recursion to 2048 levels of nesting. + +The default is for this limit to be enabled, but disabling it may be +necessary in order to demangle truly complicated names. Note however +that if the recursion limit is disabled then stack exhaustion is +possible and any bug reports about such an event will be rejected. + @item -D @itemx --dynamic @cindex dynamic symbols @@ -1197,6 +1215,7 @@ objcopy [@option{-F} @var{bfdname}|@option{--target=}@var{bfdname}] [@option{--elf-stt-common=@var{val}}] [@option{--merge-notes}] [@option{--no-merge-notes}] + [@option{--verilog-data-width=@var{val}}] [@option{-v}|@option{--verbose}] [@option{-V}|@option{--version}] [@option{--help}] [@option{--info}] @@ -1840,7 +1859,7 @@ like this: @smallexample objcopy --add-gnu-debuglink=foo.debug @end smallexample - + At debug time the debugger will attempt to look for the separate debug info file in a set of known locations. The exact set of these locations varies depending upon the distribution being used, but it @@ -2030,6 +2049,11 @@ SHT_NOTE type sections by removing duplicate notes. @itemx --version Show the version number of @command{objcopy}. +@item --verilog-data-width=@var{bytes} +For Verilog output, this options controls the number of bytes +converted for each output data element. The input target controls the +endianness of the conversion. + @item -v @itemx --verbose Verbose output: list all object files modified. In the case of @@ -2056,14 +2080,14 @@ ld(1), objdump(1), and the Info entries for @file{binutils}. @cindex object file information @kindex objdump -@c man title objdump display information from object files. +@c man title objdump display information from object files @smallexample @c man begin SYNOPSIS objdump objdump [@option{-a}|@option{--archive-headers}] [@option{-b} @var{bfdname}|@option{--target=@var{bfdname}}] [@option{-C}|@option{--demangle}[=@var{style}] ] - [@option{-d}|@option{--disassemble}] + [@option{-d}|@option{--disassemble}[=@var{symbol}]] [@option{-D}|@option{--disassemble-all}] [@option{-z}|@option{--disassemble-zeroes}] [@option{-EB}|@option{-EL}|@option{--endian=}@{big | little @}] @@ -2086,6 +2110,7 @@ objdump [@option{-a}|@option{--archive-headers}] [@option{-s}|@option{--full-contents}] [@option{-W[lLiaprmfFsoRtUuTgAckK]}| @option{--dwarf}[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links,=follow-links]] + [@option{--ctf=}@var{section}] [@option{-G}|@option{--stabs}] [@option{-t}|@option{--syms}] [@option{-T}|@option{--dynamic-syms}] @@ -2098,6 +2123,10 @@ objdump [@option{-a}|@option{--archive-headers}] [@option{--adjust-vma=}@var{offset}] [@option{--dwarf-depth=@var{n}}] [@option{--dwarf-start=@var{n}}] + [@option{--ctf-parent=}@var{section}] + [@option{--ctf-symbols=}@var{section}] + [@option{--ctf-strings=}@var{section}] + [@option{--no-recurse-limit}|@option{--recurse-limit}] [@option{--special-syms}] [@option{--prefix=}@var{prefix}] [@option{--prefix-strip=}@var{level}] @@ -2174,6 +2203,22 @@ mangling styles. The optional demangling style argument can be used to choose an appropriate demangling style for your compiler. @xref{c++filt}, for more information on demangling. +@item --recurse-limit +@itemx --no-recurse-limit +@itemx --recursion-limit +@itemx --no-recursion-limit +Enables or disables a limit on the amount of recursion performed +whilst demangling strings. Since the name mangling formats allow for +an inifinite level of recursion it is possible to create strings whose +decoding will exhaust the amount of stack space available on the host +machine, triggering a memory fault. The limit tries to prevent this +from happening by restricting recursion to 2048 levels of nesting. + +The default is for this limit to be enabled, but disabling it may be +necessary in order to demangle truly complicated names. Note however +that if the recursion limit is disabled then stack exhaustion is +possible and any bug reports about such an event will be rejected. + @item -g @itemx --debugging Display debugging information. This attempts to parse STABS @@ -2189,11 +2234,21 @@ with ctags tool. @item -d @itemx --disassemble +@itemx --disassemble=@var{symbol} @cindex disassembling object code @cindex machine instructions -Display the assembler mnemonics for the machine instructions from -@var{objfile}. This option only disassembles those sections which are -expected to contain instructions. +Display the assembler mnemonics for the machine instructions from the +input file. This option only disassembles those sections which are +expected to contain instructions. If the optional @var{symbol} +argument is given, then display the assembler mnemonics starting at +@var{symbol}. If @var{symbol} is a function name then disassembly +will stop at the end of the function, otherwise it will stop when the +next symbol is encountered. If there are no matches for @var{symbol} +then nothing will be displayed. + +Note if the @option{--dwarf=follow-links} option has also been enabled +then any symbol tables in linked debug info files will be read in and +used when disassembling. @item -D @itemx --disassemble-all @@ -2213,6 +2268,10 @@ If the target is an ARM architecture this switch also has the effect of forcing the disassembler to decode pieces of data found in code sections as if they were instructions. +Note if the @option{--dwarf=follow-links} option has also been enabled +then any symbol tables in linked debug info files will be read in and +used when disassembling. + @item --prefix-addresses When disassembling, print the complete address on each line. This is the older disassembly format. @@ -2582,6 +2641,8 @@ instructions. @item --dwarf-check Enable additional checks for consistency of Dwarf information. +@include ctf.options.texi + @item -G @itemx --stabs @cindex stab @@ -2751,7 +2812,7 @@ nm(1), readelf(1), and the Info entries for @file{binutils}. @cindex archive contents @cindex symbol index -@c man title ranlib generate index to archive. +@c man title ranlib generate an index to an archive @smallexample @c man begin SYNOPSIS ranlib @@ -2832,11 +2893,11 @@ ar(1), nm(1), and the Info entries for @file{binutils}. @kindex size @cindex section sizes -@c man title size list section sizes and total size. +@c man title size list section sizes and total size of binary files @smallexample @c man begin SYNOPSIS size -size [@option{-A}|@option{-B}|@option{--format=}@var{compatibility}] +size [@option{-A}|@option{-B}|@option{-G}|@option{--format=}@var{compatibility}] [@option{--help}] [@option{-d}|@option{-o}|@option{-x}|@option{--radix=}@var{number}] [@option{--common}] @@ -2848,13 +2909,13 @@ size [@option{-A}|@option{-B}|@option{--format=}@var{compatibility}] @c man begin DESCRIPTION size -The @sc{gnu} @command{size} utility lists the section sizes---and the total -size---for each of the object or archive files @var{objfile} in its -argument list. By default, one line of output is generated for each -object file or each module in an archive. +The @sc{gnu} @command{size} utility lists the section sizes and the total +size for each of the binary files @var{objfile} on its argument list. +By default, one line of output is generated for each file or each +module if the file is an archive. -@var{objfile}@dots{} are the object files to be examined. -If none are specified, the file @code{a.out} will be used. +@var{objfile}@dots{} are the files to be examined. If none are +specified, the file @code{a.out} will be used instead. @c man end @@ -2865,13 +2926,16 @@ The command-line options have the following meanings: @table @env @item -A @itemx -B +@itemx -G @itemx --format=@var{compatibility} @cindex @command{size} display format Using one of these options, you can choose whether the output from @sc{gnu} @command{size} resembles output from System V @command{size} (using @option{-A}, or @option{--format=sysv}), or Berkeley @command{size} (using @option{-B}, or @option{--format=berkeley}). The default is the one-line format similar to -Berkeley's. +Berkeley's. Alternatively, you can choose the GNU format output +(using @option{-G}, or @option{--format=gnu}), this is similar to +Berkeley's output format, but sizes are counted differently. @c Bonus for doc-source readers: you can also say --format=strange (or @c anything else that starts with 's') for sysv, and --format=boring (or @c anything else that starts with 'b') for Berkeley. @@ -2880,9 +2944,27 @@ Here is an example of the Berkeley (default) format of output from @command{size}: @smallexample $ size --format=Berkeley ranlib size -text data bss dec hex filename -294880 81920 11592 388392 5ed28 ranlib -294880 81920 11888 388688 5ee50 size + text data bss dec hex filename + 294880 81920 11592 388392 5ed28 ranlib + 294880 81920 11888 388688 5ee50 size +@end smallexample + +The Berkeley style output counts read only data in the @code{text} +column, not in the @code{data} column, the @code{dec} and @code{hex} +columns both display the sum of the @code{text}, @code{data}, and +@code{bss} columns in decimal and hexadecimal respectively. + +The GNU format counts read only data in the @code{data} column, not +the @code{text} column, and only displays the sum of the @code{text}, +@code{data}, and @code{bss} columns once, in the @code{total} column. +The @option{--radix} option can be used to change the number base for +all columns. Here is the same data displayed with GNU conventions: + +@smallexample +$ size --format=GNU ranlib size + text data bss total filename + 279880 96920 11592 388392 ranlib + 279880 96920 11888 388688 size @end smallexample @noindent @@ -2925,11 +3007,11 @@ octal and hexadecimal if you're using @option{-o}. @item --common Print total size of common symbols in each file. When using Berkeley -format these are included in the bss size. +or GNU format these are included in the bss size. @item -t @itemx --totals -Show totals of all objects listed (Berkeley format listing mode only). +Show totals of all objects listed (Berkeley or GNU format mode only). @item --target=@var{bfdname} @cindex object code format @@ -2958,7 +3040,7 @@ ar(1), objdump(1), readelf(1), and the Info entries for @file{binutils}. @cindex printing strings @cindex strings, printing -@c man title strings print the strings of printable characters in files. +@c man title strings print the sequences of printable characters in files @smallexample @c man begin SYNOPSIS strings @@ -2990,7 +3072,7 @@ sequences that it can find. For backwards compatibility any file that occurs after a command-line option of just @option{-} will also be scanned in full, regardless of -the presence of any @option{-d} option. +the presence of any @option{-d} option. @command{strings} is mainly useful for determining the contents of non-text files. @@ -3100,7 +3182,7 @@ and the Info entries for @file{binutils}. @cindex discarding symbols @cindex symbols, discarding -@c man title strip Discard symbols from object files. +@c man title strip discard symbols and other data from object files @smallexample @c man begin SYNOPSIS strip @@ -3243,7 +3325,7 @@ normally be stripped. This option may be given more than once. @itemx --no-merge-notes For ELF files, attempt (or do not attempt) to reduce the size of any SHT_NOTE type sections by removing duplicate notes. The default is to -attempt this reduction. +attempt this reduction unless stripping debug or DWO information. @item -N @var{symbolname} @itemx --strip-symbol=@var{symbolname} @@ -3390,7 +3472,7 @@ the Info entries for @file{binutils}. @kindex c++filt @cindex demangling C++ symbols -@c man title cxxfilt Demangle C++ and Java symbols. +@c man title cxxfilt demangle C++ and Java symbols @smallexample @c man begin SYNOPSIS cxxfilt @@ -3399,6 +3481,8 @@ c++filt [@option{-_}|@option{--strip-underscore}] [@option{-p}|@option{--no-params}] [@option{-t}|@option{--types}] [@option{-i}|@option{--no-verbose}] + [@option{-r}|@option{--no-recurse-limit}] + [@option{-R}|@option{--recurse-limit}] [@option{-s} @var{format}|@option{--format=}@var{format}] [@option{--help}] [@option{--version}] [@var{symbol}@dots{}] @c man end @@ -3503,6 +3587,28 @@ demangled to ``signed char''. Do not include implementation details (if any) in the demangled output. +@item -r +@itemx -R +@itemx --recurse-limit +@itemx --no-recurse-limit +@itemx --recursion-limit +@itemx --no-recursion-limit +Enables or disables a limit on the amount of recursion performed +whilst demangling strings. Since the name mangling formats allow for +an inifinite level of recursion it is possible to create strings whose +decoding will exhaust the amount of stack space available on the host +machine, triggering a memory fault. The limit tries to prevent this +from happening by restricting recursion to 2048 levels of nesting. + +The default is for this limit to be enabled, but disabling it may be +necessary in order to demangle truly complicated names. Note however +that if the recursion limit is disabled then stack exhaustion is +possible and any bug reports about such an event will be rejected. + +The @option{-r} option is a synonym for the +@option{--no-recurse-limit} option. The @option{-R} option is a +synonym for the @option{--recurse-limit} option. + @item -s @var{format} @itemx --format=@var{format} @command{c++filt} can decode various methods of mangling, used by @@ -3569,13 +3675,15 @@ c++filt @var{option} @var{symbol} @kindex addr2line @cindex address to file name and line number -@c man title addr2line convert addresses into file names and line numbers. +@c man title addr2line convert addresses into file names and line numbers @smallexample @c man begin SYNOPSIS addr2line addr2line [@option{-a}|@option{--addresses}] [@option{-b} @var{bfdname}|@option{--target=}@var{bfdname}] [@option{-C}|@option{--demangle}[=@var{style}]] + [@option{-r}|@option{--no-recurse-limit}] + [@option{-R}|@option{--recurse-limit}] [@option{-e} @var{filename}|@option{--exe=}@var{filename}] [@option{-f}|@option{--functions}] [@option{-s}|@option{--basename}] [@option{-i}|@option{--inlines}] @@ -3701,6 +3809,32 @@ Read offsets relative to the specified section instead of absolute addresses. Make the output more human friendly: each location are printed on one line. If option @option{-i} is specified, lines for all enclosing scopes are prefixed with @samp{(inlined by)}. + +@item -r +@itemx -R +@itemx --recurse-limit +@itemx --no-recurse-limit +@itemx --recursion-limit +@itemx --no-recursion-limit +Enables or disables a limit on the amount of recursion performed +whilst demangling strings. Since the name mangling formats allow for +an inifinite level of recursion it is possible to create strings whose +decoding will exhaust the amount of stack space available on the host +machine, triggering a memory fault. The limit tries to prevent this +from happening by restricting recursion to 2048 levels of nesting. + +The default is for this limit to be enabled, but disabling it may be +necessary in order to demangle truly complicated names. Note however +that if the recursion limit is disabled then stack exhaustion is +possible and any bug reports about such an event will be rejected. + +The @option{-r} option is a synonym for the +@option{--no-recurse-limit} option. The @option{-R} option is a +synonym for the @option{--recurse-limit} option. + +Note this option is only effective if the @option{-C} or +@option{--demangle} option has been enabled. + @end table @c man end @@ -3721,7 +3855,7 @@ Info entries for @file{binutils}. utilities, since it is only useful for Windows targets. @end quotation -@c man title windmc generates Windows message resources. +@c man title windmc generates Windows message resources @smallexample @c man begin SYNOPSIS windmc @@ -3882,7 +4016,7 @@ the Info entries for @file{binutils}. utilities, since it is only useful for Windows targets. @end quotation -@c man title windres manipulate Windows resources. +@c man title windres manipulate Windows resources @smallexample @c man begin SYNOPSIS windres @@ -4088,7 +4222,7 @@ binary utilities, since it is only useful for those targets which support DLLs. @end quotation -@c man title dlltool Create files needed to build and use DLLs. +@c man title dlltool create files needed to build and use DLLs @smallexample @c man begin SYNOPSIS dlltool @@ -4479,7 +4613,7 @@ The Info pages for @file{binutils}. @cindex ELF file information @kindex readelf -@c man title readelf Displays information about ELF files. +@c man title readelf display information about ELF files @smallexample @c man begin SYNOPSIS readelf @@ -4508,6 +4642,10 @@ readelf [@option{-a}|@option{--all}] @option{--debug-dump}[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links,=follow-links]] [@option{--dwarf-depth=@var{n}}] [@option{--dwarf-start=@var{n}}] + [@option{--ctf=}@var{section}] + [@option{--ctf-parent=}@var{section}] + [@option{--ctf-symbols=}@var{section}] + [@option{--ctf-strings=}@var{section}] [@option{-I}|@option{--histogram}] [@option{-v}|@option{--version}] [@option{-W}|@option{--wide}] @@ -4620,7 +4758,11 @@ Displays the contents of the file's relocation section, if it has one. @cindex unwind information Displays the contents of the file's unwind section, if it has one. Only the unwind sections for IA64 ELF files, as well as ARM unwind tables -(@code{.ARM.exidx} / @code{.ARM.extab}) are currently supported. +(@code{.ARM.exidx} / @code{.ARM.extab}) are currently supported. If +support is not yet implemented for your architecture you could try +dumping the contents of the @var{.eh_frames} section using the +@option{--debug-dump=frames} or @option{--debug-dump=frames-interp} +options. @item -d @itemx --dynamic @@ -4684,6 +4826,15 @@ command to @command{ar}, but without using the BFD library. @xref{ar}. @itemx --debug-dump[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links,=follow-links] @include debug.options.texi +@include ctf.options.texi +@item --ctf-symbols=@var{section} +@item --ctf-strings=@var{section} +Specify the name of another section from which the CTF file can inherit +strings and symbols. + +If either of @option{--ctf-symbols} or @option{--ctf-strings} is specified, the +other must be specified as well. + @item -I @itemx --histogram Display a histogram of bucket list lengths when displaying the contents @@ -4721,7 +4872,7 @@ objdump(1), and the Info entries for @file{binutils}. @cindex Update ELF header @kindex elfedit -@c man title elfedit Update the ELF header of ELF files. +@c man title elfedit update ELF header and program property of ELF files @smallexample @c man begin SYNOPSIS elfedit @@ -4731,6 +4882,8 @@ elfedit [@option{--input-mach=}@var{machine}] @option{--output-mach=}@var{machine} @option{--output-type=}@var{type} @option{--output-osabi=}@var{osabi} + @option{--enable-x86-feature=}@var{feature} + @option{--disable-x86-feature=}@var{feature} [@option{-v}|@option{--version}] [@option{-h}|@option{--help}] @var{elffile}@dots{} @@ -4739,9 +4892,10 @@ elfedit [@option{--input-mach=}@var{machine}] @c man begin DESCRIPTION elfedit -@command{elfedit} updates the ELF header of ELF files which have -the matching ELF machine and file types. The options control how and -which fields in the ELF header should be updated. +@command{elfedit} updates the ELF header and program property of ELF +files which have the matching ELF machine and file types. The options +control how and which fields in the ELF header and program property +should be updated. @var{elffile}@dots{} are the ELF files to be updated. 32-bit and 64-bit ELF files are supported, as are archives containing ELF files. @@ -4751,7 +4905,9 @@ which fields in the ELF header should be updated. The long and short forms of options, shown here as alternatives, are equivalent. At least one of the @option{--output-mach}, -@option{--output-type} and @option{--output-osabi} options must be given. +@option{--output-type}, @option{--output-osabi}, +@option{--enable-x86-feature} and @option{--disable-x86-feature} +options must be given. @table @env @@ -4791,6 +4947,19 @@ The supported ELF OSABIs are, @var{none}, @var{HPUX}, @var{NetBSD}, Change the ELF OSABI in the ELF header to @var{osabi}. The supported ELF OSABI are the same as @option{--input-osabi}. +@item --enable-x86-feature=@var{feature} +Set the @var{feature} bit in program property in @var{exec} or @var{dyn} +ELF files with machine types of @var{i386} or @var{x86-64}. The +supported features are, @var{ibt} and @var{shstk}. + +@item --disable-x86-feature=@var{feature} +Clear the @var{feature} bit in program property in @var{exec} or +@var{dyn} ELF files with machine types of @var{i386} or @var{x86-64}. +The supported features are the same as @option{--enable-x86-feature}. + +Note: @option{--enable-x86-feature} and @option{--disable-x86-feature} +are available only on hosts with @samp{mmap} support. + @item -v @itemx --version Display the version number of @command{elfedit}.