X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=binutils%2Fbinutils.texi;h=a20909ff7e491cadba628b78d91c2e64e12619d0;hb=4cc782b5919b187ce44ea9d4a66793105aeb07da;hp=900891fcdd4a5c01e14b85eb543e5a982939c620;hpb=18ef0a3df50ad9ee953a2faf59c3d4826d216429;p=deliverable%2Fbinutils-gdb.git diff --git a/binutils/binutils.texi b/binutils/binutils.texi index 900891fcdd..a20909ff7e 100644 --- a/binutils/binutils.texi +++ b/binutils/binutils.texi @@ -5,15 +5,28 @@ @ifinfo @format START-INFO-DIR-ENTRY -* Binutils: (binutils). The GNU binary utilities "ar", "objcopy", - "objdump", "nm", "nlmconv", "size", - "strings", "strip", and "ranlib". +* Binutils: (binutils). The GNU binary utilities. +* ar: (binutils)ar. Create, modify, and extract from archives +* nm: (binutils)nm. List symbols from object files +* objcopy: (binutils)objcopy. Copy and translate object files +* objdump: (binutils)objdump. Display information from object files +* ranlib: (binutils)ranlib. Generate index to archive contents +* readelf: (binutils)readelf. Display the contents of ELF format files. +* size: (binutils)size. List section sizes and total size +* strings: (binutils)strings. List printable strings from files +* strip: (binutils)strip. Discard symbols +* c++filt: (binutils)c++filt. Filter to demangle encoded C++ symbols +* cxxfilt: (binutils)c++filt. MS-DOS name for c++filt +* addr2line: (binutils)addr2line. Convert addresses to file and line +* nlmconv: (binutils)nlmconv. Converts object code into an NLM +* windres: (binutils)windres. Manipulate Windows resources +* dlltool: (binutils)dlltool. Create files needed to build and use DLLs END-INFO-DIR-ENTRY @end format @end ifinfo @ifinfo -Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 1997 Free Software Foundation, Inc. +Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 1999 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -39,9 +52,9 @@ into another language, under the above conditions for modified versions. @synindex ky cp @c @c This file documents the GNU binary utilities "ar", "ld", "objcopy", -@c "objdump", "nm", "size", "strings", "strip", and "ranlib". +@c "objdump", "nm", "size", "strings", "strip", "readelf" and "ranlib". @c -@c Copyright (C) 1991, 92, 93, 94, 95, 96, 1997 Free Software Foundation, Inc. +@c Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 1999 Free Software Foundation, Inc. @c @c This text may be freely distributed under the terms of the GNU @c General Public License. @@ -66,7 +79,7 @@ into another language, under the above conditions for modified versions. @end tex @vskip 0pt plus 1filll -Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 1997 Free Software Foundation, Inc. +Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -105,6 +118,9 @@ Display information from object files @item ranlib Generate index to archive contents +@item readelf +Display the contents of ELF format files. + @item size List file section sizes and total size @@ -115,7 +131,8 @@ List printable strings from files Discard symbols @item c++filt -Demangle encoded C++ symbols +Demangle encoded C++ symbols (on MS-DOS, this program is named +@code{cxxfilt}) @item addr2line Convert addresses into file names and line numbers @@ -125,6 +142,9 @@ Convert object code into a Netware Loadable Module @item windres Manipulate Windows resources + +@item dlltool +Create the files needed to build and use Dynamic Link Libraries @end table @end iftex @@ -134,13 +154,16 @@ Manipulate Windows resources * objcopy:: Copy and translate object files * objdump:: Display information from object files * ranlib:: Generate index to archive contents +* readelf:: Display the contents of ELF format files. * size:: List section sizes and total size * strings:: List printable strings from files * strip:: Discard symbols * c++filt:: Filter to demangle encoded C++ symbols +* cxxfilt: c++filt. MS-DOS name for c++filt * addr2line:: Convert addresses to file and line * nlmconv:: Converts object code into an NLM * windres:: Manipulate Windows resources +* dlltool:: Create files needed to build and use DLLs * Selecting The Target System:: How these utilities determine the target. * Reporting Bugs:: Reporting Bugs * Index:: Index @@ -153,7 +176,7 @@ Manipulate Windows resources @cindex archives @cindex collections of files @smallexample -ar [-]@var{p}[@var{mod} [@var{relpos}]] @var{archive} [@var{member}@dots{}] +ar [-]@var{p}[@var{mod} [@var{relpos}] [@var{count}]] @var{archive} [@var{member}@dots{}] ar -M [ } entry in the @samp{.drectve} +section of the object file. This can be done in C by using the +asm() operator: + +@smallexample + asm (".section .drectve"); + asm (".ascii \"-export:my_func\""); + + int my_func (void) @{ @dots{} @} +@end smallexample + +The second file needed for DLL creation is an exports file. This file +is linked with the object files that make up the body of the DLL and it +handles the interface between the DLL and the outside world. This is a +binary file and it can be created by giving the @samp{-e} option to +@code{dlltool} when it is creating or reading in a .def file. + +The third file needed for DLL creation is the library file that programs +will link with in order to access the functions in the DLL. This file +can be created by giving the @samp{-l} option to dlltool when it +is creating or reading in a .def file. + +@code{dlltool} builds the library file by hand, but it builds the +exports file by creating temporary files containing assembler statements +and then assembling these. The @samp{-S} command line option can be +used to specify the path to the assembler that dlltool will use, +and the @samp{-f} option can be used to pass specific flags to that +assembler. The @samp{-n} can be used to prevent dlltool from deleting +these temporary assembler files when it is done, and if @samp{-n} is +specified twice then this will prevent dlltool from deleting the +temporary object files it used to build the library. + +Here is an example of creating a DLL from a source file @samp{dll.c} and +also creating a program (from an object file called @samp{program.o}) +that uses that DLL: + +@smallexample + gcc -c dll.c + dlltool -e exports.o -l dll.lib dll.o + gcc dll.o exports.o -o dll.dll + gcc program.o dll.lib -o program +@end smallexample + +The command line options have the following meanings: + +@table @code + +@item -d @var{filename} +@itemx --input-def @var{filename} +@cindex input .def file +Specifies the name of a .def file to be read in and processed. + +@item -b @var{filename} +@itemx --base-file @var{filename} +@cindex base files +Specifies the name of a base file to be read in and processed. The +contents of this file will be added to the relocation section in the +exports file generated by dlltool. + +@item -e @var{filename} +@itemx --output-exp @var{filename} +Specifies the name of the export file to be created by dlltool. + +@item -z @var{filename} +@itemx --output-def @var{filename} +Specifies the name of the .def file to be created by dlltool. + +@item -l @var{filename} +@itemx --output-lib @var{filename} +Specifies the name of the library file to be created by dlltool. + +@item --export-all-symbols +Treat all global and weak defined symbols found in the input object +files as symbols to be exported. There is a small list of symbols which +are not exported by default; see the @code{--no-default-excludes} +option. You may add to the list of symbols to not export by using the +@code{--exclude-symbols} option. + +@item --no-export-all-symbols +Only export symbols explicitly listed in an input .def file or in +@samp{.drectve} sections in the input object files. This is the default +behaviour. The @samp{.drectve} sections are created by @samp{dllexport} +attributes in the source code. + +@item --exclude-symbols @var{list} +Do not export the symbols in @var{list}. This is a list of symbol names +separated by comma or colon characters. The symbol names should not +contain a leading underscore. This is only meaningful when +@code{--export-all-symbols} is used. + +@item --no-default-excludes +When @code{--export-all-symbols} is used, it will by default avoid +exporting certain special symbols. The current list of symbols to avoid +exporting is @samp{DllMain@@12}, @samp{DllEntryPoint@@0}, +@samp{impure_ptr}. You may use the @code{--no-default-excludes} option +to go ahead and export these special symbols. This is only meaningful +when @code{--export-all-symbols} is used. + +@item -S @var{path} +@itemx --as @var{path} +Specifies the path, including the filename, of the assembler to be used +to create the exports file. + +@item -f @var{switches} +@itemx --as-flags @var{switches} +Specifies any specific command line switches to be passed to the +assembler when building the exports file. This option will work even if +the @samp{-S} option is not used. This option only takes one argument, +and if it occurs more than once on the command line, then later +occurrences will override earlier occurrences. So if it is necessary to +pass multiple switches to the assembler they should be enclosed in +double quotes. + +@item -D @var{name} +@itemx --dll-name @var{name} +Specifies the name to be stored in the .def file as the name of the DLL +when the @samp{-e} option is used. If this option is not present, then +the filename given to the @samp{-e} option will be used as the name of +the DLL. + +@item -m @var{machine} +@itemx -machine @var{machine} +Specifies the type of machine for which the library file should be +built. @code{dlltool} has a built in default type, depending upon how +it was created, but this option can be used to override that. This is +normally only useful when creating DLLs for an ARM processor, when the +contents of the DLL are actually encode using THUMB instructions. + +@item -a +@itemx --add-indirect +Specifies that when @code{dlltool} is creating the exports file it +should add a section which allows the exported functions to be +referenced without using the import library. Whatever the hell that +means! + +@item -U +@itemx --add-underscore +Specifies that when @code{dlltool} is creating the exports file it +should prepend an underscore to the names of the exported functions. + +@item -k +@itemx --kill-at +Specifies that when @code{dlltool} is creating the exports file it +should not append the string @samp{@@ }. These numbers are +called ordinal numbers and they represent another way of accessing the +function in a DLL, other than by name. + +@item -A +@itemx --add-stdcall-alias +Specifies that when @code{dlltool} is creating the exports file it +should add aliases for stdcall symbols without @samp{@@ } +in addition to the symbols with @samp{@@ }. + +@item -x +@itemx --no-idata4 +Specifies that when @code{dlltool} is creating the exports and library +files it should omit the .idata4 section. This is for compatibility +with certain operating systems. + +@item -c +@itemx --no-idata5 +Specifies that when @code{dlltool} is creating the exports and library +files it should omit the .idata5 section. This is for compatibility +with certain operating systems. + +@item -i +@itemx --interwork +Specifies that @code{dlltool} should mark the objects in the library +file and exports file that it produces as supporting interworking +between ARM and THUMB code. + +@item -n +@itemx --nodelete +Makes @code{dlltool} preserve the temporary assembler files it used to +create the exports file. If this option is repeated then dlltool will +also preserve the temporary object files it uses to create the library +file. + +@item -v +@itemx --verbose +Make dlltool describe what it is doing. + +@item -h +@itemx --help +Displays a list of command line options and then exits. + +@item -V +@itemx --version +Displays dlltool's version number and then exits. + +@end table + +@node readelf +@chapter readelf + +@cindex ELF file information +@kindex readelf + +@smallexample +readelf [ -a | --all ] + [ -h | --file-header] + [ -l | --program-headers | --segments] + [ -S | --section-headers | --sections] + [ -e | --headers] + [ -s | --syms | --symbols] + [ -n | --notes] + [ -r | --relocs] + [ -d | --dynamic] + [ -V | --version-info] + [ -D | --use-dynamic] + [ -x | --hex-dump=] + [ -w[liapr] | --debug-dump[=info,=line,=abbrev,=pubnames,=ranges]] + [ --histogram] + [ -v | --version] + [ -H | --help] + @var{elffile}@dots{} +@end smallexample + +@code{readelf} displays information about one or more ELF format object +files. The options control what particular information to display. + +@var{elffile}@dots{} are the object files to be examined. At the +moment, @code{readelf} does not support examining archives, nor does it +support examing 64 bit ELF files. + +The long and short forms of options, shown here as alternatives, are +equivalent. At least one option besides @samp{-v} or @samp{-H} must be +given. + +@table @code +@item -a +@itemx --all +Equivalent to specifiying @samp{--file-header}, +@samp{--program-headers}, @samp{--sections}, @samp{--symbols}, +@samp{--relocs}, @samp{--dynamic}, @samp{--notes} and +@samp{--version-info}. + +@item -h +@itemx --file-header +@cindex ELF file header information +Displays the information contained in the ELF header at the start of the +file. + +@item -l +@itemx --program-headers +@itemx --segments +@cindex ELF program header information +@cindex ELF segment information +Displays the information contained in the file's segment headers, if it +has any. + +@item -S +@itemx --sections +@itemx --section-headers +@cindex ELF section information +Displays the information contained in the file's section headers, if it +has any. + +@item -s +@itemx --symbols +@itemx --syms +@cindex ELF symbol table information +Displays the entries in symbol table section of the file, if it has one. + +@item -e +@itemx --headers +Display all the headers in the file. Equivalent to @samp{-h -l -S}. + +@item -n +@itemx --notes +@cindex ELF core notes +Displays the contents of the NOTE segment, if it exists. + +@item -r +@itemx --relocs +@cindex ELF reloc information +Displays the contents of the file's relocation section, if it ha one. + +@item -d +@itemx --dynamic +@cindex ELF dynamic section information +Displays the contents of the file's dynamic section, if it has one. + +@item -V +@itemx --version-info +@cindex ELF version sections informations +Displays the contents of the version sections in the file, it they +exist. + +@item -D +@itemx --use-dynamic +When displaying symbols, this option makes @code{readelf} use the +symblol table in the file's dynamic section, rather than the one in the +symbols section. + +@item -x +@itemx --hex-dump= +Displays the contents of the indicated section as a hexadecimal dump. + +@item -w[liapr] +@itemx --debug-dump[=line,=info,=abbrev,=pubnames,=ranges] +Displays the contents of the debug sections in the file, if any are +present. If one of the optional letters or words follows the switch +then only data found in those specific sections will be dumped. + +@item --histogram +Display a histogram of bucket list lengths when displaying the contents +of the symbol tables. + +@item -v +@itemx --version +Display the version number of readelf. + +@item -H +@itemx --help +Display the command line options understood by @code{readelf}. + +@end table + + @node Selecting The Target System @chapter Selecting the target system @@ -2305,7 +2815,7 @@ individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs distribution. In any event, we also recommend that you send bug reports for the binary -utilities to @samp{bug-gnu-utils@@prep.ai.mit.edu}. +utilities to @samp{bug-gnu-utils@@gnu.org}. The fundamental principle of reporting bugs usefully is this: @strong{report all the facts}. If you are not sure whether to state a @@ -2365,9 +2875,10 @@ and then we might not encounter the bug. A complete input file, or set of input files, that will reproduce the bug. If the utility is reading an object file or files, then it is generally most helpful to send the actual object files, uuencoded if -necessary to get them through the mail system. Making them available -for anonymous FTP is not as good, but may be the only reasonable choice -for large object files. +necessary to get them through the mail system. Note that +@samp{bug-gnu-utils@@gnu.org} is a mailing list, so you should avoid +sending very large files to it. Making the files available for +anonymous FTP is OK. If the source files were produced exclusively using @sc{gnu} programs (e.g., @code{gcc}, @code{gas}, and/or the @sc{gnu} @code{ld}), then it