Annotation of src/external/gpl3/binutils.old/dist/binutils/doc/objcopy.1, Revision 1.1
1.1 ! christos 1: .\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
! 2: .\"
! 3: .\" Standard preamble:
! 4: .\" ========================================================================
! 5: .de Sp \" Vertical space (when we can't use .PP)
! 6: .if t .sp .5v
! 7: .if n .sp
! 8: ..
! 9: .de Vb \" Begin verbatim text
! 10: .ft CW
! 11: .nf
! 12: .ne \\$1
! 13: ..
! 14: .de Ve \" End verbatim text
! 15: .ft R
! 16: .fi
! 17: ..
! 18: .\" Set up some character translations and predefined strings. \*(-- will
! 19: .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
! 20: .\" double quote, and \*(R" will give a right double quote. \*(C+ will
! 21: .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
! 22: .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
! 23: .\" nothing in troff, for use with C<>.
! 24: .tr \(*W-
! 25: .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
! 26: .ie n \{\
! 27: . ds -- \(*W-
! 28: . ds PI pi
! 29: . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
! 30: . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
! 31: . ds L" ""
! 32: . ds R" ""
! 33: . ds C` ""
! 34: . ds C' ""
! 35: 'br\}
! 36: .el\{\
! 37: . ds -- \|\(em\|
! 38: . ds PI \(*p
! 39: . ds L" ``
! 40: . ds R" ''
! 41: 'br\}
! 42: .\"
! 43: .\" Escape single quotes in literal strings from groff's Unicode transform.
! 44: .ie \n(.g .ds Aq \(aq
! 45: .el .ds Aq '
! 46: .\"
! 47: .\" If the F register is turned on, we'll generate index entries on stderr for
! 48: .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
! 49: .\" entries marked with X<> in POD. Of course, you'll have to process the
! 50: .\" output yourself in some meaningful fashion.
! 51: .ie \nF \{\
! 52: . de IX
! 53: . tm Index:\\$1\t\\n%\t"\\$2"
! 54: ..
! 55: . nr % 0
! 56: . rr F
! 57: .\}
! 58: .el \{\
! 59: . de IX
! 60: ..
! 61: .\}
! 62: .\"
! 63: .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
! 64: .\" Fear. Run. Save yourself. No user-serviceable parts.
! 65: . \" fudge factors for nroff and troff
! 66: .if n \{\
! 67: . ds #H 0
! 68: . ds #V .8m
! 69: . ds #F .3m
! 70: . ds #[ \f1
! 71: . ds #] \fP
! 72: .\}
! 73: .if t \{\
! 74: . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
! 75: . ds #V .6m
! 76: . ds #F 0
! 77: . ds #[ \&
! 78: . ds #] \&
! 79: .\}
! 80: . \" simple accents for nroff and troff
! 81: .if n \{\
! 82: . ds ' \&
! 83: . ds ` \&
! 84: . ds ^ \&
! 85: . ds , \&
! 86: . ds ~ ~
! 87: . ds /
! 88: .\}
! 89: .if t \{\
! 90: . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
! 91: . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
! 92: . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
! 93: . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
! 94: . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
! 95: . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
! 96: .\}
! 97: . \" troff and (daisy-wheel) nroff accents
! 98: .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
! 99: .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
! 100: .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
! 101: .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
! 102: .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
! 103: .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
! 104: .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
! 105: .ds ae a\h'-(\w'a'u*4/10)'e
! 106: .ds Ae A\h'-(\w'A'u*4/10)'E
! 107: . \" corrections for vroff
! 108: .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
! 109: .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
! 110: . \" for low resolution devices (crt and lpr)
! 111: .if \n(.H>23 .if \n(.V>19 \
! 112: \{\
! 113: . ds : e
! 114: . ds 8 ss
! 115: . ds o a
! 116: . ds d- d\h'-1'\(ga
! 117: . ds D- D\h'-1'\(hy
! 118: . ds th \o'bp'
! 119: . ds Th \o'LP'
! 120: . ds ae ae
! 121: . ds Ae AE
! 122: .\}
! 123: .rm #[ #] #H #V #F C
! 124: .\" ========================================================================
! 125: .\"
! 126: .IX Title "OBJCOPY 1"
! 127: .TH OBJCOPY 1 "2013-03-25" "binutils-2.23.2" "GNU Development Tools"
! 128: .\" For nroff, turn off justification. Always turn off hyphenation; it makes
! 129: .\" way too many mistakes in technical documents.
! 130: .if n .ad l
! 131: .nh
! 132: .SH "NAME"
! 133: objcopy \- copy and translate object files
! 134: .SH "SYNOPSIS"
! 135: .IX Header "SYNOPSIS"
! 136: objcopy [\fB\-F\fR \fIbfdname\fR|\fB\-\-target=\fR\fIbfdname\fR]
! 137: [\fB\-I\fR \fIbfdname\fR|\fB\-\-input\-target=\fR\fIbfdname\fR]
! 138: [\fB\-O\fR \fIbfdname\fR|\fB\-\-output\-target=\fR\fIbfdname\fR]
! 139: [\fB\-B\fR \fIbfdarch\fR|\fB\-\-binary\-architecture=\fR\fIbfdarch\fR]
! 140: [\fB\-S\fR|\fB\-\-strip\-all\fR]
! 141: [\fB\-g\fR|\fB\-\-strip\-debug\fR]
! 142: [\fB\-K\fR \fIsymbolname\fR|\fB\-\-keep\-symbol=\fR\fIsymbolname\fR]
! 143: [\fB\-N\fR \fIsymbolname\fR|\fB\-\-strip\-symbol=\fR\fIsymbolname\fR]
! 144: [\fB\-\-strip\-unneeded\-symbol=\fR\fIsymbolname\fR]
! 145: [\fB\-G\fR \fIsymbolname\fR|\fB\-\-keep\-global\-symbol=\fR\fIsymbolname\fR]
! 146: [\fB\-\-localize\-hidden\fR]
! 147: [\fB\-L\fR \fIsymbolname\fR|\fB\-\-localize\-symbol=\fR\fIsymbolname\fR]
! 148: [\fB\-\-globalize\-symbol=\fR\fIsymbolname\fR]
! 149: [\fB\-W\fR \fIsymbolname\fR|\fB\-\-weaken\-symbol=\fR\fIsymbolname\fR]
! 150: [\fB\-w\fR|\fB\-\-wildcard\fR]
! 151: [\fB\-x\fR|\fB\-\-discard\-all\fR]
! 152: [\fB\-X\fR|\fB\-\-discard\-locals\fR]
! 153: [\fB\-b\fR \fIbyte\fR|\fB\-\-byte=\fR\fIbyte\fR]
! 154: [\fB\-i\fR [\fIbreadth\fR]|\fB\-\-interleave\fR[=\fIbreadth\fR]]
! 155: [\fB\-\-interleave\-width=\fR\fIwidth\fR]
! 156: [\fB\-j\fR \fIsectionname\fR|\fB\-\-only\-section=\fR\fIsectionname\fR]
! 157: [\fB\-R\fR \fIsectionname\fR|\fB\-\-remove\-section=\fR\fIsectionname\fR]
! 158: [\fB\-p\fR|\fB\-\-preserve\-dates\fR]
! 159: [\fB\-D\fR|\fB\-\-enable\-deterministic\-archives\fR]
! 160: [\fB\-U\fR|\fB\-\-disable\-deterministic\-archives\fR]
! 161: [\fB\-\-debugging\fR]
! 162: [\fB\-\-gap\-fill=\fR\fIval\fR]
! 163: [\fB\-\-pad\-to=\fR\fIaddress\fR]
! 164: [\fB\-\-set\-start=\fR\fIval\fR]
! 165: [\fB\-\-adjust\-start=\fR\fIincr\fR]
! 166: [\fB\-\-change\-addresses=\fR\fIincr\fR]
! 167: [\fB\-\-change\-section\-address\fR \fIsection\fR{=,+,\-}\fIval\fR]
! 168: [\fB\-\-change\-section\-lma\fR \fIsection\fR{=,+,\-}\fIval\fR]
! 169: [\fB\-\-change\-section\-vma\fR \fIsection\fR{=,+,\-}\fIval\fR]
! 170: [\fB\-\-change\-warnings\fR] [\fB\-\-no\-change\-warnings\fR]
! 171: [\fB\-\-set\-section\-flags\fR \fIsection\fR=\fIflags\fR]
! 172: [\fB\-\-add\-section\fR \fIsectionname\fR=\fIfilename\fR]
! 173: [\fB\-\-rename\-section\fR \fIoldname\fR=\fInewname\fR[,\fIflags\fR]]
! 174: [\fB\-\-long\-section\-names\fR {enable,disable,keep}]
! 175: [\fB\-\-change\-leading\-char\fR] [\fB\-\-remove\-leading\-char\fR]
! 176: [\fB\-\-reverse\-bytes=\fR\fInum\fR]
! 177: [\fB\-\-srec\-len=\fR\fIival\fR] [\fB\-\-srec\-forceS3\fR]
! 178: [\fB\-\-redefine\-sym\fR \fIold\fR=\fInew\fR]
! 179: [\fB\-\-redefine\-syms=\fR\fIfilename\fR]
! 180: [\fB\-\-weaken\fR]
! 181: [\fB\-\-keep\-symbols=\fR\fIfilename\fR]
! 182: [\fB\-\-strip\-symbols=\fR\fIfilename\fR]
! 183: [\fB\-\-strip\-unneeded\-symbols=\fR\fIfilename\fR]
! 184: [\fB\-\-keep\-global\-symbols=\fR\fIfilename\fR]
! 185: [\fB\-\-localize\-symbols=\fR\fIfilename\fR]
! 186: [\fB\-\-globalize\-symbols=\fR\fIfilename\fR]
! 187: [\fB\-\-weaken\-symbols=\fR\fIfilename\fR]
! 188: [\fB\-\-alt\-machine\-code=\fR\fIindex\fR]
! 189: [\fB\-\-prefix\-symbols=\fR\fIstring\fR]
! 190: [\fB\-\-prefix\-sections=\fR\fIstring\fR]
! 191: [\fB\-\-prefix\-alloc\-sections=\fR\fIstring\fR]
! 192: [\fB\-\-add\-gnu\-debuglink=\fR\fIpath-to-file\fR]
! 193: [\fB\-\-keep\-file\-symbols\fR]
! 194: [\fB\-\-only\-keep\-debug\fR]
! 195: [\fB\-\-strip\-dwo\fR]
! 196: [\fB\-\-extract\-dwo\fR]
! 197: [\fB\-\-extract\-symbol\fR]
! 198: [\fB\-\-writable\-text\fR]
! 199: [\fB\-\-readonly\-text\fR]
! 200: [\fB\-\-pure\fR]
! 201: [\fB\-\-impure\fR]
! 202: [\fB\-\-file\-alignment=\fR\fInum\fR]
! 203: [\fB\-\-heap=\fR\fIsize\fR]
! 204: [\fB\-\-image\-base=\fR\fIaddress\fR]
! 205: [\fB\-\-section\-alignment=\fR\fInum\fR]
! 206: [\fB\-\-stack=\fR\fIsize\fR]
! 207: [\fB\-\-subsystem=\fR\fIwhich\fR:\fImajor\fR.\fIminor\fR]
! 208: [\fB\-\-compress\-debug\-sections\fR]
! 209: [\fB\-\-decompress\-debug\-sections\fR]
! 210: [\fB\-\-dwarf\-depth=\fR\fIn\fR]
! 211: [\fB\-\-dwarf\-start=\fR\fIn\fR]
! 212: [\fB\-v\fR|\fB\-\-verbose\fR]
! 213: [\fB\-V\fR|\fB\-\-version\fR]
! 214: [\fB\-\-help\fR] [\fB\-\-info\fR]
! 215: \fIinfile\fR [\fIoutfile\fR]
! 216: .SH "DESCRIPTION"
! 217: .IX Header "DESCRIPTION"
! 218: The \s-1GNU\s0 \fBobjcopy\fR utility copies the contents of an object
! 219: file to another. \fBobjcopy\fR uses the \s-1GNU\s0 \s-1BFD\s0 Library to
! 220: read and write the object files. It can write the destination object
! 221: file in a format different from that of the source object file. The
! 222: exact behavior of \fBobjcopy\fR is controlled by command-line options.
! 223: Note that \fBobjcopy\fR should be able to copy a fully linked file
! 224: between any two formats. However, copying a relocatable object file
! 225: between any two formats may not work as expected.
! 226: .PP
! 227: \&\fBobjcopy\fR creates temporary files to do its translations and
! 228: deletes them afterward. \fBobjcopy\fR uses \s-1BFD\s0 to do all its
! 229: translation work; it has access to all the formats described in \s-1BFD\s0
! 230: and thus is able to recognize most formats without being told
! 231: explicitly.
! 232: .PP
! 233: \&\fBobjcopy\fR can be used to generate S\-records by using an output
! 234: target of \fBsrec\fR (e.g., use \fB\-O srec\fR).
! 235: .PP
! 236: \&\fBobjcopy\fR can be used to generate a raw binary file by using an
! 237: output target of \fBbinary\fR (e.g., use \fB\-O binary\fR). When
! 238: \&\fBobjcopy\fR generates a raw binary file, it will essentially produce
! 239: a memory dump of the contents of the input object file. All symbols and
! 240: relocation information will be discarded. The memory dump will start at
! 241: the load address of the lowest section copied into the output file.
! 242: .PP
! 243: When generating an S\-record or a raw binary file, it may be helpful to
! 244: use \fB\-S\fR to remove sections containing debugging information. In
! 245: some cases \fB\-R\fR will be useful to remove sections which contain
! 246: information that is not needed by the binary file.
! 247: .PP
! 248: Note\-\-\-\fBobjcopy\fR is not able to change the endianness of its input
! 249: files. If the input format has an endianness (some formats do not),
! 250: \&\fBobjcopy\fR can only copy the inputs into file formats that have the
! 251: same endianness or which have no endianness (e.g., \fBsrec\fR).
! 252: (However, see the \fB\-\-reverse\-bytes\fR option.)
! 253: .SH "OPTIONS"
! 254: .IX Header "OPTIONS"
! 255: .IP "\fIinfile\fR" 4
! 256: .IX Item "infile"
! 257: .PD 0
! 258: .IP "\fIoutfile\fR" 4
! 259: .IX Item "outfile"
! 260: .PD
! 261: The input and output files, respectively.
! 262: If you do not specify \fIoutfile\fR, \fBobjcopy\fR creates a
! 263: temporary file and destructively renames the result with
! 264: the name of \fIinfile\fR.
! 265: .IP "\fB\-I\fR \fIbfdname\fR" 4
! 266: .IX Item "-I bfdname"
! 267: .PD 0
! 268: .IP "\fB\-\-input\-target=\fR\fIbfdname\fR" 4
! 269: .IX Item "--input-target=bfdname"
! 270: .PD
! 271: Consider the source file's object format to be \fIbfdname\fR, rather than
! 272: attempting to deduce it.
! 273: .IP "\fB\-O\fR \fIbfdname\fR" 4
! 274: .IX Item "-O bfdname"
! 275: .PD 0
! 276: .IP "\fB\-\-output\-target=\fR\fIbfdname\fR" 4
! 277: .IX Item "--output-target=bfdname"
! 278: .PD
! 279: Write the output file using the object format \fIbfdname\fR.
! 280: .IP "\fB\-F\fR \fIbfdname\fR" 4
! 281: .IX Item "-F bfdname"
! 282: .PD 0
! 283: .IP "\fB\-\-target=\fR\fIbfdname\fR" 4
! 284: .IX Item "--target=bfdname"
! 285: .PD
! 286: Use \fIbfdname\fR as the object format for both the input and the output
! 287: file; i.e., simply transfer data from source to destination with no
! 288: translation.
! 289: .IP "\fB\-B\fR \fIbfdarch\fR" 4
! 290: .IX Item "-B bfdarch"
! 291: .PD 0
! 292: .IP "\fB\-\-binary\-architecture=\fR\fIbfdarch\fR" 4
! 293: .IX Item "--binary-architecture=bfdarch"
! 294: .PD
! 295: Useful when transforming a architecture-less input file into an object file.
! 296: In this case the output architecture can be set to \fIbfdarch\fR. This
! 297: option will be ignored if the input file has a known \fIbfdarch\fR. You
! 298: can access this binary data inside a program by referencing the special
! 299: symbols that are created by the conversion process. These symbols are
! 300: called _binary_\fIobjfile\fR_start, _binary_\fIobjfile\fR_end and
! 301: _binary_\fIobjfile\fR_size. e.g. you can transform a picture file into
! 302: an object file and then access it in your code using these symbols.
! 303: .IP "\fB\-j\fR \fIsectionname\fR" 4
! 304: .IX Item "-j sectionname"
! 305: .PD 0
! 306: .IP "\fB\-\-only\-section=\fR\fIsectionname\fR" 4
! 307: .IX Item "--only-section=sectionname"
! 308: .PD
! 309: Copy only the named section from the input file to the output file.
! 310: This option may be given more than once. Note that using this option
! 311: inappropriately may make the output file unusable.
! 312: .IP "\fB\-R\fR \fIsectionname\fR" 4
! 313: .IX Item "-R sectionname"
! 314: .PD 0
! 315: .IP "\fB\-\-remove\-section=\fR\fIsectionname\fR" 4
! 316: .IX Item "--remove-section=sectionname"
! 317: .PD
! 318: Remove any section named \fIsectionname\fR from the output file. This
! 319: option may be given more than once. Note that using this option
! 320: inappropriately may make the output file unusable.
! 321: .IP "\fB\-S\fR" 4
! 322: .IX Item "-S"
! 323: .PD 0
! 324: .IP "\fB\-\-strip\-all\fR" 4
! 325: .IX Item "--strip-all"
! 326: .PD
! 327: Do not copy relocation and symbol information from the source file.
! 328: .IP "\fB\-g\fR" 4
! 329: .IX Item "-g"
! 330: .PD 0
! 331: .IP "\fB\-\-strip\-debug\fR" 4
! 332: .IX Item "--strip-debug"
! 333: .PD
! 334: Do not copy debugging symbols or sections from the source file.
! 335: .IP "\fB\-\-strip\-unneeded\fR" 4
! 336: .IX Item "--strip-unneeded"
! 337: Strip all symbols that are not needed for relocation processing.
! 338: .IP "\fB\-K\fR \fIsymbolname\fR" 4
! 339: .IX Item "-K symbolname"
! 340: .PD 0
! 341: .IP "\fB\-\-keep\-symbol=\fR\fIsymbolname\fR" 4
! 342: .IX Item "--keep-symbol=symbolname"
! 343: .PD
! 344: When stripping symbols, keep symbol \fIsymbolname\fR even if it would
! 345: normally be stripped. This option may be given more than once.
! 346: .IP "\fB\-N\fR \fIsymbolname\fR" 4
! 347: .IX Item "-N symbolname"
! 348: .PD 0
! 349: .IP "\fB\-\-strip\-symbol=\fR\fIsymbolname\fR" 4
! 350: .IX Item "--strip-symbol=symbolname"
! 351: .PD
! 352: Do not copy symbol \fIsymbolname\fR from the source file. This option
! 353: may be given more than once.
! 354: .IP "\fB\-\-strip\-unneeded\-symbol=\fR\fIsymbolname\fR" 4
! 355: .IX Item "--strip-unneeded-symbol=symbolname"
! 356: Do not copy symbol \fIsymbolname\fR from the source file unless it is needed
! 357: by a relocation. This option may be given more than once.
! 358: .IP "\fB\-G\fR \fIsymbolname\fR" 4
! 359: .IX Item "-G symbolname"
! 360: .PD 0
! 361: .IP "\fB\-\-keep\-global\-symbol=\fR\fIsymbolname\fR" 4
! 362: .IX Item "--keep-global-symbol=symbolname"
! 363: .PD
! 364: Keep only symbol \fIsymbolname\fR global. Make all other symbols local
! 365: to the file, so that they are not visible externally. This option may
! 366: be given more than once.
! 367: .IP "\fB\-\-localize\-hidden\fR" 4
! 368: .IX Item "--localize-hidden"
! 369: In an \s-1ELF\s0 object, mark all symbols that have hidden or internal visibility
! 370: as local. This option applies on top of symbol-specific localization options
! 371: such as \fB\-L\fR.
! 372: .IP "\fB\-L\fR \fIsymbolname\fR" 4
! 373: .IX Item "-L symbolname"
! 374: .PD 0
! 375: .IP "\fB\-\-localize\-symbol=\fR\fIsymbolname\fR" 4
! 376: .IX Item "--localize-symbol=symbolname"
! 377: .PD
! 378: Make symbol \fIsymbolname\fR local to the file, so that it is not
! 379: visible externally. This option may be given more than once.
! 380: .IP "\fB\-W\fR \fIsymbolname\fR" 4
! 381: .IX Item "-W symbolname"
! 382: .PD 0
! 383: .IP "\fB\-\-weaken\-symbol=\fR\fIsymbolname\fR" 4
! 384: .IX Item "--weaken-symbol=symbolname"
! 385: .PD
! 386: Make symbol \fIsymbolname\fR weak. This option may be given more than once.
! 387: .IP "\fB\-\-globalize\-symbol=\fR\fIsymbolname\fR" 4
! 388: .IX Item "--globalize-symbol=symbolname"
! 389: Give symbol \fIsymbolname\fR global scoping so that it is visible
! 390: outside of the file in which it is defined. This option may be given
! 391: more than once.
! 392: .IP "\fB\-w\fR" 4
! 393: .IX Item "-w"
! 394: .PD 0
! 395: .IP "\fB\-\-wildcard\fR" 4
! 396: .IX Item "--wildcard"
! 397: .PD
! 398: Permit regular expressions in \fIsymbolname\fRs used in other command
! 399: line options. The question mark (?), asterisk (*), backslash (\e) and
! 400: square brackets ([]) operators can be used anywhere in the symbol
! 401: name. If the first character of the symbol name is the exclamation
! 402: point (!) then the sense of the switch is reversed for that symbol.
! 403: For example:
! 404: .Sp
! 405: .Vb 1
! 406: \& \-w \-W !foo \-W fo*
! 407: .Ve
! 408: .Sp
! 409: would cause objcopy to weaken all symbols that start with \*(L"fo\*(R"
! 410: except for the symbol \*(L"foo\*(R".
! 411: .IP "\fB\-x\fR" 4
! 412: .IX Item "-x"
! 413: .PD 0
! 414: .IP "\fB\-\-discard\-all\fR" 4
! 415: .IX Item "--discard-all"
! 416: .PD
! 417: Do not copy non-global symbols from the source file.
! 418: .IP "\fB\-X\fR" 4
! 419: .IX Item "-X"
! 420: .PD 0
! 421: .IP "\fB\-\-discard\-locals\fR" 4
! 422: .IX Item "--discard-locals"
! 423: .PD
! 424: Do not copy compiler-generated local symbols.
! 425: (These usually start with \fBL\fR or \fB.\fR.)
! 426: .IP "\fB\-b\fR \fIbyte\fR" 4
! 427: .IX Item "-b byte"
! 428: .PD 0
! 429: .IP "\fB\-\-byte=\fR\fIbyte\fR" 4
! 430: .IX Item "--byte=byte"
! 431: .PD
! 432: If interleaving has been enabled via the \fB\-\-interleave\fR option
! 433: then start the range of bytes to keep at the \fIbyte\fRth byte.
! 434: \&\fIbyte\fR can be in the range from 0 to \fIbreadth\fR\-1, where
! 435: \&\fIbreadth\fR is the value given by the \fB\-\-interleave\fR option.
! 436: .IP "\fB\-i [\fR\fIbreadth\fR\fB]\fR" 4
! 437: .IX Item "-i [breadth]"
! 438: .PD 0
! 439: .IP "\fB\-\-interleave[=\fR\fIbreadth\fR\fB]\fR" 4
! 440: .IX Item "--interleave[=breadth]"
! 441: .PD
! 442: Only copy a range out of every \fIbreadth\fR bytes. (Header data is
! 443: not affected). Select which byte in the range begins the copy with
! 444: the \fB\-\-byte\fR option. Select the width of the range with the
! 445: \&\fB\-\-interleave\-width\fR option.
! 446: .Sp
! 447: This option is useful for creating files to program \s-1ROM\s0. It is
! 448: typically used with an \f(CW\*(C`srec\*(C'\fR output target. Note that
! 449: \&\fBobjcopy\fR will complain if you do not specify the
! 450: \&\fB\-\-byte\fR option as well.
! 451: .Sp
! 452: The default interleave breadth is 4, so with \fB\-\-byte\fR set to 0,
! 453: \&\fBobjcopy\fR would copy the first byte out of every four bytes
! 454: from the input to the output.
! 455: .IP "\fB\-\-interleave\-width=\fR\fIwidth\fR" 4
! 456: .IX Item "--interleave-width=width"
! 457: When used with the \fB\-\-interleave\fR option, copy \fIwidth\fR
! 458: bytes at a time. The start of the range of bytes to be copied is set
! 459: by the \fB\-\-byte\fR option, and the extent of the range is set with
! 460: the \fB\-\-interleave\fR option.
! 461: .Sp
! 462: The default value for this option is 1. The value of \fIwidth\fR plus
! 463: the \fIbyte\fR value set by the \fB\-\-byte\fR option must not exceed
! 464: the interleave breadth set by the \fB\-\-interleave\fR option.
! 465: .Sp
! 466: This option can be used to create images for two 16\-bit flashes interleaved
! 467: in a 32\-bit bus by passing \fB\-b 0 \-i 4 \-\-interleave\-width=2\fR
! 468: and \fB\-b 2 \-i 4 \-\-interleave\-width=2\fR to two \fBobjcopy\fR
! 469: commands. If the input was '12345678' then the outputs would be
! 470: \&'1256' and '3478' respectively.
! 471: .IP "\fB\-p\fR" 4
! 472: .IX Item "-p"
! 473: .PD 0
! 474: .IP "\fB\-\-preserve\-dates\fR" 4
! 475: .IX Item "--preserve-dates"
! 476: .PD
! 477: Set the access and modification dates of the output file to be the same
! 478: as those of the input file.
! 479: .IP "\fB\-D\fR" 4
! 480: .IX Item "-D"
! 481: .PD 0
! 482: .IP "\fB\-\-enable\-deterministic\-archives\fR" 4
! 483: .IX Item "--enable-deterministic-archives"
! 484: .PD
! 485: Operate in \fIdeterministic\fR mode. When copying archive members
! 486: and writing the archive index, use zero for UIDs, GIDs, timestamps,
! 487: and use consistent file modes for all files.
! 488: .Sp
! 489: If \fIbinutils\fR was configured with
! 490: \&\fB\-\-enable\-deterministic\-archives\fR, then this mode is on by default.
! 491: It can be disabled with the \fB\-U\fR option, below.
! 492: .IP "\fB\-U\fR" 4
! 493: .IX Item "-U"
! 494: .PD 0
! 495: .IP "\fB\-\-disable\-deterministic\-archives\fR" 4
! 496: .IX Item "--disable-deterministic-archives"
! 497: .PD
! 498: Do \fInot\fR operate in \fIdeterministic\fR mode. This is the
! 499: inverse of the \fB\-D\fR option, above: when copying archive members
! 500: and writing the archive index, use their actual \s-1UID\s0, \s-1GID\s0, timestamp,
! 501: and file mode values.
! 502: .Sp
! 503: This is the default unless \fIbinutils\fR was configured with
! 504: \&\fB\-\-enable\-deterministic\-archives\fR.
! 505: .IP "\fB\-\-debugging\fR" 4
! 506: .IX Item "--debugging"
! 507: Convert debugging information, if possible. This is not the default
! 508: because only certain debugging formats are supported, and the
! 509: conversion process can be time consuming.
! 510: .IP "\fB\-\-gap\-fill\fR \fIval\fR" 4
! 511: .IX Item "--gap-fill val"
! 512: Fill gaps between sections with \fIval\fR. This operation applies to
! 513: the \fIload address\fR (\s-1LMA\s0) of the sections. It is done by increasing
! 514: the size of the section with the lower address, and filling in the extra
! 515: space created with \fIval\fR.
! 516: .IP "\fB\-\-pad\-to\fR \fIaddress\fR" 4
! 517: .IX Item "--pad-to address"
! 518: Pad the output file up to the load address \fIaddress\fR. This is
! 519: done by increasing the size of the last section. The extra space is
! 520: filled in with the value specified by \fB\-\-gap\-fill\fR (default zero).
! 521: .IP "\fB\-\-set\-start\fR \fIval\fR" 4
! 522: .IX Item "--set-start val"
! 523: Set the start address of the new file to \fIval\fR. Not all object file
! 524: formats support setting the start address.
! 525: .IP "\fB\-\-change\-start\fR \fIincr\fR" 4
! 526: .IX Item "--change-start incr"
! 527: .PD 0
! 528: .IP "\fB\-\-adjust\-start\fR \fIincr\fR" 4
! 529: .IX Item "--adjust-start incr"
! 530: .PD
! 531: Change the start address by adding \fIincr\fR. Not all object file
! 532: formats support setting the start address.
! 533: .IP "\fB\-\-change\-addresses\fR \fIincr\fR" 4
! 534: .IX Item "--change-addresses incr"
! 535: .PD 0
! 536: .IP "\fB\-\-adjust\-vma\fR \fIincr\fR" 4
! 537: .IX Item "--adjust-vma incr"
! 538: .PD
! 539: Change the \s-1VMA\s0 and \s-1LMA\s0 addresses of all sections, as well as the start
! 540: address, by adding \fIincr\fR. Some object file formats do not permit
! 541: section addresses to be changed arbitrarily. Note that this does not
! 542: relocate the sections; if the program expects sections to be loaded at a
! 543: certain address, and this option is used to change the sections such
! 544: that they are loaded at a different address, the program may fail.
! 545: .IP "\fB\-\-change\-section\-address\fR \fIsection\fR\fB{=,+,\-}\fR\fIval\fR" 4
! 546: .IX Item "--change-section-address section{=,+,-}val"
! 547: .PD 0
! 548: .IP "\fB\-\-adjust\-section\-vma\fR \fIsection\fR\fB{=,+,\-}\fR\fIval\fR" 4
! 549: .IX Item "--adjust-section-vma section{=,+,-}val"
! 550: .PD
! 551: Set or change both the \s-1VMA\s0 address and the \s-1LMA\s0 address of the named
! 552: \&\fIsection\fR. If \fB=\fR is used, the section address is set to
! 553: \&\fIval\fR. Otherwise, \fIval\fR is added to or subtracted from the
! 554: section address. See the comments under \fB\-\-change\-addresses\fR,
! 555: above. If \fIsection\fR does not exist in the input file, a warning will
! 556: be issued, unless \fB\-\-no\-change\-warnings\fR is used.
! 557: .IP "\fB\-\-change\-section\-lma\fR \fIsection\fR\fB{=,+,\-}\fR\fIval\fR" 4
! 558: .IX Item "--change-section-lma section{=,+,-}val"
! 559: Set or change the \s-1LMA\s0 address of the named \fIsection\fR. The \s-1LMA\s0
! 560: address is the address where the section will be loaded into memory at
! 561: program load time. Normally this is the same as the \s-1VMA\s0 address, which
! 562: is the address of the section at program run time, but on some systems,
! 563: especially those where a program is held in \s-1ROM\s0, the two can be
! 564: different. If \fB=\fR is used, the section address is set to
! 565: \&\fIval\fR. Otherwise, \fIval\fR is added to or subtracted from the
! 566: section address. See the comments under \fB\-\-change\-addresses\fR,
! 567: above. If \fIsection\fR does not exist in the input file, a warning
! 568: will be issued, unless \fB\-\-no\-change\-warnings\fR is used.
! 569: .IP "\fB\-\-change\-section\-vma\fR \fIsection\fR\fB{=,+,\-}\fR\fIval\fR" 4
! 570: .IX Item "--change-section-vma section{=,+,-}val"
! 571: Set or change the \s-1VMA\s0 address of the named \fIsection\fR. The \s-1VMA\s0
! 572: address is the address where the section will be located once the
! 573: program has started executing. Normally this is the same as the \s-1LMA\s0
! 574: address, which is the address where the section will be loaded into
! 575: memory, but on some systems, especially those where a program is held in
! 576: \&\s-1ROM\s0, the two can be different. If \fB=\fR is used, the section address
! 577: is set to \fIval\fR. Otherwise, \fIval\fR is added to or subtracted
! 578: from the section address. See the comments under
! 579: \&\fB\-\-change\-addresses\fR, above. If \fIsection\fR does not exist in
! 580: the input file, a warning will be issued, unless
! 581: \&\fB\-\-no\-change\-warnings\fR is used.
! 582: .IP "\fB\-\-change\-warnings\fR" 4
! 583: .IX Item "--change-warnings"
! 584: .PD 0
! 585: .IP "\fB\-\-adjust\-warnings\fR" 4
! 586: .IX Item "--adjust-warnings"
! 587: .PD
! 588: If \fB\-\-change\-section\-address\fR or \fB\-\-change\-section\-lma\fR or
! 589: \&\fB\-\-change\-section\-vma\fR is used, and the named section does not
! 590: exist, issue a warning. This is the default.
! 591: .IP "\fB\-\-no\-change\-warnings\fR" 4
! 592: .IX Item "--no-change-warnings"
! 593: .PD 0
! 594: .IP "\fB\-\-no\-adjust\-warnings\fR" 4
! 595: .IX Item "--no-adjust-warnings"
! 596: .PD
! 597: Do not issue a warning if \fB\-\-change\-section\-address\fR or
! 598: \&\fB\-\-adjust\-section\-lma\fR or \fB\-\-adjust\-section\-vma\fR is used, even
! 599: if the named section does not exist.
! 600: .IP "\fB\-\-set\-section\-flags\fR \fIsection\fR\fB=\fR\fIflags\fR" 4
! 601: .IX Item "--set-section-flags section=flags"
! 602: Set the flags for the named section. The \fIflags\fR argument is a
! 603: comma separated string of flag names. The recognized names are
! 604: \&\fBalloc\fR, \fBcontents\fR, \fBload\fR, \fBnoload\fR,
! 605: \&\fBreadonly\fR, \fBcode\fR, \fBdata\fR, \fBrom\fR, \fBshare\fR, and
! 606: \&\fBdebug\fR. You can set the \fBcontents\fR flag for a section which
! 607: does not have contents, but it is not meaningful to clear the
! 608: \&\fBcontents\fR flag of a section which does have contents\*(--just remove
! 609: the section instead. Not all flags are meaningful for all object file
! 610: formats.
! 611: .IP "\fB\-\-add\-section\fR \fIsectionname\fR\fB=\fR\fIfilename\fR" 4
! 612: .IX Item "--add-section sectionname=filename"
! 613: Add a new section named \fIsectionname\fR while copying the file. The
! 614: contents of the new section are taken from the file \fIfilename\fR. The
! 615: size of the section will be the size of the file. This option only
! 616: works on file formats which can support sections with arbitrary names.
! 617: .IP "\fB\-\-rename\-section\fR \fIoldname\fR\fB=\fR\fInewname\fR\fB[,\fR\fIflags\fR\fB]\fR" 4
! 618: .IX Item "--rename-section oldname=newname[,flags]"
! 619: Rename a section from \fIoldname\fR to \fInewname\fR, optionally
! 620: changing the section's flags to \fIflags\fR in the process. This has
! 621: the advantage over usng a linker script to perform the rename in that
! 622: the output stays as an object file and does not become a linked
! 623: executable.
! 624: .Sp
! 625: This option is particularly helpful when the input format is binary,
! 626: since this will always create a section called .data. If for example,
! 627: you wanted instead to create a section called .rodata containing binary
! 628: data you could use the following command line to achieve it:
! 629: .Sp
! 630: .Vb 3
! 631: \& objcopy \-I binary \-O <output_format> \-B <architecture> \e
! 632: \& \-\-rename\-section .data=.rodata,alloc,load,readonly,data,contents \e
! 633: \& <input_binary_file> <output_object_file>
! 634: .Ve
! 635: .IP "\fB\-\-long\-section\-names {enable,disable,keep}\fR" 4
! 636: .IX Item "--long-section-names {enable,disable,keep}"
! 637: Controls the handling of long section names when processing \f(CW\*(C`COFF\*(C'\fR
! 638: and \f(CW\*(C`PE\-COFF\*(C'\fR object formats. The default behaviour, \fBkeep\fR,
! 639: is to preserve long section names if any are present in the input file.
! 640: The \fBenable\fR and \fBdisable\fR options forcibly enable or disable
! 641: the use of long section names in the output object; when \fBdisable\fR
! 642: is in effect, any long section names in the input object will be truncated.
! 643: The \fBenable\fR option will only emit long section names if any are
! 644: present in the inputs; this is mostly the same as \fBkeep\fR, but it
! 645: is left undefined whether the \fBenable\fR option might force the
! 646: creation of an empty string table in the output file.
! 647: .IP "\fB\-\-change\-leading\-char\fR" 4
! 648: .IX Item "--change-leading-char"
! 649: Some object file formats use special characters at the start of
! 650: symbols. The most common such character is underscore, which compilers
! 651: often add before every symbol. This option tells \fBobjcopy\fR to
! 652: change the leading character of every symbol when it converts between
! 653: object file formats. If the object file formats use the same leading
! 654: character, this option has no effect. Otherwise, it will add a
! 655: character, or remove a character, or change a character, as
! 656: appropriate.
! 657: .IP "\fB\-\-remove\-leading\-char\fR" 4
! 658: .IX Item "--remove-leading-char"
! 659: If the first character of a global symbol is a special symbol leading
! 660: character used by the object file format, remove the character. The
! 661: most common symbol leading character is underscore. This option will
! 662: remove a leading underscore from all global symbols. This can be useful
! 663: if you want to link together objects of different file formats with
! 664: different conventions for symbol names. This is different from
! 665: \&\fB\-\-change\-leading\-char\fR because it always changes the symbol name
! 666: when appropriate, regardless of the object file format of the output
! 667: file.
! 668: .IP "\fB\-\-reverse\-bytes=\fR\fInum\fR" 4
! 669: .IX Item "--reverse-bytes=num"
! 670: Reverse the bytes in a section with output contents. A section length must
! 671: be evenly divisible by the value given in order for the swap to be able to
! 672: take place. Reversing takes place before the interleaving is performed.
! 673: .Sp
! 674: This option is used typically in generating \s-1ROM\s0 images for problematic
! 675: target systems. For example, on some target boards, the 32\-bit words
! 676: fetched from 8\-bit ROMs are re-assembled in little-endian byte order
! 677: regardless of the \s-1CPU\s0 byte order. Depending on the programming model, the
! 678: endianness of the \s-1ROM\s0 may need to be modified.
! 679: .Sp
! 680: Consider a simple file with a section containing the following eight
! 681: bytes: \f(CW12345678\fR.
! 682: .Sp
! 683: Using \fB\-\-reverse\-bytes=2\fR for the above example, the bytes in the
! 684: output file would be ordered \f(CW21436587\fR.
! 685: .Sp
! 686: Using \fB\-\-reverse\-bytes=4\fR for the above example, the bytes in the
! 687: output file would be ordered \f(CW43218765\fR.
! 688: .Sp
! 689: By using \fB\-\-reverse\-bytes=2\fR for the above example, followed by
! 690: \&\fB\-\-reverse\-bytes=4\fR on the output file, the bytes in the second
! 691: output file would be ordered \f(CW34127856\fR.
! 692: .IP "\fB\-\-srec\-len=\fR\fIival\fR" 4
! 693: .IX Item "--srec-len=ival"
! 694: Meaningful only for srec output. Set the maximum length of the Srecords
! 695: being produced to \fIival\fR. This length covers both address, data and
! 696: crc fields.
! 697: .IP "\fB\-\-srec\-forceS3\fR" 4
! 698: .IX Item "--srec-forceS3"
! 699: Meaningful only for srec output. Avoid generation of S1/S2 records,
! 700: creating S3\-only record format.
! 701: .IP "\fB\-\-redefine\-sym\fR \fIold\fR\fB=\fR\fInew\fR" 4
! 702: .IX Item "--redefine-sym old=new"
! 703: Change the name of a symbol \fIold\fR, to \fInew\fR. This can be useful
! 704: when one is trying link two things together for which you have no
! 705: source, and there are name collisions.
! 706: .IP "\fB\-\-redefine\-syms=\fR\fIfilename\fR" 4
! 707: .IX Item "--redefine-syms=filename"
! 708: Apply \fB\-\-redefine\-sym\fR to each symbol pair "\fIold\fR \fInew\fR"
! 709: listed in the file \fIfilename\fR. \fIfilename\fR is simply a flat file,
! 710: with one symbol pair per line. Line comments may be introduced by the hash
! 711: character. This option may be given more than once.
! 712: .IP "\fB\-\-weaken\fR" 4
! 713: .IX Item "--weaken"
! 714: Change all global symbols in the file to be weak. This can be useful
! 715: when building an object which will be linked against other objects using
! 716: the \fB\-R\fR option to the linker. This option is only effective when
! 717: using an object file format which supports weak symbols.
! 718: .IP "\fB\-\-keep\-symbols=\fR\fIfilename\fR" 4
! 719: .IX Item "--keep-symbols=filename"
! 720: Apply \fB\-\-keep\-symbol\fR option to each symbol listed in the file
! 721: \&\fIfilename\fR. \fIfilename\fR is simply a flat file, with one symbol
! 722: name per line. Line comments may be introduced by the hash character.
! 723: This option may be given more than once.
! 724: .IP "\fB\-\-strip\-symbols=\fR\fIfilename\fR" 4
! 725: .IX Item "--strip-symbols=filename"
! 726: Apply \fB\-\-strip\-symbol\fR option to each symbol listed in the file
! 727: \&\fIfilename\fR. \fIfilename\fR is simply a flat file, with one symbol
! 728: name per line. Line comments may be introduced by the hash character.
! 729: This option may be given more than once.
! 730: .IP "\fB\-\-strip\-unneeded\-symbols=\fR\fIfilename\fR" 4
! 731: .IX Item "--strip-unneeded-symbols=filename"
! 732: Apply \fB\-\-strip\-unneeded\-symbol\fR option to each symbol listed in
! 733: the file \fIfilename\fR. \fIfilename\fR is simply a flat file, with one
! 734: symbol name per line. Line comments may be introduced by the hash
! 735: character. This option may be given more than once.
! 736: .IP "\fB\-\-keep\-global\-symbols=\fR\fIfilename\fR" 4
! 737: .IX Item "--keep-global-symbols=filename"
! 738: Apply \fB\-\-keep\-global\-symbol\fR option to each symbol listed in the
! 739: file \fIfilename\fR. \fIfilename\fR is simply a flat file, with one
! 740: symbol name per line. Line comments may be introduced by the hash
! 741: character. This option may be given more than once.
! 742: .IP "\fB\-\-localize\-symbols=\fR\fIfilename\fR" 4
! 743: .IX Item "--localize-symbols=filename"
! 744: Apply \fB\-\-localize\-symbol\fR option to each symbol listed in the file
! 745: \&\fIfilename\fR. \fIfilename\fR is simply a flat file, with one symbol
! 746: name per line. Line comments may be introduced by the hash character.
! 747: This option may be given more than once.
! 748: .IP "\fB\-\-globalize\-symbols=\fR\fIfilename\fR" 4
! 749: .IX Item "--globalize-symbols=filename"
! 750: Apply \fB\-\-globalize\-symbol\fR option to each symbol listed in the file
! 751: \&\fIfilename\fR. \fIfilename\fR is simply a flat file, with one symbol
! 752: name per line. Line comments may be introduced by the hash character.
! 753: This option may be given more than once.
! 754: .IP "\fB\-\-weaken\-symbols=\fR\fIfilename\fR" 4
! 755: .IX Item "--weaken-symbols=filename"
! 756: Apply \fB\-\-weaken\-symbol\fR option to each symbol listed in the file
! 757: \&\fIfilename\fR. \fIfilename\fR is simply a flat file, with one symbol
! 758: name per line. Line comments may be introduced by the hash character.
! 759: This option may be given more than once.
! 760: .IP "\fB\-\-alt\-machine\-code=\fR\fIindex\fR" 4
! 761: .IX Item "--alt-machine-code=index"
! 762: If the output architecture has alternate machine codes, use the
! 763: \&\fIindex\fRth code instead of the default one. This is useful in case
! 764: a machine is assigned an official code and the tool-chain adopts the
! 765: new code, but other applications still depend on the original code
! 766: being used. For \s-1ELF\s0 based architectures if the \fIindex\fR
! 767: alternative does not exist then the value is treated as an absolute
! 768: number to be stored in the e_machine field of the \s-1ELF\s0 header.
! 769: .IP "\fB\-\-writable\-text\fR" 4
! 770: .IX Item "--writable-text"
! 771: Mark the output text as writable. This option isn't meaningful for all
! 772: object file formats.
! 773: .IP "\fB\-\-readonly\-text\fR" 4
! 774: .IX Item "--readonly-text"
! 775: Make the output text write protected. This option isn't meaningful for all
! 776: object file formats.
! 777: .IP "\fB\-\-pure\fR" 4
! 778: .IX Item "--pure"
! 779: Mark the output file as demand paged. This option isn't meaningful for all
! 780: object file formats.
! 781: .IP "\fB\-\-impure\fR" 4
! 782: .IX Item "--impure"
! 783: Mark the output file as impure. This option isn't meaningful for all
! 784: object file formats.
! 785: .IP "\fB\-\-prefix\-symbols=\fR\fIstring\fR" 4
! 786: .IX Item "--prefix-symbols=string"
! 787: Prefix all symbols in the output file with \fIstring\fR.
! 788: .IP "\fB\-\-prefix\-sections=\fR\fIstring\fR" 4
! 789: .IX Item "--prefix-sections=string"
! 790: Prefix all section names in the output file with \fIstring\fR.
! 791: .IP "\fB\-\-prefix\-alloc\-sections=\fR\fIstring\fR" 4
! 792: .IX Item "--prefix-alloc-sections=string"
! 793: Prefix all the names of all allocated sections in the output file with
! 794: \&\fIstring\fR.
! 795: .IP "\fB\-\-add\-gnu\-debuglink=\fR\fIpath-to-file\fR" 4
! 796: .IX Item "--add-gnu-debuglink=path-to-file"
! 797: Creates a .gnu_debuglink section which contains a reference to \fIpath-to-file\fR
! 798: and adds it to the output file.
! 799: .IP "\fB\-\-keep\-file\-symbols\fR" 4
! 800: .IX Item "--keep-file-symbols"
! 801: When stripping a file, perhaps with \fB\-\-strip\-debug\fR or
! 802: \&\fB\-\-strip\-unneeded\fR, retain any symbols specifying source file names,
! 803: which would otherwise get stripped.
! 804: .IP "\fB\-\-only\-keep\-debug\fR" 4
! 805: .IX Item "--only-keep-debug"
! 806: Strip a file, removing contents of any sections that would not be
! 807: stripped by \fB\-\-strip\-debug\fR and leaving the debugging sections
! 808: intact. In \s-1ELF\s0 files, this preserves all note sections in the output.
! 809: .Sp
! 810: The intention is that this option will be used in conjunction with
! 811: \&\fB\-\-add\-gnu\-debuglink\fR to create a two part executable. One a
! 812: stripped binary which will occupy less space in \s-1RAM\s0 and in a
! 813: distribution and the second a debugging information file which is only
! 814: needed if debugging abilities are required. The suggested procedure
! 815: to create these files is as follows:
! 816: .RS 4
! 817: .IP "1.<Link the executable as normal. Assuming that is is called>" 4
! 818: .IX Item "1.<Link the executable as normal. Assuming that is is called>"
! 819: \&\f(CW\*(C`foo\*(C'\fR then...
! 820: .ie n .IP "1.<Run ""objcopy \-\-only\-keep\-debug foo foo.dbg"" to>" 4
! 821: .el .IP "1.<Run \f(CWobjcopy \-\-only\-keep\-debug foo foo.dbg\fR to>" 4
! 822: .IX Item "1.<Run objcopy --only-keep-debug foo foo.dbg to>"
! 823: create a file containing the debugging info.
! 824: .ie n .IP "1.<Run ""objcopy \-\-strip\-debug foo"" to create a>" 4
! 825: .el .IP "1.<Run \f(CWobjcopy \-\-strip\-debug foo\fR to create a>" 4
! 826: .IX Item "1.<Run objcopy --strip-debug foo to create a>"
! 827: stripped executable.
! 828: .ie n .IP "1.<Run ""objcopy \-\-add\-gnu\-debuglink=foo.dbg foo"">" 4
! 829: .el .IP "1.<Run \f(CWobjcopy \-\-add\-gnu\-debuglink=foo.dbg foo\fR>" 4
! 830: .IX Item "1.<Run objcopy --add-gnu-debuglink=foo.dbg foo>"
! 831: to add a link to the debugging info into the stripped executable.
! 832: .RE
! 833: .RS 4
! 834: .Sp
! 835: Note\-\-\-the choice of \f(CW\*(C`.dbg\*(C'\fR as an extension for the debug info
! 836: file is arbitrary. Also the \f(CW\*(C`\-\-only\-keep\-debug\*(C'\fR step is
! 837: optional. You could instead do this:
! 838: .IP "1.<Link the executable as normal.>" 4
! 839: .IX Item "1.<Link the executable as normal.>"
! 840: .PD 0
! 841: .ie n .IP "1.<Copy ""foo"" to ""foo.full"">" 4
! 842: .el .IP "1.<Copy \f(CWfoo\fR to \f(CWfoo.full\fR>" 4
! 843: .IX Item "1.<Copy foo to foo.full>"
! 844: .ie n .IP "1.<Run ""objcopy \-\-strip\-debug foo"">" 4
! 845: .el .IP "1.<Run \f(CWobjcopy \-\-strip\-debug foo\fR>" 4
! 846: .IX Item "1.<Run objcopy --strip-debug foo>"
! 847: .ie n .IP "1.<Run ""objcopy \-\-add\-gnu\-debuglink=foo.full foo"">" 4
! 848: .el .IP "1.<Run \f(CWobjcopy \-\-add\-gnu\-debuglink=foo.full foo\fR>" 4
! 849: .IX Item "1.<Run objcopy --add-gnu-debuglink=foo.full foo>"
! 850: .RE
! 851: .RS 4
! 852: .PD
! 853: .Sp
! 854: i.e., the file pointed to by the \fB\-\-add\-gnu\-debuglink\fR can be the
! 855: full executable. It does not have to be a file created by the
! 856: \&\fB\-\-only\-keep\-debug\fR switch.
! 857: .Sp
! 858: Note\-\-\-this switch is only intended for use on fully linked files. It
! 859: does not make sense to use it on object files where the debugging
! 860: information may be incomplete. Besides the gnu_debuglink feature
! 861: currently only supports the presence of one filename containing
! 862: debugging information, not multiple filenames on a one-per-object-file
! 863: basis.
! 864: .RE
! 865: .IP "\fB\-\-strip\-dwo\fR" 4
! 866: .IX Item "--strip-dwo"
! 867: Remove the contents of all \s-1DWARF\s0 .dwo sections, leaving the
! 868: remaining debugging sections and all symbols intact.
! 869: This option is intended for use by the compiler as part of
! 870: the \fB\-gsplit\-dwarf\fR option, which splits debug information
! 871: between the .o file and a separate .dwo file. The compiler
! 872: generates all debug information in the same file, then uses
! 873: the \fB\-\-extract\-dwo\fR option to copy the .dwo sections to
! 874: the .dwo file, then the \fB\-\-strip\-dwo\fR option to remove
! 875: those sections from the original .o file.
! 876: .IP "\fB\-\-extract\-dwo\fR" 4
! 877: .IX Item "--extract-dwo"
! 878: Extract the contents of all \s-1DWARF\s0 .dwo sections. See the
! 879: \&\fB\-\-strip\-dwo\fR option for more information.
! 880: .IP "\fB\-\-file\-alignment\fR \fInum\fR" 4
! 881: .IX Item "--file-alignment num"
! 882: Specify the file alignment. Sections in the file will always begin at
! 883: file offsets which are multiples of this number. This defaults to
! 884: 512.
! 885: [This option is specific to \s-1PE\s0 targets.]
! 886: .IP "\fB\-\-heap\fR \fIreserve\fR" 4
! 887: .IX Item "--heap reserve"
! 888: .PD 0
! 889: .IP "\fB\-\-heap\fR \fIreserve\fR\fB,\fR\fIcommit\fR" 4
! 890: .IX Item "--heap reserve,commit"
! 891: .PD
! 892: Specify the number of bytes of memory to reserve (and optionally commit)
! 893: to be used as heap for this program.
! 894: [This option is specific to \s-1PE\s0 targets.]
! 895: .IP "\fB\-\-image\-base\fR \fIvalue\fR" 4
! 896: .IX Item "--image-base value"
! 897: Use \fIvalue\fR as the base address of your program or dll. This is
! 898: the lowest memory location that will be used when your program or dll
! 899: is loaded. To reduce the need to relocate and improve performance of
! 900: your dlls, each should have a unique base address and not overlap any
! 901: other dlls. The default is 0x400000 for executables, and 0x10000000
! 902: for dlls.
! 903: [This option is specific to \s-1PE\s0 targets.]
! 904: .IP "\fB\-\-section\-alignment\fR \fInum\fR" 4
! 905: .IX Item "--section-alignment num"
! 906: Sets the section alignment. Sections in memory will always begin at
! 907: addresses which are a multiple of this number. Defaults to 0x1000.
! 908: [This option is specific to \s-1PE\s0 targets.]
! 909: .IP "\fB\-\-stack\fR \fIreserve\fR" 4
! 910: .IX Item "--stack reserve"
! 911: .PD 0
! 912: .IP "\fB\-\-stack\fR \fIreserve\fR\fB,\fR\fIcommit\fR" 4
! 913: .IX Item "--stack reserve,commit"
! 914: .PD
! 915: Specify the number of bytes of memory to reserve (and optionally commit)
! 916: to be used as stack for this program.
! 917: [This option is specific to \s-1PE\s0 targets.]
! 918: .IP "\fB\-\-subsystem\fR \fIwhich\fR" 4
! 919: .IX Item "--subsystem which"
! 920: .PD 0
! 921: .IP "\fB\-\-subsystem\fR \fIwhich\fR\fB:\fR\fImajor\fR" 4
! 922: .IX Item "--subsystem which:major"
! 923: .IP "\fB\-\-subsystem\fR \fIwhich\fR\fB:\fR\fImajor\fR\fB.\fR\fIminor\fR" 4
! 924: .IX Item "--subsystem which:major.minor"
! 925: .PD
! 926: Specifies the subsystem under which your program will execute. The
! 927: legal values for \fIwhich\fR are \f(CW\*(C`native\*(C'\fR, \f(CW\*(C`windows\*(C'\fR,
! 928: \&\f(CW\*(C`console\*(C'\fR, \f(CW\*(C`posix\*(C'\fR, \f(CW\*(C`efi\-app\*(C'\fR, \f(CW\*(C`efi\-bsd\*(C'\fR,
! 929: \&\f(CW\*(C`efi\-rtd\*(C'\fR, \f(CW\*(C`sal\-rtd\*(C'\fR, and \f(CW\*(C`xbox\*(C'\fR. You may optionally set
! 930: the subsystem version also. Numeric values are also accepted for
! 931: \&\fIwhich\fR.
! 932: [This option is specific to \s-1PE\s0 targets.]
! 933: .IP "\fB\-\-extract\-symbol\fR" 4
! 934: .IX Item "--extract-symbol"
! 935: Keep the file's section flags and symbols but remove all section data.
! 936: Specifically, the option:
! 937: .RS 4
! 938: .IP "*<removes the contents of all sections;>" 4
! 939: .IX Item "*<removes the contents of all sections;>"
! 940: .PD 0
! 941: .IP "*<sets the size of every section to zero; and>" 4
! 942: .IX Item "*<sets the size of every section to zero; and>"
! 943: .IP "*<sets the file's start address to zero.>" 4
! 944: .IX Item "*<sets the file's start address to zero.>"
! 945: .RE
! 946: .RS 4
! 947: .PD
! 948: .Sp
! 949: This option is used to build a \fI.sym\fR file for a VxWorks kernel.
! 950: It can also be a useful way of reducing the size of a \fB\-\-just\-symbols\fR
! 951: linker input file.
! 952: .RE
! 953: .IP "\fB\-\-compress\-debug\-sections\fR" 4
! 954: .IX Item "--compress-debug-sections"
! 955: Compress \s-1DWARF\s0 debug sections using zlib.
! 956: .IP "\fB\-\-decompress\-debug\-sections\fR" 4
! 957: .IX Item "--decompress-debug-sections"
! 958: Decompress \s-1DWARF\s0 debug sections using zlib.
! 959: .IP "\fB\-V\fR" 4
! 960: .IX Item "-V"
! 961: .PD 0
! 962: .IP "\fB\-\-version\fR" 4
! 963: .IX Item "--version"
! 964: .PD
! 965: Show the version number of \fBobjcopy\fR.
! 966: .IP "\fB\-v\fR" 4
! 967: .IX Item "-v"
! 968: .PD 0
! 969: .IP "\fB\-\-verbose\fR" 4
! 970: .IX Item "--verbose"
! 971: .PD
! 972: Verbose output: list all object files modified. In the case of
! 973: archives, \fBobjcopy \-V\fR lists all members of the archive.
! 974: .IP "\fB\-\-help\fR" 4
! 975: .IX Item "--help"
! 976: Show a summary of the options to \fBobjcopy\fR.
! 977: .IP "\fB\-\-info\fR" 4
! 978: .IX Item "--info"
! 979: Display a list showing all architectures and object formats available.
! 980: .IP "\fB@\fR\fIfile\fR" 4
! 981: .IX Item "@file"
! 982: Read command-line options from \fIfile\fR. The options read are
! 983: inserted in place of the original @\fIfile\fR option. If \fIfile\fR
! 984: does not exist, or cannot be read, then the option will be treated
! 985: literally, and not removed.
! 986: .Sp
! 987: Options in \fIfile\fR are separated by whitespace. A whitespace
! 988: character may be included in an option by surrounding the entire
! 989: option in either single or double quotes. Any character (including a
! 990: backslash) may be included by prefixing the character to be included
! 991: with a backslash. The \fIfile\fR may itself contain additional
! 992: @\fIfile\fR options; any such options will be processed recursively.
! 993: .SH "SEE ALSO"
! 994: .IX Header "SEE ALSO"
! 995: \&\fIld\fR\|(1), \fIobjdump\fR\|(1), and the Info entries for \fIbinutils\fR.
! 996: .SH "COPYRIGHT"
! 997: .IX Header "COPYRIGHT"
! 998: Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
! 999: 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
! 1000: 2010, 2011, 2012
! 1001: Free Software Foundation, Inc.
! 1002: .PP
! 1003: Permission is granted to copy, distribute and/or modify this document
! 1004: under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
! 1005: or any later version published by the Free Software Foundation;
! 1006: with no Invariant Sections, with no Front-Cover Texts, and with no
! 1007: Back-Cover Texts. A copy of the license is included in the
! 1008: section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".
CVSweb <webmaster@jp.NetBSD.org>