| blob | a0bb64e371aca6db70f1cf7bf60931b17396015c |
1 This is binutils.info, produced by makeinfo version 4.0 from
2 binutils.texi.
4 START-INFO-DIR-ENTRY
5 * Binutils: (binutils). The GNU binary utilities.
6 * ar: (binutils)ar. Create, modify, and extract from archives
7 * nm: (binutils)nm. List symbols from object files
8 * objcopy: (binutils)objcopy. Copy and translate object files
9 * objdump: (binutils)objdump. Display information from object files
10 * ranlib: (binutils)ranlib. Generate index to archive contents
11 * readelf: (binutils)readelf. Display the contents of ELF format files.
12 * size: (binutils)size. List section sizes and total size
13 * strings: (binutils)strings. List printable strings from files
14 * strip: (binutils)strip. Discard symbols
15 * c++filt: (binutils)c++filt. Filter to demangle encoded C++ symbols
16 * cxxfilt: (binutils)c++filt. MS-DOS name for c++filt
17 * addr2line: (binutils)addr2line. Convert addresses to file and line
18 * nlmconv: (binutils)nlmconv. Converts object code into an NLM
19 * windres: (binutils)windres. Manipulate Windows resources
20 * dlltool: (binutils)dlltool. Create files needed to build and use DLLs
21 END-INFO-DIR-ENTRY
23 Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001 Free
24 Software Foundation, Inc.
26 Permission is granted to copy, distribute and/or modify this document
27 under the terms of the GNU Free Documentation License, Version 1.1
28 or any later version published by the Free Software Foundation;
29 with no Invariant Sections, with no Front-Cover Texts, and with no
30 Back-Cover Texts. A copy of the license is included in the
31 section entitled "GNU Free Documentation License".
33 \x1f
34 File: binutils.info, Node: Top, Next: ar, Up: (dir)
36 Introduction
37 ************
39 This brief manual contains preliminary documentation for the GNU
40 binary utilities (collectively version 2.11.1):
42 This document is distributed under the terms of the GNU Free
43 Documentation License. A copy of the license is included in the
44 section entitled "GNU Free Documentation License".
46 * Menu:
48 * ar:: Create, modify, and extract from archives
49 * nm:: List symbols from object files
50 * objcopy:: Copy and translate object files
51 * objdump:: Display information from object files
52 * ranlib:: Generate index to archive contents
53 * readelf:: Display the contents of ELF format files.
54 * size:: List section sizes and total size
55 * strings:: List printable strings from files
56 * strip:: Discard symbols
57 * c++filt:: Filter to demangle encoded C++ symbols
58 * cxxfilt: c++filt. MS-DOS name for c++filt
59 * addr2line:: Convert addresses to file and line
60 * nlmconv:: Converts object code into an NLM
61 * windres:: Manipulate Windows resources
62 * dlltool:: Create files needed to build and use DLLs
63 * Selecting The Target System:: How these utilities determine the target.
64 * Reporting Bugs:: Reporting Bugs
65 * GNU Free Documentation License:: GNU Free Documentation License
66 * Index:: Index
68 \x1f
69 File: binutils.info, Node: ar, Next: nm, Prev: Top, Up: Top
71 ar
72 **
74 ar [-]P[MOD [RELPOS] [COUNT]] ARCHIVE [MEMBER...]
75 ar -M [ <mri-script ]
77 The GNU `ar' program creates, modifies, and extracts from archives.
78 An "archive" is a single file holding a collection of other files in a
79 structure that makes it possible to retrieve the original individual
80 files (called "members" of the archive).
82 The original files' contents, mode (permissions), timestamp, owner,
83 and group are preserved in the archive, and can be restored on
84 extraction.
86 GNU `ar' can maintain archives whose members have names of any
87 length; however, depending on how `ar' is configured on your system, a
88 limit on member-name length may be imposed for compatibility with
89 archive formats maintained with other tools. If it exists, the limit
90 is often 15 characters (typical of formats related to a.out) or 16
91 characters (typical of formats related to coff).
93 `ar' is considered a binary utility because archives of this sort
94 are most often used as "libraries" holding commonly needed subroutines.
96 `ar' creates an index to the symbols defined in relocatable object
97 modules in the archive when you specify the modifier `s'. Once
98 created, this index is updated in the archive whenever `ar' makes a
99 change to its contents (save for the `q' update operation). An archive
100 with such an index speeds up linking to the library, and allows
101 routines in the library to call each other without regard to their
102 placement in the archive.
104 You may use `nm -s' or `nm --print-armap' to list this index table.
105 If an archive lacks the table, another form of `ar' called `ranlib' can
106 be used to add just the table.
108 GNU `ar' is designed to be compatible with two different facilities.
109 You can control its activity using command-line options, like the
110 different varieties of `ar' on Unix systems; or, if you specify the
111 single command-line option `-M', you can control it with a script
112 supplied via standard input, like the MRI "librarian" program.
114 * Menu:
116 * ar cmdline:: Controlling `ar' on the command line
117 * ar scripts:: Controlling `ar' with a script
119 \x1f
120 File: binutils.info, Node: ar cmdline, Next: ar scripts, Up: ar
122 Controlling `ar' on the command line
123 ====================================
125 ar [-X32_64] [-]P[MOD [RELPOS] [COUNT]] ARCHIVE [MEMBER...]
127 When you use `ar' in the Unix style, `ar' insists on at least two
128 arguments to execute: one keyletter specifying the _operation_
129 (optionally accompanied by other keyletters specifying _modifiers_),
130 and the archive name to act on.
132 Most operations can also accept further MEMBER arguments, specifying
133 particular files to operate on.
135 GNU `ar' allows you to mix the operation code P and modifier flags
136 MOD in any order, within the first command-line argument.
138 If you wish, you may begin the first command-line argument with a
139 dash.
141 The P keyletter specifies what operation to execute; it may be any
142 of the following, but you must specify only one of them:
144 `d'
145 _Delete_ modules from the archive. Specify the names of modules to
146 be deleted as MEMBER...; the archive is untouched if you specify
147 no files to delete.
149 If you specify the `v' modifier, `ar' lists each module as it is
150 deleted.
152 `m'
153 Use this operation to _move_ members in an archive.
155 The ordering of members in an archive can make a difference in how
156 programs are linked using the library, if a symbol is defined in
157 more than one member.
159 If no modifiers are used with `m', any members you name in the
160 MEMBER arguments are moved to the _end_ of the archive; you can
161 use the `a', `b', or `i' modifiers to move them to a specified
162 place instead.
164 `p'
165 _Print_ the specified members of the archive, to the standard
166 output file. If the `v' modifier is specified, show the member
167 name before copying its contents to standard output.
169 If you specify no MEMBER arguments, all the files in the archive
170 are printed.
172 `q'
173 _Quick append_; Historically, add the files MEMBER... to the end of
174 ARCHIVE, without checking for replacement.
176 The modifiers `a', `b', and `i' do _not_ affect this operation;
177 new members are always placed at the end of the archive.
179 The modifier `v' makes `ar' list each file as it is appended.
181 Since the point of this operation is speed, the archive's symbol
182 table index is not updated, even if it already existed; you can
183 use `ar s' or `ranlib' explicitly to update the symbol table index.
185 However, too many different systems assume quick append rebuilds
186 the index, so GNU ar implements `q' as a synonym for `r'.
188 `r'
189 Insert the files MEMBER... into ARCHIVE (with _replacement_). This
190 operation differs from `q' in that any previously existing members
191 are deleted if their names match those being added.
193 If one of the files named in MEMBER... does not exist, `ar'
194 displays an error message, and leaves undisturbed any existing
195 members of the archive matching that name.
197 By default, new members are added at the end of the file; but you
198 may use one of the modifiers `a', `b', or `i' to request placement
199 relative to some existing member.
201 The modifier `v' used with this operation elicits a line of output
202 for each file inserted, along with one of the letters `a' or `r'
203 to indicate whether the file was appended (no old member deleted)
204 or replaced.
206 `t'
207 Display a _table_ listing the contents of ARCHIVE, or those of the
208 files listed in MEMBER... that are present in the archive.
209 Normally only the member name is shown; if you also want to see
210 the modes (permissions), timestamp, owner, group, and size, you can
211 request that by also specifying the `v' modifier.
213 If you do not specify a MEMBER, all files in the archive are
214 listed.
216 If there is more than one file with the same name (say, `fie') in
217 an archive (say `b.a'), `ar t b.a fie' lists only the first
218 instance; to see them all, you must ask for a complete listing--in
219 our example, `ar t b.a'.
221 `x'
222 _Extract_ members (named MEMBER) from the archive. You can use
223 the `v' modifier with this operation, to request that `ar' list
224 each name as it extracts it.
226 If you do not specify a MEMBER, all files in the archive are
227 extracted.
229 A number of modifiers (MOD) may immediately follow the P keyletter,
230 to specify variations on an operation's behavior:
232 `a'
233 Add new files _after_ an existing member of the archive. If you
234 use the modifier `a', the name of an existing archive member must
235 be present as the RELPOS argument, before the ARCHIVE
236 specification.
238 `b'
239 Add new files _before_ an existing member of the archive. If you
240 use the modifier `b', the name of an existing archive member must
241 be present as the RELPOS argument, before the ARCHIVE
242 specification. (same as `i').
244 `c'
245 _Create_ the archive. The specified ARCHIVE is always created if
246 it did not exist, when you request an update. But a warning is
247 issued unless you specify in advance that you expect to create it,
248 by using this modifier.
250 `f'
251 Truncate names in the archive. GNU `ar' will normally permit file
252 names of any length. This will cause it to create archives which
253 are not compatible with the native `ar' program on some systems.
254 If this is a concern, the `f' modifier may be used to truncate file
255 names when putting them in the archive.
257 `i'
258 Insert new files _before_ an existing member of the archive. If
259 you use the modifier `i', the name of an existing archive member
260 must be present as the RELPOS argument, before the ARCHIVE
261 specification. (same as `b').
263 `l'
264 This modifier is accepted but not used.
266 `N'
267 Uses the COUNT parameter. This is used if there are multiple
268 entries in the archive with the same name. Extract or delete
269 instance COUNT of the given name from the archive.
271 `o'
272 Preserve the _original_ dates of members when extracting them. If
273 you do not specify this modifier, files extracted from the archive
274 are stamped with the time of extraction.
276 `P'
277 Use the full path name when matching names in the archive. GNU
278 `ar' can not create an archive with a full path name (such archives
279 are not POSIX complaint), but other archive creators can. This
280 option will cause GNU `ar' to match file names using a complete
281 path name, which can be convenient when extracting a single file
282 from an archive created by another tool.
284 `s'
285 Write an object-file index into the archive, or update an existing
286 one, even if no other change is made to the archive. You may use
287 this modifier flag either with any operation, or alone. Running
288 `ar s' on an archive is equivalent to running `ranlib' on it.
290 `S'
291 Do not generate an archive symbol table. This can speed up
292 building a large library in several steps. The resulting archive
293 can not be used with the linker. In order to build a symbol
294 table, you must omit the `S' modifier on the last execution of
295 `ar', or you must run `ranlib' on the archive.
297 `u'
298 Normally, `ar r'... inserts all files listed into the archive. If
299 you would like to insert _only_ those of the files you list that
300 are newer than existing members of the same names, use this
301 modifier. The `u' modifier is allowed only for the operation `r'
302 (replace). In particular, the combination `qu' is not allowed,
303 since checking the timestamps would lose any speed advantage from
304 the operation `q'.
306 `v'
307 This modifier requests the _verbose_ version of an operation. Many
308 operations display additional information, such as filenames
309 processed, when the modifier `v' is appended.
311 `V'
312 This modifier shows the version number of `ar'.
314 `ar' ignores an initial option spelt `-X32_64', for compatibility
315 with AIX. The behaviour produced by this option is the default for GNU
316 `ar'. `ar' does not support any of the other `-X' options; in
317 particular, it does not support `-X32' which is the default for AIX
318 `ar'.
320 \x1f
321 File: binutils.info, Node: ar scripts, Prev: ar cmdline, Up: ar
323 Controlling `ar' with a script
324 ==============================
326 ar -M [ <SCRIPT ]
328 If you use the single command-line option `-M' with `ar', you can
329 control its operation with a rudimentary command language. This form
330 of `ar' operates interactively if standard input is coming directly
331 from a terminal. During interactive use, `ar' prompts for input (the
332 prompt is `AR >'), and continues executing even after errors. If you
333 redirect standard input to a script file, no prompts are issued, and
334 `ar' abandons execution (with a nonzero exit code) on any error.
336 The `ar' command language is _not_ designed to be equivalent to the
337 command-line options; in fact, it provides somewhat less control over
338 archives. The only purpose of the command language is to ease the
339 transition to GNU `ar' for developers who already have scripts written
340 for the MRI "librarian" program.
342 The syntax for the `ar' command language is straightforward:
343 * commands are recognized in upper or lower case; for example, `LIST'
344 is the same as `list'. In the following descriptions, commands are
345 shown in upper case for clarity.
347 * a single command may appear on each line; it is the first word on
348 the line.
350 * empty lines are allowed, and have no effect.
352 * comments are allowed; text after either of the characters `*' or
353 `;' is ignored.
355 * Whenever you use a list of names as part of the argument to an `ar'
356 command, you can separate the individual names with either commas
357 or blanks. Commas are shown in the explanations below, for
358 clarity.
360 * `+' is used as a line continuation character; if `+' appears at
361 the end of a line, the text on the following line is considered
362 part of the current command.
364 Here are the commands you can use in `ar' scripts, or when using
365 `ar' interactively. Three of them have special significance:
367 `OPEN' or `CREATE' specify a "current archive", which is a temporary
368 file required for most of the other commands.
370 `SAVE' commits the changes so far specified by the script. Prior to
371 `SAVE', commands affect only the temporary copy of the current archive.
373 `ADDLIB ARCHIVE'
374 `ADDLIB ARCHIVE (MODULE, MODULE, ... MODULE)'
375 Add all the contents of ARCHIVE (or, if specified, each named
376 MODULE from ARCHIVE) to the current archive.
378 Requires prior use of `OPEN' or `CREATE'.
380 `ADDMOD MEMBER, MEMBER, ... MEMBER'
381 Add each named MEMBER as a module in the current archive.
383 Requires prior use of `OPEN' or `CREATE'.
385 `CLEAR'
386 Discard the contents of the current archive, canceling the effect
387 of any operations since the last `SAVE'. May be executed (with no
388 effect) even if no current archive is specified.
390 `CREATE ARCHIVE'
391 Creates an archive, and makes it the current archive (required for
392 many other commands). The new archive is created with a temporary
393 name; it is not actually saved as ARCHIVE until you use `SAVE'.
394 You can overwrite existing archives; similarly, the contents of any
395 existing file named ARCHIVE will not be destroyed until `SAVE'.
397 `DELETE MODULE, MODULE, ... MODULE'
398 Delete each listed MODULE from the current archive; equivalent to
399 `ar -d ARCHIVE MODULE ... MODULE'.
401 Requires prior use of `OPEN' or `CREATE'.
403 `DIRECTORY ARCHIVE (MODULE, ... MODULE)'
404 `DIRECTORY ARCHIVE (MODULE, ... MODULE) OUTPUTFILE'
405 List each named MODULE present in ARCHIVE. The separate command
406 `VERBOSE' specifies the form of the output: when verbose output is
407 off, output is like that of `ar -t ARCHIVE MODULE...'. When
408 verbose output is on, the listing is like `ar -tv ARCHIVE
409 MODULE...'.
411 Output normally goes to the standard output stream; however, if you
412 specify OUTPUTFILE as a final argument, `ar' directs the output to
413 that file.
415 `END'
416 Exit from `ar', with a `0' exit code to indicate successful
417 completion. This command does not save the output file; if you
418 have changed the current archive since the last `SAVE' command,
419 those changes are lost.
421 `EXTRACT MODULE, MODULE, ... MODULE'
422 Extract each named MODULE from the current archive, writing them
423 into the current directory as separate files. Equivalent to `ar -x
424 ARCHIVE MODULE...'.
426 Requires prior use of `OPEN' or `CREATE'.
428 `LIST'
429 Display full contents of the current archive, in "verbose" style
430 regardless of the state of `VERBOSE'. The effect is like `ar tv
431 ARCHIVE'. (This single command is a GNU `ar' enhancement, rather
432 than present for MRI compatibility.)
434 Requires prior use of `OPEN' or `CREATE'.
436 `OPEN ARCHIVE'
437 Opens an existing archive for use as the current archive (required
438 for many other commands). Any changes as the result of subsequent
439 commands will not actually affect ARCHIVE until you next use
440 `SAVE'.
442 `REPLACE MODULE, MODULE, ... MODULE'
443 In the current archive, replace each existing MODULE (named in the
444 `REPLACE' arguments) from files in the current working directory.
445 To execute this command without errors, both the file, and the
446 module in the current archive, must exist.
448 Requires prior use of `OPEN' or `CREATE'.
450 `VERBOSE'
451 Toggle an internal flag governing the output from `DIRECTORY'.
452 When the flag is on, `DIRECTORY' output matches output from `ar
453 -tv '....
455 `SAVE'
456 Commit your changes to the current archive, and actually save it
457 as a file with the name specified in the last `CREATE' or `OPEN'
458 command.
460 Requires prior use of `OPEN' or `CREATE'.
462 \x1f
463 File: binutils.info, Node: nm, Next: objcopy, Prev: ar, Up: Top
465 nm
466 **
468 nm [ -a | --debug-syms ] [ -g | --extern-only ]
469 [ -B ] [ -C | --demangle[=STYLE] ] [ -D | --dynamic ]
470 [ -s | --print-armap ] [ -A | -o | --print-file-name ]
471 [ -n | -v | --numeric-sort ] [ -p | --no-sort ]
472 [ -r | --reverse-sort ] [ --size-sort ] [ -u | --undefined-only ]
473 [ -t RADIX | --radix=RADIX ] [ -P | --portability ]
474 [ --target=BFDNAME ] [ -f FORMAT | --format=FORMAT ]
475 [ --defined-only ] [-l | --line-numbers ] [ --no-demangle ]
476 [ -V | --version ] [ -X 32_64 ] [ --help ] [ OBJFILE... ]
478 GNU `nm' lists the symbols from object files OBJFILE.... If no
479 object files are listed as arguments, `nm' assumes the file `a.out'.
481 For each symbol, `nm' shows:
483 * The symbol value, in the radix selected by options (see below), or
484 hexadecimal by default.
486 * The symbol type. At least the following types are used; others
487 are, as well, depending on the object file format. If lowercase,
488 the symbol is local; if uppercase, the symbol is global (external).
490 `A'
491 The symbol's value is absolute, and will not be changed by
492 further linking.
494 `B'
495 The symbol is in the uninitialized data section (known as
496 BSS).
498 `C'
499 The symbol is common. Common symbols are uninitialized data.
500 When linking, multiple common symbols may appear with the
501 same name. If the symbol is defined anywhere, the common
502 symbols are treated as undefined references. For more
503 details on common symbols, see the discussion of -warn-common
504 in *Note Linker options: (ld.info)Options.
506 `D'
507 The symbol is in the initialized data section.
509 `G'
510 The symbol is in an initialized data section for small
511 objects. Some object file formats permit more efficient
512 access to small data objects, such as a global int variable
513 as opposed to a large global array.
515 `I'
516 The symbol is an indirect reference to another symbol. This
517 is a GNU extension to the a.out object file format which is
518 rarely used.
520 `N'
521 The symbol is a debugging symbol.
523 `R'
524 The symbol is in a read only data section.
526 `S'
527 The symbol is in an uninitialized data section for small
528 objects.
530 `T'
531 The symbol is in the text (code) section.
533 `U'
534 The symbol is undefined.
536 `V'
537 The symbol is a weak object. When a weak defined symbol is
538 linked with a normal defined symbol, the normal defined
539 symbol is used with no error. When a weak undefined symbol
540 is linked and the symbol is not defined, the value of the
541 weak symbol becomes zero with no error.
543 `W'
544 The symbol is a weak symbol that has not been specifically
545 tagged as a weak object symbol. When a weak defined symbol
546 is linked with a normal defined symbol, the normal defined
547 symbol is used with no error. When a weak undefined symbol
548 is linked and the symbol is not defined, the value of the
549 weak symbol becomes zero with no error.
551 `-'
552 The symbol is a stabs symbol in an a.out object file. In
553 this case, the next values printed are the stabs other field,
554 the stabs desc field, and the stab type. Stabs symbols are
555 used to hold debugging information; for more information, see
556 *Note Stabs: (stabs.info)Top.
558 `?'
559 The symbol type is unknown, or object file format specific.
561 * The symbol name.
563 The long and short forms of options, shown here as alternatives, are
564 equivalent.
566 `-A'
567 `-o'
568 `--print-file-name'
569 Precede each symbol by the name of the input file (or archive
570 member) in which it was found, rather than identifying the input
571 file once only, before all of its symbols.
573 `-a'
574 `--debug-syms'
575 Display all symbols, even debugger-only symbols; normally these
576 are not listed.
578 `-B'
579 The same as `--format=bsd' (for compatibility with the MIPS `nm').
581 `-C'
582 `--demangle[=STYLE]'
583 Decode ("demangle") low-level symbol names into user-level names.
584 Besides removing any initial underscore prepended by the system,
585 this makes C++ function names readable. Different compilers have
586 different mangling styles. The optional demangling style argument
587 can be used to choose an appropriate demangling style for your
588 compiler. *Note c++filt::, for more information on demangling.
590 `--no-demangle'
591 Do not demangle low-level symbol names. This is the default.
593 `-D'
594 `--dynamic'
595 Display the dynamic symbols rather than the normal symbols. This
596 is only meaningful for dynamic objects, such as certain types of
597 shared libraries.
599 `-f FORMAT'
600 `--format=FORMAT'
601 Use the output format FORMAT, which can be `bsd', `sysv', or
602 `posix'. The default is `bsd'. Only the first character of
603 FORMAT is significant; it can be either upper or lower case.
605 `-g'
606 `--extern-only'
607 Display only external symbols.
609 `-l'
610 `--line-numbers'
611 For each symbol, use debugging information to try to find a
612 filename and line number. For a defined symbol, look for the line
613 number of the address of the symbol. For an undefined symbol,
614 look for the line number of a relocation entry which refers to the
615 symbol. If line number information can be found, print it after
616 the other symbol information.
618 `-n'
619 `-v'
620 `--numeric-sort'
621 Sort symbols numerically by their addresses, rather than
622 alphabetically by their names.
624 `-p'
625 `--no-sort'
626 Do not bother to sort the symbols in any order; print them in the
627 order encountered.
629 `-P'
630 `--portability'
631 Use the POSIX.2 standard output format instead of the default
632 format. Equivalent to `-f posix'.
634 `-s'
635 `--print-armap'
636 When listing symbols from archive members, include the index: a
637 mapping (stored in the archive by `ar' or `ranlib') of which
638 modules contain definitions for which names.
640 `-r'
641 `--reverse-sort'
642 Reverse the order of the sort (whether numeric or alphabetic); let
643 the last come first.
645 `--size-sort'
646 Sort symbols by size. The size is computed as the difference
647 between the value of the symbol and the value of the symbol with
648 the next higher value. The size of the symbol is printed, rather
649 than the value.
651 `-t RADIX'
652 `--radix=RADIX'
653 Use RADIX as the radix for printing the symbol values. It must be
654 `d' for decimal, `o' for octal, or `x' for hexadecimal.
656 `--target=BFDNAME'
657 Specify an object code format other than your system's default
658 format. *Note Target Selection::, for more information.
660 `-u'
661 `--undefined-only'
662 Display only undefined symbols (those external to each object
663 file).
665 `--defined-only'
666 Display only defined symbols for each object file.
668 `-V'
669 `--version'
670 Show the version number of `nm' and exit.
672 `-X'
673 This option is ignored for compatibility with the AIX version of
674 `nm'. It takes one parameter which must be the string `32_64'.
675 The default mode of AIX `nm' corresponds to `-X 32', which is not
676 supported by GNU `nm'.
678 `--help'
679 Show a summary of the options to `nm' and exit.
681 \x1f
682 File: binutils.info, Node: objcopy, Next: objdump, Prev: nm, Up: Top
684 objcopy
685 *******
687 objcopy [ -F BFDNAME | --target=BFDNAME ]
688 [ -I BFDNAME | --input-target=BFDNAME ]
689 [ -O BFDNAME | --output-target=BFDNAME ]
690 [ -S | --strip-all ] [ -g | --strip-debug ]
691 [ -K SYMBOLNAME | --keep-symbol=SYMBOLNAME ]
692 [ -N SYMBOLNAME | --strip-symbol=SYMBOLNAME ]
693 [ -G SYMBOLNAME | --keep-global-symbol=SYMBOLNAME]
694 [ -L SYMBOLNAME | --localize-symbol=SYMBOLNAME ]
695 [ -W SYMBOLNAME | --weaken-symbol=SYMBOLNAME ]
696 [ -x | --discard-all ] [ -X | --discard-locals ]
697 [ -b BYTE | --byte=BYTE ]
698 [ -i INTERLEAVE | --interleave=INTERLEAVE ]
699 [ -j SECTIONNAME | --only-section=SECTIONNAME ]
700 [ -R SECTIONNAME | --remove-section=SECTIONNAME ]
701 [ -p | --preserve-dates ] [ --debugging ]
702 [ --gap-fill=VAL ] [ --pad-to=ADDRESS ]
703 [ --set-start=VAL ] [ --adjust-start=INCR ]
704 [ --change-addresses=INCR ]
705 [ --change-section-address SECTION{=,+,-}VAL ]
706 [ --change-section-lma SECTION{=,+,-}VAL ]
707 [ --change-section-vma SECTION{=,+,-}VAL ]
708 [ --change-warnings ] [ --no-change-warnings ]
709 [ --set-section-flags SECTION=FLAGS ]
710 [ --add-section SECTIONNAME=FILENAME ]
711 [ --change-leading-char ] [ --remove-leading-char ]
712 [ --srec-len=IVAL ] [ --srec-forceS3 ]
713 [ --redefine-sym OLD=NEW ] [ --weaken ]
714 [ --keep-symbols=FILENAME ]
715 [ --strip-symbols=FILENAME ]
716 [ --keep-global-symbols=FILENAME ]
717 [ --localize-symbols=FILENAME ]
718 [ --weaken-symbols=FILENAME ]
719 [ -v | --verbose ] [ -V | --version ] [ --help ]
720 INFILE [OUTFILE]
722 The GNU `objcopy' utility copies the contents of an object file to
723 another. `objcopy' uses the GNU BFD Library to read and write the
724 object files. It can write the destination object file in a format
725 different from that of the source object file. The exact behavior of
726 `objcopy' is controlled by command-line options. Note that `objcopy'
727 should be able to copy a fully linked file between any two formats.
728 However, copying a relocatable object file between any two formats may
729 not work as expected.
731 `objcopy' creates temporary files to do its translations and deletes
732 them afterward. `objcopy' uses BFD to do all its translation work; it
733 has access to all the formats described in BFD and thus is able to
734 recognize most formats without being told explicitly. *Note BFD:
735 (ld.info)BFD.
737 `objcopy' can be used to generate S-records by using an output
738 target of `srec' (e.g., use `-O srec').
740 `objcopy' can be used to generate a raw binary file by using an
741 output target of `binary' (e.g., use `-O binary'). When `objcopy'
742 generates a raw binary file, it will essentially produce a memory dump
743 of the contents of the input object file. All symbols and relocation
744 information will be discarded. The memory dump will start at the load
745 address of the lowest section copied into the output file.
747 When generating an S-record or a raw binary file, it may be helpful
748 to use `-S' to remove sections containing debugging information. In
749 some cases `-R' will be useful to remove sections which contain
750 information that is not needed by the binary file.
752 Note - `objcopy' is not able to change the endianness of its input
753 files. If the input format has an endianness, (some formats do not),
754 `objcopy' can only copy the inputs into file formats that have the same
755 endianness or which have no endianness (eg `srec').
757 `INFILE'
758 `OUTFILE'
759 The input and output files, respectively. If you do not specify
760 OUTFILE, `objcopy' creates a temporary file and destructively
761 renames the result with the name of INFILE.
763 `-I BFDNAME'
764 `--input-target=BFDNAME'
765 Consider the source file's object format to be BFDNAME, rather than
766 attempting to deduce it. *Note Target Selection::, for more
767 information.
769 `-O BFDNAME'
770 `--output-target=BFDNAME'
771 Write the output file using the object format BFDNAME. *Note
772 Target Selection::, for more information.
774 `-F BFDNAME'
775 `--target=BFDNAME'
776 Use BFDNAME as the object format for both the input and the output
777 file; i.e., simply transfer data from source to destination with no
778 translation. *Note Target Selection::, for more information.
780 `-j SECTIONNAME'
781 `--only-section=SECTIONNAME'
782 Copy only the named section from the input file to the output file.
783 This option may be given more than once. Note that using this
784 option inappropriately may make the output file unusable.
786 `-R SECTIONNAME'
787 `--remove-section=SECTIONNAME'
788 Remove any section named SECTIONNAME from the output file. This
789 option may be given more than once. Note that using this option
790 inappropriately may make the output file unusable.
792 `-S'
793 `--strip-all'
794 Do not copy relocation and symbol information from the source file.
796 `-g'
797 `--strip-debug'
798 Do not copy debugging symbols from the source file.
800 `--strip-unneeded'
801 Strip all symbols that are not needed for relocation processing.
803 `-K SYMBOLNAME'
804 `--keep-symbol=SYMBOLNAME'
805 Copy only symbol SYMBOLNAME from the source file. This option may
806 be given more than once.
808 `-N SYMBOLNAME'
809 `--strip-symbol=SYMBOLNAME'
810 Do not copy symbol SYMBOLNAME from the source file. This option
811 may be given more than once.
813 `-G SYMBOLNAME'
814 `--keep-global-symbol=SYMBOLNAME'
815 Keep only symbol SYMBOLNAME global. Make all other symbols local
816 to the file, so that they are not visible externally. This option
817 may be given more than once.
819 `-L SYMBOLNAME'
820 `--localize-symbol=SYMBOLNAME'
821 Make symbol SYMBOLNAME local to the file, so that it is not
822 visible externally. This option may be given more than once.
824 `-W SYMBOLNAME'
825 `--weaken-symbol=SYMBOLNAME'
826 Make symbol SYMBOLNAME weak. This option may be given more than
827 once.
829 `-x'
830 `--discard-all'
831 Do not copy non-global symbols from the source file.
833 `-X'
834 `--discard-locals'
835 Do not copy compiler-generated local symbols. (These usually
836 start with `L' or `.'.)
838 `-b BYTE'
839 `--byte=BYTE'
840 Keep only every BYTEth byte of the input file (header data is not
841 affected). BYTE can be in the range from 0 to INTERLEAVE-1, where
842 INTERLEAVE is given by the `-i' or `--interleave' option, or the
843 default of 4. This option is useful for creating files to program
844 ROM. It is typically used with an `srec' output target.
846 `-i INTERLEAVE'
847 `--interleave=INTERLEAVE'
848 Only copy one out of every INTERLEAVE bytes. Select which byte to
849 copy with the -B or `--byte' option. The default is 4. `objcopy'
850 ignores this option if you do not specify either `-b' or `--byte'.
852 `-p'
853 `--preserve-dates'
854 Set the access and modification dates of the output file to be the
855 same as those of the input file.
857 `--debugging'
858 Convert debugging information, if possible. This is not the
859 default because only certain debugging formats are supported, and
860 the conversion process can be time consuming.
862 `--gap-fill VAL'
863 Fill gaps between sections with VAL. This operation applies to
864 the _load address_ (LMA) of the sections. It is done by increasing
865 the size of the section with the lower address, and filling in the
866 extra space created with VAL.
868 `--pad-to ADDRESS'
869 Pad the output file up to the load address ADDRESS. This is done
870 by increasing the size of the last section. The extra space is
871 filled in with the value specified by `--gap-fill' (default zero).
873 `--set-start VAL'
874 Set the start address of the new file to VAL. Not all object file
875 formats support setting the start address.
877 `--change-start INCR'
878 `--adjust-start INCR'
879 Change the start address by adding INCR. Not all object file
880 formats support setting the start address.
882 `--change-addresses INCR'
883 `--adjust-vma INCR'
884 Change the VMA and LMA addresses of all sections, as well as the
885 start address, by adding INCR. Some object file formats do not
886 permit section addresses to be changed arbitrarily. Note that
887 this does not relocate the sections; if the program expects
888 sections to be loaded at a certain address, and this option is
889 used to change the sections such that they are loaded at a
890 different address, the program may fail.
892 `--change-section-address SECTION{=,+,-}VAL'
893 `--adjust-section-vma SECTION{=,+,-}VAL'
894 Set or change both the VMA address and the LMA address of the named
895 SECTION. If `=' is used, the section address is set to VAL.
896 Otherwise, VAL is added to or subtracted from the section address.
897 See the comments under `--change-addresses', above. If SECTION
898 does not exist in the input file, a warning will be issued, unless
899 `--no-change-warnings' is used.
901 `--change-section-lma SECTION{=,+,-}VAL'
902 Set or change the LMA address of the named SECTION. The LMA
903 address is the address where the section will be loaded into
904 memory at program load time. Normally this is the same as the VMA
905 address, which is the address of the section at program run time,
906 but on some systems, especially those where a program is held in
907 ROM, the two can be different. If `=' is used, the section
908 address is set to VAL. Otherwise, VAL is added to or subtracted
909 from the section address. See the comments under
910 `--change-addresses', above. If SECTION does not exist in the
911 input file, a warning will be issued, unless
912 `--no-change-warnings' is used.
914 `--change-section-vma SECTION{=,+,-}VAL'
915 Set or change the VMA address of the named SECTION. The VMA
916 address is the address where the section will be located once the
917 program has started executing. Normally this is the same as the
918 LMA address, which is the address where the section will be loaded
919 into memory, but on some systems, especially those where a program
920 is held in ROM, the two can be different. If `=' is used, the
921 section address is set to VAL. Otherwise, VAL is added to or
922 subtracted from the section address. See the comments under
923 `--change-addresses', above. If SECTION does not exist in the
924 input file, a warning will be issued, unless
925 `--no-change-warnings' is used.
927 `--change-warnings'
928 `--adjust-warnings'
929 If `--change-section-address' or `--change-section-lma' or
930 `--change-section-vma' is used, and the named section does not
931 exist, issue a warning. This is the default.
933 `--no-change-warnings'
934 `--no-adjust-warnings'
935 Do not issue a warning if `--change-section-address' or
936 `--adjust-section-lma' or `--adjust-section-vma' is used, even if
937 the named section does not exist.
939 `--set-section-flags SECTION=FLAGS'
940 Set the flags for the named section. The FLAGS argument is a
941 comma separated string of flag names. The recognized names are
942 `alloc', `contents', `load', `noload', `readonly', `code', `data',
943 `rom', `share', and `debug'. You can set the `contents' flag for
944 a section which does not have contents, but it is not meaningful
945 to clear the `contents' flag of a section which does have
946 contents-just remove the section instead. Not all flags are
947 meaningful for all object file formats.
949 `--add-section SECTIONNAME=FILENAME'
950 Add a new section named SECTIONNAME while copying the file. The
951 contents of the new section are taken from the file FILENAME. The
952 size of the section will be the size of the file. This option only
953 works on file formats which can support sections with arbitrary
954 names.
956 `--change-leading-char'
957 Some object file formats use special characters at the start of
958 symbols. The most common such character is underscore, which
959 compilers often add before every symbol. This option tells
960 `objcopy' to change the leading character of every symbol when it
961 converts between object file formats. If the object file formats
962 use the same leading character, this option has no effect.
963 Otherwise, it will add a character, or remove a character, or
964 change a character, as appropriate.
966 `--remove-leading-char'
967 If the first character of a global symbol is a special symbol
968 leading character used by the object file format, remove the
969 character. The most common symbol leading character is
970 underscore. This option will remove a leading underscore from all
971 global symbols. This can be useful if you want to link together
972 objects of different file formats with different conventions for
973 symbol names. This is different from `--change-leading-char'
974 because it always changes the symbol name when appropriate,
975 regardless of the object file format of the output file.
977 `--srec-len=IVAL'
978 Meaningful only for srec output. Set the maximum length of the
979 Srecords being produced to IVAL. This length covers both address,
980 data and crc fields.
982 `--srec-forceS3'
983 Meaningful only for srec output. Avoid generation of S1/S2
984 records, creating S3-only record format.
986 `--redefine-sym OLD=NEW'
987 Change the name of a symbol OLD, to NEW. This can be useful when
988 one is trying link two things together for which you have no
989 source, and there are name collisions.
991 `--weaken'
992 Change all global symbols in the file to be weak. This can be
993 useful when building an object which will be linked against other
994 objects using the `-R' option to the linker. This option is only
995 effective when using an object file format which supports weak
996 symbols.
998 `--keep-symbols=FILENAME'
999 Apply `--keep-symbol' option to each symbol listed in the file
1000 FILENAME. FILENAME is simply a flat file, with one symbol name
1001 per line. Line comments may be introduced by the hash character.
1002 This option may be given more than once.
1004 `--strip-symbols=FILENAME'
1005 Apply `--strip-symbol' option to each symbol listed in the file
1006 FILENAME. FILENAME is simply a flat file, with one symbol name
1007 per line. Line comments may be introduced by the hash character.
1008 This option may be given more than once.
1010 `--keep-global-symbols=FILENAME'
1011 Apply `--keep-global-symbol' option to each symbol listed in the
1012 file FILENAME. FILENAME is simply a flat file, with one symbol
1013 name per line. Line comments may be introduced by the hash
1014 character. This option may be given more than once.
1016 `--localize-symbols=FILENAME'
1017 Apply `--localize-symbol' option to each symbol listed in the file
1018 FILENAME. FILENAME is simply a flat file, with one symbol name
1019 per line. Line comments may be introduced by the hash character.
1020 This option may be given more than once.
1022 `--weaken-symbols=FILENAME'
1023 Apply `--weaken-symbol' option to each symbol listed in the file
1024 FILENAME. FILENAME is simply a flat file, with one symbol name
1025 per line. Line comments may be introduced by the hash character.
1026 This option may be given more than once.
1028 `-V'
1029 `--version'
1030 Show the version number of `objcopy'.
1032 `-v'
1033 `--verbose'
1034 Verbose output: list all object files modified. In the case of
1035 archives, `objcopy -V' lists all members of the archive.
1037 `--help'
1038 Show a summary of the options to `objcopy'.