| This is binutils.info, produced by makeinfo version 4.0 from |
| binutils.texi. |
| |
| START-INFO-DIR-ENTRY |
| * 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 |
| |
| Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001 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.1 |
| or any later version published by the Free Software Foundation; |
| with no Invariant Sections, with no Front-Cover Texts, and with no |
| Back-Cover Texts. A copy of the license is included in the |
| section entitled "GNU Free Documentation License". |
| |
| |
| File: binutils.info, Node: Top, Next: ar, Up: (dir) |
| |
| Introduction |
| ************ |
| |
| This brief manual contains preliminary documentation for the GNU |
| binary utilities (collectively version 2.11.2): |
| |
| This document is distributed under the terms of the GNU Free |
| Documentation License. A copy of the license is included in the |
| section entitled "GNU Free Documentation License". |
| |
| * Menu: |
| |
| * ar:: Create, modify, and extract from archives |
| * nm:: List symbols from object files |
| * 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 |
| * GNU Free Documentation License:: GNU Free Documentation License |
| * Index:: Index |
| |
| |
| File: binutils.info, Node: ar, Next: nm, Prev: Top, Up: Top |
| |
| ar |
| ** |
| |
| ar [-]P[MOD [RELPOS] [COUNT]] ARCHIVE [MEMBER...] |
| ar -M [ <mri-script ] |
| |
| The GNU `ar' program creates, modifies, and extracts from archives. |
| An "archive" is a single file holding a collection of other files in a |
| structure that makes it possible to retrieve the original individual |
| files (called "members" of the archive). |
| |
| The original files' contents, mode (permissions), timestamp, owner, |
| and group are preserved in the archive, and can be restored on |
| extraction. |
| |
| GNU `ar' can maintain archives whose members have names of any |
| length; however, depending on how `ar' is configured on your system, a |
| limit on member-name length may be imposed for compatibility with |
| archive formats maintained with other tools. If it exists, the limit |
| is often 15 characters (typical of formats related to a.out) or 16 |
| characters (typical of formats related to coff). |
| |
| `ar' is considered a binary utility because archives of this sort |
| are most often used as "libraries" holding commonly needed subroutines. |
| |
| `ar' creates an index to the symbols defined in relocatable object |
| modules in the archive when you specify the modifier `s'. Once |
| created, this index is updated in the archive whenever `ar' makes a |
| change to its contents (save for the `q' update operation). An archive |
| with such an index speeds up linking to the library, and allows |
| routines in the library to call each other without regard to their |
| placement in the archive. |
| |
| You may use `nm -s' or `nm --print-armap' to list this index table. |
| If an archive lacks the table, another form of `ar' called `ranlib' can |
| be used to add just the table. |
| |
| GNU `ar' is designed to be compatible with two different facilities. |
| You can control its activity using command-line options, like the |
| different varieties of `ar' on Unix systems; or, if you specify the |
| single command-line option `-M', you can control it with a script |
| supplied via standard input, like the MRI "librarian" program. |
| |
| * Menu: |
| |
| * ar cmdline:: Controlling `ar' on the command line |
| * ar scripts:: Controlling `ar' with a script |
| |
| |
| File: binutils.info, Node: ar cmdline, Next: ar scripts, Up: ar |
| |
| Controlling `ar' on the command line |
| ==================================== |
| |
| ar [-X32_64] [-]P[MOD [RELPOS] [COUNT]] ARCHIVE [MEMBER...] |
| |
| When you use `ar' in the Unix style, `ar' insists on at least two |
| arguments to execute: one keyletter specifying the _operation_ |
| (optionally accompanied by other keyletters specifying _modifiers_), |
| and the archive name to act on. |
| |
| Most operations can also accept further MEMBER arguments, specifying |
| particular files to operate on. |
| |
| GNU `ar' allows you to mix the operation code P and modifier flags |
| MOD in any order, within the first command-line argument. |
| |
| If you wish, you may begin the first command-line argument with a |
| dash. |
| |
| The P keyletter specifies what operation to execute; it may be any |
| of the following, but you must specify only one of them: |
| |
| `d' |
| _Delete_ modules from the archive. Specify the names of modules to |
| be deleted as MEMBER...; the archive is untouched if you specify |
| no files to delete. |
| |
| If you specify the `v' modifier, `ar' lists each module as it is |
| deleted. |
| |
| `m' |
| Use this operation to _move_ members in an archive. |
| |
| The ordering of members in an archive can make a difference in how |
| programs are linked using the library, if a symbol is defined in |
| more than one member. |
| |
| If no modifiers are used with `m', any members you name in the |
| MEMBER arguments are moved to the _end_ of the archive; you can |
| use the `a', `b', or `i' modifiers to move them to a specified |
| place instead. |
| |
| `p' |
| _Print_ the specified members of the archive, to the standard |
| output file. If the `v' modifier is specified, show the member |
| name before copying its contents to standard output. |
| |
| If you specify no MEMBER arguments, all the files in the archive |
| are printed. |
| |
| `q' |
| _Quick append_; Historically, add the files MEMBER... to the end of |
| ARCHIVE, without checking for replacement. |
| |
| The modifiers `a', `b', and `i' do _not_ affect this operation; |
| new members are always placed at the end of the archive. |
| |
| The modifier `v' makes `ar' list each file as it is appended. |
| |
| Since the point of this operation is speed, the archive's symbol |
| table index is not updated, even if it already existed; you can |
| use `ar s' or `ranlib' explicitly to update the symbol table index. |
| |
| However, too many different systems assume quick append rebuilds |
| the index, so GNU ar implements `q' as a synonym for `r'. |
| |
| `r' |
| Insert the files MEMBER... into ARCHIVE (with _replacement_). This |
| operation differs from `q' in that any previously existing members |
| are deleted if their names match those being added. |
| |
| If one of the files named in MEMBER... does not exist, `ar' |
| displays an error message, and leaves undisturbed any existing |
| members of the archive matching that name. |
| |
| By default, new members are added at the end of the file; but you |
| may use one of the modifiers `a', `b', or `i' to request placement |
| relative to some existing member. |
| |
| The modifier `v' used with this operation elicits a line of output |
| for each file inserted, along with one of the letters `a' or `r' |
| to indicate whether the file was appended (no old member deleted) |
| or replaced. |
| |
| `t' |
| Display a _table_ listing the contents of ARCHIVE, or those of the |
| files listed in MEMBER... that are present in the archive. |
| Normally only the member name is shown; if you also want to see |
| the modes (permissions), timestamp, owner, group, and size, you can |
| request that by also specifying the `v' modifier. |
| |
| If you do not specify a MEMBER, all files in the archive are |
| listed. |
| |
| If there is more than one file with the same name (say, `fie') in |
| an archive (say `b.a'), `ar t b.a fie' lists only the first |
| instance; to see them all, you must ask for a complete listing--in |
| our example, `ar t b.a'. |
| |
| `x' |
| _Extract_ members (named MEMBER) from the archive. You can use |
| the `v' modifier with this operation, to request that `ar' list |
| each name as it extracts it. |
| |
| If you do not specify a MEMBER, all files in the archive are |
| extracted. |
| |
| A number of modifiers (MOD) may immediately follow the P keyletter, |
| to specify variations on an operation's behavior: |
| |
| `a' |
| Add new files _after_ an existing member of the archive. If you |
| use the modifier `a', the name of an existing archive member must |
| be present as the RELPOS argument, before the ARCHIVE |
| specification. |
| |
| `b' |
| Add new files _before_ an existing member of the archive. If you |
| use the modifier `b', the name of an existing archive member must |
| be present as the RELPOS argument, before the ARCHIVE |
| specification. (same as `i'). |
| |
| `c' |
| _Create_ the archive. The specified ARCHIVE is always created if |
| it did not exist, when you request an update. But a warning is |
| issued unless you specify in advance that you expect to create it, |
| by using this modifier. |
| |
| `f' |
| Truncate names in the archive. GNU `ar' will normally permit file |
| names of any length. This will cause it to create archives which |
| are not compatible with the native `ar' program on some systems. |
| If this is a concern, the `f' modifier may be used to truncate file |
| names when putting them in the archive. |
| |
| `i' |
| Insert new files _before_ an existing member of the archive. If |
| you use the modifier `i', the name of an existing archive member |
| must be present as the RELPOS argument, before the ARCHIVE |
| specification. (same as `b'). |
| |
| `l' |
| This modifier is accepted but not used. |
| |
| `N' |
| Uses the COUNT parameter. This is used if there are multiple |
| entries in the archive with the same name. Extract or delete |
| instance COUNT of the given name from the archive. |
| |
| `o' |
| Preserve the _original_ dates of members when extracting them. If |
| you do not specify this modifier, files extracted from the archive |
| are stamped with the time of extraction. |
| |
| `P' |
| Use the full path name when matching names in the archive. GNU |
| `ar' can not create an archive with a full path name (such archives |
| are not POSIX complaint), but other archive creators can. This |
| option will cause GNU `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. |
| |
| `s' |
| Write an object-file index into the archive, or update an existing |
| one, even if no other change is made to the archive. You may use |
| this modifier flag either with any operation, or alone. Running |
| `ar s' on an archive is equivalent to running `ranlib' on it. |
| |
| `S' |
| Do not generate an archive symbol table. This can speed up |
| building a large library in several steps. The resulting archive |
| can not be used with the linker. In order to build a symbol |
| table, you must omit the `S' modifier on the last execution of |
| `ar', or you must run `ranlib' on the archive. |
| |
| `u' |
| Normally, `ar r'... inserts all files listed into the archive. If |
| you would like to insert _only_ those of the files you list that |
| are newer than existing members of the same names, use this |
| modifier. The `u' modifier is allowed only for the operation `r' |
| (replace). In particular, the combination `qu' is not allowed, |
| since checking the timestamps would lose any speed advantage from |
| the operation `q'. |
| |
| `v' |
| This modifier requests the _verbose_ version of an operation. Many |
| operations display additional information, such as filenames |
| processed, when the modifier `v' is appended. |
| |
| `V' |
| This modifier shows the version number of `ar'. |
| |
| `ar' ignores an initial option spelt `-X32_64', for compatibility |
| with AIX. The behaviour produced by this option is the default for GNU |
| `ar'. `ar' does not support any of the other `-X' options; in |
| particular, it does not support `-X32' which is the default for AIX |
| `ar'. |
| |
| |
| File: binutils.info, Node: ar scripts, Prev: ar cmdline, Up: ar |
| |
| Controlling `ar' with a script |
| ============================== |
| |
| ar -M [ <SCRIPT ] |
| |
| If you use the single command-line option `-M' with `ar', you can |
| control its operation with a rudimentary command language. This form |
| of `ar' operates interactively if standard input is coming directly |
| from a terminal. During interactive use, `ar' prompts for input (the |
| prompt is `AR >'), and continues executing even after errors. If you |
| redirect standard input to a script file, no prompts are issued, and |
| `ar' abandons execution (with a nonzero exit code) on any error. |
| |
| The `ar' command language is _not_ designed to be equivalent to the |
| command-line options; in fact, it provides somewhat less control over |
| archives. The only purpose of the command language is to ease the |
| transition to GNU `ar' for developers who already have scripts written |
| for the MRI "librarian" program. |
| |
| The syntax for the `ar' command language is straightforward: |
| * commands are recognized in upper or lower case; for example, `LIST' |
| is the same as `list'. In the following descriptions, commands are |
| shown in upper case for clarity. |
| |
| * a single command may appear on each line; it is the first word on |
| the line. |
| |
| * empty lines are allowed, and have no effect. |
| |
| * comments are allowed; text after either of the characters `*' or |
| `;' is ignored. |
| |
| * Whenever you use a list of names as part of the argument to an `ar' |
| command, you can separate the individual names with either commas |
| or blanks. Commas are shown in the explanations below, for |
| clarity. |
| |
| * `+' is used as a line continuation character; if `+' appears at |
| the end of a line, the text on the following line is considered |
| part of the current command. |
| |
| Here are the commands you can use in `ar' scripts, or when using |
| `ar' interactively. Three of them have special significance: |
| |
| `OPEN' or `CREATE' specify a "current archive", which is a temporary |
| file required for most of the other commands. |
| |
| `SAVE' commits the changes so far specified by the script. Prior to |
| `SAVE', commands affect only the temporary copy of the current archive. |
| |
| `ADDLIB ARCHIVE' |
| `ADDLIB ARCHIVE (MODULE, MODULE, ... MODULE)' |
| Add all the contents of ARCHIVE (or, if specified, each named |
| MODULE from ARCHIVE) to the current archive. |
| |
| Requires prior use of `OPEN' or `CREATE'. |
| |
| `ADDMOD MEMBER, MEMBER, ... MEMBER' |
| Add each named MEMBER as a module in the current archive. |
| |
| Requires prior use of `OPEN' or `CREATE'. |
| |
| `CLEAR' |
| Discard the contents of the current archive, canceling the effect |
| of any operations since the last `SAVE'. May be executed (with no |
| effect) even if no current archive is specified. |
| |
| `CREATE ARCHIVE' |
| Creates an archive, and makes it the current archive (required for |
| many other commands). The new archive is created with a temporary |
| name; it is not actually saved as ARCHIVE until you use `SAVE'. |
| You can overwrite existing archives; similarly, the contents of any |
| existing file named ARCHIVE will not be destroyed until `SAVE'. |
| |
| `DELETE MODULE, MODULE, ... MODULE' |
| Delete each listed MODULE from the current archive; equivalent to |
| `ar -d ARCHIVE MODULE ... MODULE'. |
| |
| Requires prior use of `OPEN' or `CREATE'. |
| |
| `DIRECTORY ARCHIVE (MODULE, ... MODULE)' |
| `DIRECTORY ARCHIVE (MODULE, ... MODULE) OUTPUTFILE' |
| List each named MODULE present in ARCHIVE. The separate command |
| `VERBOSE' specifies the form of the output: when verbose output is |
| off, output is like that of `ar -t ARCHIVE MODULE...'. When |
| verbose output is on, the listing is like `ar -tv ARCHIVE |
| MODULE...'. |
| |
| Output normally goes to the standard output stream; however, if you |
| specify OUTPUTFILE as a final argument, `ar' directs the output to |
| that file. |
| |
| `END' |
| Exit from `ar', with a `0' exit code to indicate successful |
| completion. This command does not save the output file; if you |
| have changed the current archive since the last `SAVE' command, |
| those changes are lost. |
| |
| `EXTRACT MODULE, MODULE, ... MODULE' |
| Extract each named MODULE from the current archive, writing them |
| into the current directory as separate files. Equivalent to `ar -x |
| ARCHIVE MODULE...'. |
| |
| Requires prior use of `OPEN' or `CREATE'. |
| |
| `LIST' |
| Display full contents of the current archive, in "verbose" style |
| regardless of the state of `VERBOSE'. The effect is like `ar tv |
| ARCHIVE'. (This single command is a GNU `ar' enhancement, rather |
| than present for MRI compatibility.) |
| |
| Requires prior use of `OPEN' or `CREATE'. |
| |
| `OPEN ARCHIVE' |
| Opens an existing archive for use as the current archive (required |
| for many other commands). Any changes as the result of subsequent |
| commands will not actually affect ARCHIVE until you next use |
| `SAVE'. |
| |
| `REPLACE MODULE, MODULE, ... MODULE' |
| In the current archive, replace each existing MODULE (named in the |
| `REPLACE' arguments) from files in the current working directory. |
| To execute this command without errors, both the file, and the |
| module in the current archive, must exist. |
| |
| Requires prior use of `OPEN' or `CREATE'. |
| |
| `VERBOSE' |
| Toggle an internal flag governing the output from `DIRECTORY'. |
| When the flag is on, `DIRECTORY' output matches output from `ar |
| -tv '.... |
| |
| `SAVE' |
| Commit your changes to the current archive, and actually save it |
| as a file with the name specified in the last `CREATE' or `OPEN' |
| command. |
| |
| Requires prior use of `OPEN' or `CREATE'. |
| |
| |
| File: binutils.info, Node: nm, Next: objcopy, Prev: ar, Up: Top |
| |
| nm |
| ** |
| |
| nm [ -a | --debug-syms ] [ -g | --extern-only ] |
| [ -B ] [ -C | --demangle[=STYLE] ] [ -D | --dynamic ] |
| [ -s | --print-armap ] [ -A | -o | --print-file-name ] |
| [ -n | -v | --numeric-sort ] [ -p | --no-sort ] |
| [ -r | --reverse-sort ] [ --size-sort ] [ -u | --undefined-only ] |
| [ -t RADIX | --radix=RADIX ] [ -P | --portability ] |
| [ --target=BFDNAME ] [ -f FORMAT | --format=FORMAT ] |
| [ --defined-only ] [-l | --line-numbers ] [ --no-demangle ] |
| [ -V | --version ] [ -X 32_64 ] [ --help ] [ OBJFILE... ] |
| |
| GNU `nm' lists the symbols from object files OBJFILE.... If no |
| object files are listed as arguments, `nm' assumes the file `a.out'. |
| |
| For each symbol, `nm' shows: |
| |
| * The symbol value, in the radix selected by options (see below), or |
| hexadecimal by default. |
| |
| * The symbol type. At least the following types are used; others |
| are, as well, depending on the object file format. If lowercase, |
| the symbol is local; if uppercase, the symbol is global (external). |
| |
| `A' |
| The symbol's value is absolute, and will not be changed by |
| further linking. |
| |
| `B' |
| The symbol is in the uninitialized data section (known as |
| BSS). |
| |
| `C' |
| The symbol is common. Common symbols are uninitialized data. |
| When linking, multiple common symbols may appear with the |
| same name. If the symbol is defined anywhere, the common |
| symbols are treated as undefined references. For more |
| details on common symbols, see the discussion of -warn-common |
| in *Note Linker options: (ld.info)Options. |
| |
| `D' |
| The symbol is in the initialized data section. |
| |
| `G' |
| The symbol is in an initialized data section for small |
| objects. Some object file formats permit more efficient |
| access to small data objects, such as a global int variable |
| as opposed to a large global array. |
| |
| `I' |
| The symbol is an indirect reference to another symbol. This |
| is a GNU extension to the a.out object file format which is |
| rarely used. |
| |
| `N' |
| The symbol is a debugging symbol. |
| |
| `R' |
| The symbol is in a read only data section. |
| |
| `S' |
| The symbol is in an uninitialized data section for small |
| objects. |
| |
| `T' |
| The symbol is in the text (code) section. |
| |
| `U' |
| The symbol is undefined. |
| |
| `V' |
| The symbol is a weak object. When a weak defined symbol is |
| linked with a normal defined symbol, the normal defined |
| symbol is used with no error. When a weak undefined symbol |
| is linked and the symbol is not defined, the value of the |
| weak symbol becomes zero with no error. |
| |
| `W' |
| The symbol is a weak symbol that has not been specifically |
| tagged as a weak object symbol. When a weak defined symbol |
| is linked with a normal defined symbol, the normal defined |
| symbol is used with no error. When a weak undefined symbol |
| is linked and the symbol is not defined, the value of the |
| weak symbol becomes zero with no error. |
| |
| `-' |
| The symbol is a stabs symbol in an a.out object file. In |
| this case, the next values printed are the stabs other field, |
| the stabs desc field, and the stab type. Stabs symbols are |
| used to hold debugging information; for more information, see |
| *Note Stabs: (stabs.info)Top. |
| |
| `?' |
| The symbol type is unknown, or object file format specific. |
| |
| * The symbol name. |
| |
| The long and short forms of options, shown here as alternatives, are |
| equivalent. |
| |
| `-A' |
| `-o' |
| `--print-file-name' |
| Precede each symbol by the name of the input file (or archive |
| member) in which it was found, rather than identifying the input |
| file once only, before all of its symbols. |
| |
| `-a' |
| `--debug-syms' |
| Display all symbols, even debugger-only symbols; normally these |
| are not listed. |
| |
| `-B' |
| The same as `--format=bsd' (for compatibility with the MIPS `nm'). |
| |
| `-C' |
| `--demangle[=STYLE]' |
| Decode ("demangle") low-level symbol names into user-level names. |
| Besides removing any initial underscore prepended by the system, |
| this makes C++ function names readable. Different compilers have |
| different mangling styles. The optional demangling style argument |
| can be used to choose an appropriate demangling style for your |
| compiler. *Note c++filt::, for more information on demangling. |
| |
| `--no-demangle' |
| Do not demangle low-level symbol names. This is the default. |
| |
| `-D' |
| `--dynamic' |
| Display the dynamic symbols rather than the normal symbols. This |
| is only meaningful for dynamic objects, such as certain types of |
| shared libraries. |
| |
| `-f FORMAT' |
| `--format=FORMAT' |
| Use the output format FORMAT, which can be `bsd', `sysv', or |
| `posix'. The default is `bsd'. Only the first character of |
| FORMAT is significant; it can be either upper or lower case. |
| |
| `-g' |
| `--extern-only' |
| Display only external symbols. |
| |
| `-l' |
| `--line-numbers' |
| For each symbol, use debugging information to try to find a |
| filename and line number. For a defined symbol, look for the line |
| number of the address of the symbol. For an undefined symbol, |
| look for the line number of a relocation entry which refers to the |
| symbol. If line number information can be found, print it after |
| the other symbol information. |
| |
| `-n' |
| `-v' |
| `--numeric-sort' |
| Sort symbols numerically by their addresses, rather than |
| alphabetically by their names. |
| |
| `-p' |
| `--no-sort' |
| Do not bother to sort the symbols in any order; print them in the |
| order encountered. |
| |
| `-P' |
| `--portability' |
| Use the POSIX.2 standard output format instead of the default |
| format. Equivalent to `-f posix'. |
| |
| `-s' |
| `--print-armap' |
| When listing symbols from archive members, include the index: a |
| mapping (stored in the archive by `ar' or `ranlib') of which |
| modules contain definitions for which names. |
| |
| `-r' |
| `--reverse-sort' |
| Reverse the order of the sort (whether numeric or alphabetic); let |
| the last come first. |
| |
| `--size-sort' |
| Sort symbols by size. The size is computed as the difference |
| between the value of the symbol and the value of the symbol with |
| the next higher value. The size of the symbol is printed, rather |
| than the value. |
| |
| `-t RADIX' |
| `--radix=RADIX' |
| Use RADIX as the radix for printing the symbol values. It must be |
| `d' for decimal, `o' for octal, or `x' for hexadecimal. |
| |
| `--target=BFDNAME' |
| Specify an object code format other than your system's default |
| format. *Note Target Selection::, for more information. |
| |
| `-u' |
| `--undefined-only' |
| Display only undefined symbols (those external to each object |
| file). |
| |
| `--defined-only' |
| Display only defined symbols for each object file. |
| |
| `-V' |
| `--version' |
| Show the version number of `nm' and exit. |
| |
| `-X' |
| This option is ignored for compatibility with the AIX version of |
| `nm'. It takes one parameter which must be the string `32_64'. |
| The default mode of AIX `nm' corresponds to `-X 32', which is not |
| supported by GNU `nm'. |
| |
| `--help' |
| Show a summary of the options to `nm' and exit. |
| |
| |
| File: binutils.info, Node: objcopy, Next: objdump, Prev: nm, Up: Top |
| |
| objcopy |
| ******* |
| |
| objcopy [ -F BFDNAME | --target=BFDNAME ] |
| [ -I BFDNAME | --input-target=BFDNAME ] |
| [ -O BFDNAME | --output-target=BFDNAME ] |
| [ -S | --strip-all ] [ -g | --strip-debug ] |
| [ -K SYMBOLNAME | --keep-symbol=SYMBOLNAME ] |
| [ -N SYMBOLNAME | --strip-symbol=SYMBOLNAME ] |
| [ -G SYMBOLNAME | --keep-global-symbol=SYMBOLNAME] |
| [ -L SYMBOLNAME | --localize-symbol=SYMBOLNAME ] |
| [ -W SYMBOLNAME | --weaken-symbol=SYMBOLNAME ] |
| [ -x | --discard-all ] [ -X | --discard-locals ] |
| [ -b BYTE | --byte=BYTE ] |
| [ -i INTERLEAVE | --interleave=INTERLEAVE ] |
| [ -j SECTIONNAME | --only-section=SECTIONNAME ] |
| [ -R SECTIONNAME | --remove-section=SECTIONNAME ] |
| [ -p | --preserve-dates ] [ --debugging ] |
| [ --gap-fill=VAL ] [ --pad-to=ADDRESS ] |
| [ --set-start=VAL ] [ --adjust-start=INCR ] |
| [ --change-addresses=INCR ] |
| [ --change-section-address SECTION{=,+,-}VAL ] |
| [ --change-section-lma SECTION{=,+,-}VAL ] |
| [ --change-section-vma SECTION{=,+,-}VAL ] |
| [ --change-warnings ] [ --no-change-warnings ] |
| [ --set-section-flags SECTION=FLAGS ] |
| [ --add-section SECTIONNAME=FILENAME ] |
| [ --change-leading-char ] [ --remove-leading-char ] |
| [ --srec-len=IVAL ] [ --srec-forceS3 ] |
| [ --redefine-sym OLD=NEW ] [ --weaken ] |
| [ --keep-symbols=FILENAME ] |
| [ --strip-symbols=FILENAME ] |
| [ --keep-global-symbols=FILENAME ] |
| [ --localize-symbols=FILENAME ] |
| [ --weaken-symbols=FILENAME ] |
| [ -v | --verbose ] [ -V | --version ] [ --help ] |
| INFILE [OUTFILE] |
| |
| The GNU `objcopy' utility copies the contents of an object file to |
| another. `objcopy' uses the GNU BFD Library to read and write the |
| object files. It can write the destination object file in a format |
| different from that of the source object file. The exact behavior of |
| `objcopy' is controlled by command-line options. Note that `objcopy' |
| should be able to copy a fully linked file between any two formats. |
| However, copying a relocatable object file between any two formats may |
| not work as expected. |
| |
| `objcopy' creates temporary files to do its translations and deletes |
| them afterward. `objcopy' uses BFD to do all its translation work; it |
| has access to all the formats described in BFD and thus is able to |
| recognize most formats without being told explicitly. *Note BFD: |
| (ld.info)BFD. |
| |
| `objcopy' can be used to generate S-records by using an output |
| target of `srec' (e.g., use `-O srec'). |
| |
| `objcopy' can be used to generate a raw binary file by using an |
| output target of `binary' (e.g., use `-O binary'). When `objcopy' |
| generates a raw binary file, it will essentially produce a memory dump |
| of the contents of the input object file. All symbols and relocation |
| information will be discarded. The memory dump will start at the load |
| address of the lowest section copied into the output file. |
| |
| When generating an S-record or a raw binary file, it may be helpful |
| to use `-S' to remove sections containing debugging information. In |
| some cases `-R' will be useful to remove sections which contain |
| information that is not needed by the binary file. |
| |
| Note - `objcopy' is not able to change the endianness of its input |
| files. If the input format has an endianness, (some formats do not), |
| `objcopy' can only copy the inputs into file formats that have the same |
| endianness or which have no endianness (eg `srec'). |
| |
| `INFILE' |
| `OUTFILE' |
| The input and output files, respectively. If you do not specify |
| OUTFILE, `objcopy' creates a temporary file and destructively |
| renames the result with the name of INFILE. |
| |
| `-I BFDNAME' |
| `--input-target=BFDNAME' |
| Consider the source file's object format to be BFDNAME, rather than |
| attempting to deduce it. *Note Target Selection::, for more |
| information. |
| |
| `-O BFDNAME' |
| `--output-target=BFDNAME' |
| Write the output file using the object format BFDNAME. *Note |
| Target Selection::, for more information. |
| |
| `-F BFDNAME' |
| `--target=BFDNAME' |
| Use BFDNAME as the object format for both the input and the output |
| file; i.e., simply transfer data from source to destination with no |
| translation. *Note Target Selection::, for more information. |
| |
| `-j SECTIONNAME' |
| `--only-section=SECTIONNAME' |
| Copy only the named section from the input file to the output file. |
| This option may be given more than once. Note that using this |
| option inappropriately may make the output file unusable. |
| |
| `-R SECTIONNAME' |
| `--remove-section=SECTIONNAME' |
| Remove any section named SECTIONNAME from the output file. This |
| option may be given more than once. Note that using this option |
| inappropriately may make the output file unusable. |
| |
| `-S' |
| `--strip-all' |
| Do not copy relocation and symbol information from the source file. |
| |
| `-g' |
| `--strip-debug' |
| Do not copy debugging symbols from the source file. |
| |
| `--strip-unneeded' |
| Strip all symbols that are not needed for relocation processing. |
| |
| `-K SYMBOLNAME' |
| `--keep-symbol=SYMBOLNAME' |
| Copy only symbol SYMBOLNAME from the source file. This option may |
| be given more than once. |
| |
| `-N SYMBOLNAME' |
| `--strip-symbol=SYMBOLNAME' |
| Do not copy symbol SYMBOLNAME from the source file. This option |
| may be given more than once. |
| |
| `-G SYMBOLNAME' |
| `--keep-global-symbol=SYMBOLNAME' |
| Keep only symbol SYMBOLNAME global. Make all other symbols local |
| to the file, so that they are not visible externally. This option |
| may be given more than once. |
| |
| `-L SYMBOLNAME' |
| `--localize-symbol=SYMBOLNAME' |
| Make symbol SYMBOLNAME local to the file, so that it is not |
| visible externally. This option may be given more than once. |
| |
| `-W SYMBOLNAME' |
| `--weaken-symbol=SYMBOLNAME' |
| Make symbol SYMBOLNAME weak. This option may be given more than |
| once. |
| |
| `-x' |
| `--discard-all' |
| Do not copy non-global symbols from the source file. |
| |
| `-X' |
| `--discard-locals' |
| Do not copy compiler-generated local symbols. (These usually |
| start with `L' or `.'.) |
| |
| `-b BYTE' |
| `--byte=BYTE' |
| Keep only every BYTEth byte of the input file (header data is not |
| affected). BYTE can be in the range from 0 to INTERLEAVE-1, where |
| INTERLEAVE is given by the `-i' or `--interleave' option, or the |
| default of 4. This option is useful for creating files to program |
| ROM. It is typically used with an `srec' output target. |
| |
| `-i INTERLEAVE' |
| `--interleave=INTERLEAVE' |
| Only copy one out of every INTERLEAVE bytes. Select which byte to |
| copy with the -B or `--byte' option. The default is 4. `objcopy' |
| ignores this option if you do not specify either `-b' or `--byte'. |
| |
| `-p' |
| `--preserve-dates' |
| Set the access and modification dates of the output file to be the |
| same as those of the input file. |
| |
| `--debugging' |
| Convert debugging information, if possible. This is not the |
| default because only certain debugging formats are supported, and |
| the conversion process can be time consuming. |
| |
| `--gap-fill VAL' |
| Fill gaps between sections with VAL. This operation applies to |
| the _load address_ (LMA) of the sections. It is done by increasing |
| the size of the section with the lower address, and filling in the |
| extra space created with VAL. |
| |
| `--pad-to ADDRESS' |
| Pad the output file up to the load address ADDRESS. This is done |
| by increasing the size of the last section. The extra space is |
| filled in with the value specified by `--gap-fill' (default zero). |
| |
| `--set-start VAL' |
| Set the start address of the new file to VAL. Not all object file |
| formats support setting the start address. |
| |
| `--change-start INCR' |
| `--adjust-start INCR' |
| Change the start address by adding INCR. Not all object file |
| formats support setting the start address. |
| |
| `--change-addresses INCR' |
| `--adjust-vma INCR' |
| Change the VMA and LMA addresses of all sections, as well as the |
| start address, by adding INCR. Some object file formats do not |
| permit section addresses to be changed arbitrarily. Note that |
| this does not relocate the sections; if the program expects |
| sections to be loaded at a certain address, and this option is |
| used to change the sections such that they are loaded at a |
| different address, the program may fail. |
| |
| `--change-section-address SECTION{=,+,-}VAL' |
| `--adjust-section-vma SECTION{=,+,-}VAL' |
| Set or change both the VMA address and the LMA address of the named |
| SECTION. If `=' is used, the section address is set to VAL. |
| Otherwise, VAL is added to or subtracted from the section address. |
| See the comments under `--change-addresses', above. If SECTION |
| does not exist in the input file, a warning will be issued, unless |
| `--no-change-warnings' is used. |
| |
| `--change-section-lma SECTION{=,+,-}VAL' |
| Set or change the LMA address of the named SECTION. The LMA |
| address is the address where the section will be loaded into |
| memory at program load time. Normally this is the same as the VMA |
| address, which is the address of the section at program run time, |
| but on some systems, especially those where a program is held in |
| ROM, the two can be different. If `=' is used, the section |
| address is set to VAL. Otherwise, VAL is added to or subtracted |
| from the section address. See the comments under |
| `--change-addresses', above. If SECTION does not exist in the |
| input file, a warning will be issued, unless |
| `--no-change-warnings' is used. |
| |
| `--change-section-vma SECTION{=,+,-}VAL' |
| Set or change the VMA address of the named SECTION. The VMA |
| address is the address where the section will be located once the |
| program has started executing. Normally this is the same as the |
| LMA address, which is the address where the section will be loaded |
| into memory, but on some systems, especially those where a program |
| is held in ROM, the two can be different. If `=' is used, the |
| section address is set to VAL. Otherwise, VAL is added to or |
| subtracted from the section address. See the comments under |
| `--change-addresses', above. If SECTION does not exist in the |
| input file, a warning will be issued, unless |
| `--no-change-warnings' is used. |
| |
| `--change-warnings' |
| `--adjust-warnings' |
| If `--change-section-address' or `--change-section-lma' or |
| `--change-section-vma' is used, and the named section does not |
| exist, issue a warning. This is the default. |
| |
| `--no-change-warnings' |
| `--no-adjust-warnings' |
| Do not issue a warning if `--change-section-address' or |
| `--adjust-section-lma' or `--adjust-section-vma' is used, even if |
| the named section does not exist. |
| |
| `--set-section-flags SECTION=FLAGS' |
| Set the flags for the named section. The FLAGS argument is a |
| comma separated string of flag names. The recognized names are |
| `alloc', `contents', `load', `noload', `readonly', `code', `data', |
| `rom', `share', and `debug'. You can set the `contents' flag for |
| a section which does not have contents, but it is not meaningful |
| to clear the `contents' flag of a section which does have |
| contents-just remove the section instead. Not all flags are |
| meaningful for all object file formats. |
| |
| `--add-section SECTIONNAME=FILENAME' |
| Add a new section named SECTIONNAME while copying the file. The |
| contents of the new section are taken from the file FILENAME. The |
| size of the section will be the size of the file. This option only |
| works on file formats which can support sections with arbitrary |
| names. |
| |
| `--change-leading-char' |
| Some object file formats use special characters at the start of |
| symbols. The most common such character is underscore, which |
| compilers often add before every symbol. This option tells |
| `objcopy' to change the leading character of every symbol when it |
| converts between object file formats. If the object file formats |
| use the same leading character, this option has no effect. |
| Otherwise, it will add a character, or remove a character, or |
| change a character, as appropriate. |
| |
| `--remove-leading-char' |
| If the first character of a global symbol is a special symbol |
| leading character used by the object file format, remove the |
| character. The most common symbol leading character is |
| underscore. This option will remove a leading underscore from all |
| global symbols. This can be useful if you want to link together |
| objects of different file formats with different conventions for |
| symbol names. This is different from `--change-leading-char' |
| because it always changes the symbol name when appropriate, |
| regardless of the object file format of the output file. |
| |
| `--srec-len=IVAL' |
| Meaningful only for srec output. Set the maximum length of the |
| Srecords being produced to IVAL. This length covers both address, |
| data and crc fields. |
| |
| `--srec-forceS3' |
| Meaningful only for srec output. Avoid generation of S1/S2 |
| records, creating S3-only record format. |
| |
| `--redefine-sym OLD=NEW' |
| Change the name of a symbol OLD, to NEW. This can be useful when |
| one is trying link two things together for which you have no |
| source, and there are name collisions. |
| |
| `--weaken' |
| Change all global symbols in the file to be weak. This can be |
| useful when building an object which will be linked against other |
| objects using the `-R' option to the linker. This option is only |
| effective when using an object file format which supports weak |
| symbols. |
| |
| `--keep-symbols=FILENAME' |
| Apply `--keep-symbol' option to each symbol listed in the file |
| FILENAME. FILENAME is simply a flat file, with one symbol name |
| per line. Line comments may be introduced by the hash character. |
| This option may be given more than once. |
| |
| `--strip-symbols=FILENAME' |
| Apply `--strip-symbol' option to each symbol listed in the file |
| FILENAME. FILENAME is simply a flat file, with one symbol name |
| per line. Line comments may be introduced by the hash character. |
| This option may be given more than once. |
| |
| `--keep-global-symbols=FILENAME' |
| Apply `--keep-global-symbol' option to each symbol listed in the |
| file FILENAME. FILENAME is simply a flat file, with one symbol |
| name per line. Line comments may be introduced by the hash |
| character. This option may be given more than once. |
| |
| `--localize-symbols=FILENAME' |
| Apply `--localize-symbol' option to each symbol listed in the file |
| FILENAME. FILENAME is simply a flat file, with one symbol name |
| per line. Line comments may be introduced by the hash character. |
| This option may be given more than once. |
| |
| `--weaken-symbols=FILENAME' |
| Apply `--weaken-symbol' option to each symbol listed in the file |
| FILENAME. FILENAME is simply a flat file, with one symbol name |
| per line. Line comments may be introduced by the hash character. |
| This option may be given more than once. |
| |
| `-V' |
| `--version' |
| Show the version number of `objcopy'. |
| |
| `-v' |
| `--verbose' |
| Verbose output: list all object files modified. In the case of |
| archives, `objcopy -V' lists all members of the archive. |
| |
| `--help' |
| Show a summary of the options to `objcopy'. |
| |