diff options
| -rw-r--r-- | gnu/usr.bin/binutils/addr2line/addr2line.1 | 266 | ||||
| -rw-r--r-- | gnu/usr.bin/binutils/ar/ar.1 | 391 | ||||
| -rw-r--r-- | gnu/usr.bin/binutils/as/as.1 | 1135 | ||||
| -rw-r--r-- | gnu/usr.bin/binutils/ld/ld.1 | 2156 | ||||
| -rw-r--r-- | gnu/usr.bin/binutils/nm/nm.1 | 450 | ||||
| -rw-r--r-- | gnu/usr.bin/binutils/objcopy/objcopy.1 | 858 | ||||
| -rw-r--r-- | gnu/usr.bin/binutils/objdump/objdump.1 | 636 | ||||
| -rw-r--r-- | gnu/usr.bin/binutils/ranlib/ranlib.1 | 189 | ||||
| -rw-r--r-- | gnu/usr.bin/binutils/readelf/readelf.1 | 377 | ||||
| -rw-r--r-- | gnu/usr.bin/binutils/size/size.1 | 263 | ||||
| -rw-r--r-- | gnu/usr.bin/binutils/strings/strings.1 | 254 | ||||
| -rw-r--r-- | gnu/usr.bin/binutils/strip/strip.1 | 392 |
12 files changed, 7367 insertions, 0 deletions
diff --git a/gnu/usr.bin/binutils/addr2line/addr2line.1 b/gnu/usr.bin/binutils/addr2line/addr2line.1 new file mode 100644 index 0000000..dc946f8 --- /dev/null +++ b/gnu/usr.bin/binutils/addr2line/addr2line.1 @@ -0,0 +1,266 @@ +.\" $FreeBSD$ +.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "ADDR2LINE 1" +.TH ADDR2LINE 1 "2010-10-30" "binutils-2.17.50" "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +addr2line \- convert addresses into file names and line numbers. +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +addr2line [\fB\-b\fR \fIbfdname\fR|\fB\-\-target=\fR\fIbfdname\fR] + [\fB\-C\fR|\fB\-\-demangle\fR[=\fIstyle\fR]] + [\fB\-e\fR \fIfilename\fR|\fB\-\-exe=\fR\fIfilename\fR] + [\fB\-f\fR|\fB\-\-functions\fR] [\fB\-s\fR|\fB\-\-basename\fR] + [\fB\-i\fR|\fB\-\-inlines\fR] + [\fB\-j\fR|\fB\-\-section=\fR\fIname\fR] + [\fB\-H\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] + [addr addr ...] +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBaddr2line\fR translates addresses into file names and line numbers. +Given an address in an executable or an offset in a section of a relocatable +object, it uses the debugging information to figure out which file name and +line number are associated with it. +.PP +The executable or relocatable object to use is specified with the \fB\-e\fR +option. The default is the file \fIa.out\fR. The section in the relocatable +object to use is specified with the \fB\-j\fR option. +.PP +\&\fBaddr2line\fR has two modes of operation. +.PP +In the first, hexadecimal addresses are specified on the command line, +and \fBaddr2line\fR displays the file name and line number for each +address. +.PP +In the second, \fBaddr2line\fR reads hexadecimal addresses from +standard input, and prints the file name and line number for each +address on standard output. In this mode, \fBaddr2line\fR may be used +in a pipe to convert dynamically chosen addresses. +.PP +The format of the output is \fB\s-1FILENAME:LINENO\s0\fR. The file name and +line number for each address is printed on a separate line. If the +\&\fB\-f\fR option is used, then each \fB\s-1FILENAME:LINENO\s0\fR line is +preceded by a \fB\s-1FUNCTIONNAME\s0\fR line which is the name of the function +containing the address. +.PP +If the file name or function name can not be determined, +\&\fBaddr2line\fR will print two question marks in their place. If the +line number can not be determined, \fBaddr2line\fR will print 0. +.SH "OPTIONS" +.IX Header "OPTIONS" +The long and short forms of options, shown here as alternatives, are +equivalent. +.IP "\fB\-b\fR \fIbfdname\fR" 4 +.IX Item "-b bfdname" +.PD 0 +.IP "\fB\-\-target=\fR\fIbfdname\fR" 4 +.IX Item "--target=bfdname" +.PD +Specify that the object-code format for the object files is +\&\fIbfdname\fR. +.IP "\fB\-C\fR" 4 +.IX Item "-C" +.PD 0 +.IP "\fB\-\-demangle[=\fR\fIstyle\fR\fB]\fR" 4 +.IX Item "--demangle[=style]" +.PD +Decode (\fIdemangle\fR) 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. +.IP "\fB\-e\fR \fIfilename\fR" 4 +.IX Item "-e filename" +.PD 0 +.IP "\fB\-\-exe=\fR\fIfilename\fR" 4 +.IX Item "--exe=filename" +.PD +Specify the name of the executable for which addresses should be +translated. The default file is \fIa.out\fR. +.IP "\fB\-f\fR" 4 +.IX Item "-f" +.PD 0 +.IP "\fB\-\-functions\fR" 4 +.IX Item "--functions" +.PD +Display function names as well as file and line number information. +.IP "\fB\-s\fR" 4 +.IX Item "-s" +.PD 0 +.IP "\fB\-\-basenames\fR" 4 +.IX Item "--basenames" +.PD +Display only the base of each file name. +.IP "\fB\-i\fR" 4 +.IX Item "-i" +.PD 0 +.IP "\fB\-\-inlines\fR" 4 +.IX Item "--inlines" +.PD +If the address belongs to a function that was inlined, the source +information for all enclosing scopes back to the first non-inlined +function will also be printed. For example, if \f(CW\*(C`main\*(C'\fR inlines +\&\f(CW\*(C`callee1\*(C'\fR which inlines \f(CW\*(C`callee2\*(C'\fR, and address is from +\&\f(CW\*(C`callee2\*(C'\fR, the source information for \f(CW\*(C`callee1\*(C'\fR and \f(CW\*(C`main\*(C'\fR +will also be printed. +.IP "\fB\-j\fR" 4 +.IX Item "-j" +.PD 0 +.IP "\fB\-\-section\fR" 4 +.IX Item "--section" +.PD +Read offsets relative to the specified section instead of absolute addresses. +.IP "\fB@\fR\fIfile\fR" 4 +.IX Item "@file" +Read command-line options from \fIfile\fR. The options read are +inserted in place of the original @\fIfile\fR option. If \fIfile\fR +does not exist, or cannot be read, then the option will be treated +literally, and not removed. +.Sp +Options in \fIfile\fR are separated by whitespace. A whitespace +character may be included in an option by surrounding the entire +option in either single or double quotes. Any character (including a +backslash) may be included by prefixing the character to be included +with a backslash. The \fIfile\fR may itself contain additional +@\fIfile\fR options; any such options will be processed recursively. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +Info entries for \fIbinutils\fR. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, +2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 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 \*(L"\s-1GNU\s0 Free Documentation License\*(R". diff --git a/gnu/usr.bin/binutils/ar/ar.1 b/gnu/usr.bin/binutils/ar/ar.1 new file mode 100644 index 0000000..6e31fb7 --- /dev/null +++ b/gnu/usr.bin/binutils/ar/ar.1 @@ -0,0 +1,391 @@ +.\" $FreeBSD$ +.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "AR 1" +.TH AR 1 "2010-10-30" "binutils-2.17.50" "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +ar \- create, modify, and extract from archives +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +ar [\fB\-X32_64\fR] [\fB\-\fR]\fIp\fR[\fImod\fR [\fIrelpos\fR] [\fIcount\fR]] \fIarchive\fR [\fImember\fR...] +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \s-1GNU\s0 \fBar\fR program creates, modifies, and extracts from +archives. An \fIarchive\fR is a single file holding a collection of +other files in a structure that makes it possible to retrieve +the original individual files (called \fImembers\fR of the archive). +.PP +The original files' contents, mode (permissions), timestamp, owner, and +group are preserved in the archive, and can be restored on +extraction. +.PP +\&\s-1GNU\s0 \fBar\fR can maintain archives whose members have names of any +length; however, depending on how \fBar\fR 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). +.PP +\&\fBar\fR is considered a binary utility because archives of this sort +are most often used as \fIlibraries\fR holding commonly needed +subroutines. +.PP +\&\fBar\fR creates an index to the symbols defined in relocatable +object modules in the archive when you specify the modifier \fBs\fR. +Once created, this index is updated in the archive whenever \fBar\fR +makes a change to its contents (save for the \fBq\fR 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. +.PP +You may use \fBnm \-s\fR or \fBnm \-\-print\-armap\fR to list this index +table. If an archive lacks the table, another form of \fBar\fR called +\&\fBranlib\fR can be used to add just the table. +.PP +\&\s-1GNU\s0 \fBar\fR is designed to be compatible with two different +facilities. You can control its activity using command-line options, +like the different varieties of \fBar\fR on Unix systems; or, if you +specify the single command-line option \fB\-M\fR, you can control it +with a script supplied via standard input, like the \s-1MRI\s0 \*(L"librarian\*(R" +program. +.SH "OPTIONS" +.IX Header "OPTIONS" +\&\s-1GNU\s0 \fBar\fR allows you to mix the operation code \fIp\fR and modifier +flags \fImod\fR in any order, within the first command-line argument. +.PP +If you wish, you may begin the first command-line argument with a +dash. +.PP +The \fIp\fR keyletter specifies what operation to execute; it may be +any of the following, but you must specify only one of them: +.IP "\fBd\fR" 4 +.IX Item "d" +\&\fIDelete\fR modules from the archive. Specify the names of modules to +be deleted as \fImember\fR...; the archive is untouched if you +specify no files to delete. +.Sp +If you specify the \fBv\fR modifier, \fBar\fR lists each module +as it is deleted. +.IP "\fBm\fR" 4 +.IX Item "m" +Use this operation to \fImove\fR members in an archive. +.Sp +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. +.Sp +If no modifiers are used with \f(CW\*(C`m\*(C'\fR, any members you name in the +\&\fImember\fR arguments are moved to the \fIend\fR of the archive; +you can use the \fBa\fR, \fBb\fR, or \fBi\fR modifiers to move them to a +specified place instead. +.IP "\fBp\fR" 4 +.IX Item "p" +\&\fIPrint\fR the specified members of the archive, to the standard +output file. If the \fBv\fR modifier is specified, show the member +name before copying its contents to standard output. +.Sp +If you specify no \fImember\fR arguments, all the files in the archive are +printed. +.IP "\fBq\fR" 4 +.IX Item "q" +\&\fIQuick append\fR; Historically, add the files \fImember\fR... to the end of +\&\fIarchive\fR, without checking for replacement. +.Sp +The modifiers \fBa\fR, \fBb\fR, and \fBi\fR do \fInot\fR affect this +operation; new members are always placed at the end of the archive. +.Sp +The modifier \fBv\fR makes \fBar\fR list each file as it is appended. +.Sp +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 \fBar s\fR or +\&\fBranlib\fR explicitly to update the symbol table index. +.Sp +However, too many different systems assume quick append rebuilds the +index, so \s-1GNU\s0 \fBar\fR implements \fBq\fR as a synonym for \fBr\fR. +.IP "\fBr\fR" 4 +.IX Item "r" +Insert the files \fImember\fR... into \fIarchive\fR (with +\&\fIreplacement\fR). This operation differs from \fBq\fR in that any +previously existing members are deleted if their names match those being +added. +.Sp +If one of the files named in \fImember\fR... does not exist, \fBar\fR +displays an error message, and leaves undisturbed any existing members +of the archive matching that name. +.Sp +By default, new members are added at the end of the file; but you may +use one of the modifiers \fBa\fR, \fBb\fR, or \fBi\fR to request +placement relative to some existing member. +.Sp +The modifier \fBv\fR used with this operation elicits a line of +output for each file inserted, along with one of the letters \fBa\fR or +\&\fBr\fR to indicate whether the file was appended (no old member +deleted) or replaced. +.IP "\fBt\fR" 4 +.IX Item "t" +Display a \fItable\fR listing the contents of \fIarchive\fR, or those +of the files listed in \fImember\fR... 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 \fBv\fR modifier. +.Sp +If you do not specify a \fImember\fR, all files in the archive +are listed. +.Sp +If there is more than one file with the same name (say, \fBfie\fR) in +an archive (say \fBb.a\fR), \fBar t b.a fie\fR lists only the +first instance; to see them all, you must ask for a complete +listing\-\-\-in our example, \fBar t b.a\fR. +.IP "\fBx\fR" 4 +.IX Item "x" +\&\fIExtract\fR members (named \fImember\fR) from the archive. You can +use the \fBv\fR modifier with this operation, to request that +\&\fBar\fR list each name as it extracts it. +.Sp +If you do not specify a \fImember\fR, all files in the archive +are extracted. +.PP +A number of modifiers (\fImod\fR) may immediately follow the \fIp\fR +keyletter, to specify variations on an operation's behavior: +.IP "\fBa\fR" 4 +.IX Item "a" +Add new files \fIafter\fR an existing member of the +archive. If you use the modifier \fBa\fR, the name of an existing archive +member must be present as the \fIrelpos\fR argument, before the +\&\fIarchive\fR specification. +.IP "\fBb\fR" 4 +.IX Item "b" +Add new files \fIbefore\fR an existing member of the +archive. If you use the modifier \fBb\fR, the name of an existing archive +member must be present as the \fIrelpos\fR argument, before the +\&\fIarchive\fR specification. (same as \fBi\fR). +.IP "\fBc\fR" 4 +.IX Item "c" +\&\fICreate\fR the archive. The specified \fIarchive\fR 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. +.IP "\fBf\fR" 4 +.IX Item "f" +Truncate names in the archive. \s-1GNU\s0 \fBar\fR will normally permit file +names of any length. This will cause it to create archives which are +not compatible with the native \fBar\fR program on some systems. If +this is a concern, the \fBf\fR modifier may be used to truncate file +names when putting them in the archive. +.IP "\fBi\fR" 4 +.IX Item "i" +Insert new files \fIbefore\fR an existing member of the +archive. If you use the modifier \fBi\fR, the name of an existing archive +member must be present as the \fIrelpos\fR argument, before the +\&\fIarchive\fR specification. (same as \fBb\fR). +.IP "\fBl\fR" 4 +.IX Item "l" +This modifier is accepted but not used. +.IP "\fBN\fR" 4 +.IX Item "N" +Uses the \fIcount\fR parameter. This is used if there are multiple +entries in the archive with the same name. Extract or delete instance +\&\fIcount\fR of the given name from the archive. +.IP "\fBo\fR" 4 +.IX Item "o" +Preserve the \fIoriginal\fR 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. +.IP "\fBP\fR" 4 +.IX Item "P" +Use the full path name when matching names in the archive. \s-1GNU\s0 +\&\fBar\fR can not create an archive with a full path name (such archives +are not \s-1POSIX\s0 complaint), but other archive creators can. This option +will cause \s-1GNU\s0 \fBar\fR 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. +.IP "\fBs\fR" 4 +.IX Item "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 \fBar s\fR on an +archive is equivalent to running \fBranlib\fR on it. +.IP "\fBS\fR" 4 +.IX Item "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 +\&\fBS\fR modifier on the last execution of \fBar\fR, or you must run +\&\fBranlib\fR on the archive. +.IP "\fBu\fR" 4 +.IX Item "u" +Normally, \fBar r\fR... inserts all files +listed into the archive. If you would like to insert \fIonly\fR those +of the files you list that are newer than existing members of the same +names, use this modifier. The \fBu\fR modifier is allowed only for the +operation \fBr\fR (replace). In particular, the combination \fBqu\fR is +not allowed, since checking the timestamps would lose any speed +advantage from the operation \fBq\fR. +.IP "\fBv\fR" 4 +.IX Item "v" +This modifier requests the \fIverbose\fR version of an operation. Many +operations display additional information, such as filenames processed, +when the modifier \fBv\fR is appended. +.IP "\fBV\fR" 4 +.IX Item "V" +This modifier shows the version number of \fBar\fR. +.PP +\&\fBar\fR ignores an initial option spelt \fB\-X32_64\fR, for +compatibility with \s-1AIX\s0. The behaviour produced by this option is the +default for \s-1GNU\s0 \fBar\fR. \fBar\fR does not support any of the other +\&\fB\-X\fR options; in particular, it does not support \fB\-X32\fR +which is the default for \s-1AIX\s0 \fBar\fR. +.IP "\fB@\fR\fIfile\fR" 4 +.IX Item "@file" +Read command-line options from \fIfile\fR. The options read are +inserted in place of the original @\fIfile\fR option. If \fIfile\fR +does not exist, or cannot be read, then the option will be treated +literally, and not removed. +.Sp +Options in \fIfile\fR are separated by whitespace. A whitespace +character may be included in an option by surrounding the entire +option in either single or double quotes. Any character (including a +backslash) may be included by prefixing the character to be included +with a backslash. The \fIfile\fR may itself contain additional +@\fIfile\fR options; any such options will be processed recursively. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fInm\fR\|(1), \fIranlib\fR\|(1), and the Info entries for \fIbinutils\fR. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, +2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 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 \*(L"\s-1GNU\s0 Free Documentation License\*(R". diff --git a/gnu/usr.bin/binutils/as/as.1 b/gnu/usr.bin/binutils/as/as.1 new file mode 100644 index 0000000..40ee7e4 --- /dev/null +++ b/gnu/usr.bin/binutils/as/as.1 @@ -0,0 +1,1135 @@ +.\" $FreeBSD$ +.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "AS 1" +.TH AS 1 "2010-10-30" "binutils-2.17.50" "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +AS \- the portable GNU assembler. +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +as [\fB\-a\fR[\fBcdhlns\fR][=\fIfile\fR]] [\fB\-\-alternate\fR] [\fB\-D\fR] + [\fB\-\-defsym\fR \fIsym\fR=\fIval\fR] [\fB\-f\fR] [\fB\-g\fR] [\fB\-\-gstabs\fR] + [\fB\-\-gstabs+\fR] [\fB\-\-gdwarf\-2\fR] [\fB\-\-help\fR] [\fB\-I\fR \fIdir\fR] [\fB\-J\fR] + [\fB\-K\fR] [\fB\-L\fR] [\fB\-\-listing\-lhs\-width\fR=\fI\s-1NUM\s0\fR] + [\fB\-\-listing\-lhs\-width2\fR=\fI\s-1NUM\s0\fR] [\fB\-\-listing\-rhs\-width\fR=\fI\s-1NUM\s0\fR] + [\fB\-\-listing\-cont\-lines\fR=\fI\s-1NUM\s0\fR] [\fB\-\-keep\-locals\fR] [\fB\-o\fR + \fIobjfile\fR] [\fB\-R\fR] [\fB\-\-reduce\-memory\-overheads\fR] [\fB\-\-statistics\fR] + [\fB\-v\fR] [\fB\-version\fR] [\fB\-\-version\fR] [\fB\-W\fR] [\fB\-\-warn\fR] + [\fB\-\-fatal\-warnings\fR] [\fB\-w\fR] [\fB\-x\fR] [\fB\-Z\fR] [\fB@\fR\fI\s-1FILE\s0\fR] + [\fB\-\-target\-help\fR] [\fItarget-options\fR] + [\fB\-\-\fR|\fIfiles\fR ...] +.PP +\&\fITarget Alpha options:\fR + [\fB\-m\fR\fIcpu\fR] + [\fB\-mdebug\fR | \fB\-no\-mdebug\fR] + [\fB\-relax\fR] [\fB\-g\fR] [\fB\-G\fR\fIsize\fR] + [\fB\-F\fR] [\fB\-32addr\fR] +.PP +\&\fITarget \s-1ARC\s0 options:\fR + [\fB\-marc[5|6|7|8]\fR] + [\fB\-EB\fR|\fB\-EL\fR] +.PP +\&\fITarget \s-1ARM\s0 options:\fR + [\fB\-mcpu\fR=\fIprocessor\fR[+\fIextension\fR...]] + [\fB\-march\fR=\fIarchitecture\fR[+\fIextension\fR...]] + [\fB\-mfpu\fR=\fIfloating-point-format\fR] + [\fB\-mfloat\-abi\fR=\fIabi\fR] + [\fB\-meabi\fR=\fIver\fR] + [\fB\-mthumb\fR] + [\fB\-EB\fR|\fB\-EL\fR] + [\fB\-mapcs\-32\fR|\fB\-mapcs\-26\fR|\fB\-mapcs\-float\fR| + \fB\-mapcs\-reentrant\fR] + [\fB\-mthumb\-interwork\fR] [\fB\-k\fR] +.PP +\&\fITarget \s-1CRIS\s0 options:\fR + [\fB\-\-underscore\fR | \fB\-\-no\-underscore\fR] + [\fB\-\-pic\fR] [\fB\-N\fR] + [\fB\-\-emulation=criself\fR | \fB\-\-emulation=crisaout\fR] + [\fB\-\-march=v0_v10\fR | \fB\-\-march=v10\fR | \fB\-\-march=v32\fR | \fB\-\-march=common_v10_v32\fR] +.PP +\&\fITarget D10V options:\fR + [\fB\-O\fR] +.PP +\&\fITarget D30V options:\fR + [\fB\-O\fR|\fB\-n\fR|\fB\-N\fR] +.PP +\&\fITarget i386 options:\fR + [\fB\-\-32\fR|\fB\-\-64\fR] [\fB\-n\fR] + [\fB\-march\fR=\fI\s-1CPU\s0\fR] [\fB\-mtune\fR=\fI\s-1CPU\s0\fR] +.PP +\&\fITarget i960 options:\fR + [\fB\-ACA\fR|\fB\-ACA_A\fR|\fB\-ACB\fR|\fB\-ACC\fR|\fB\-AKA\fR|\fB\-AKB\fR| + \fB\-AKC\fR|\fB\-AMC\fR] + [\fB\-b\fR] [\fB\-no\-relax\fR] +.PP +\&\fITarget \s-1IA\-64\s0 options:\fR + [\fB\-mconstant\-gp\fR|\fB\-mauto\-pic\fR] + [\fB\-milp32\fR|\fB\-milp64\fR|\fB\-mlp64\fR|\fB\-mp64\fR] + [\fB\-mle\fR|\fBmbe\fR] + [\fB\-mtune=itanium1\fR|\fB\-mtune=itanium2\fR] + [\fB\-munwind\-check=warning\fR|\fB\-munwind\-check=error\fR] + [\fB\-mhint.b=ok\fR|\fB\-mhint.b=warning\fR|\fB\-mhint.b=error\fR] + [\fB\-x\fR|\fB\-xexplicit\fR] [\fB\-xauto\fR] [\fB\-xdebug\fR] +.PP +\&\fITarget \s-1IP2K\s0 options:\fR + [\fB\-mip2022\fR|\fB\-mip2022ext\fR] +.PP +\&\fITarget M32C options:\fR + [\fB\-m32c\fR|\fB\-m16c\fR] +.PP +\&\fITarget M32R options:\fR + [\fB\-\-m32rx\fR|\fB\-\-[no\-]warn\-explicit\-parallel\-conflicts\fR| + \fB\-\-W[n]p\fR] +.PP +\&\fITarget M680X0 options:\fR + [\fB\-l\fR] [\fB\-m68000\fR|\fB\-m68010\fR|\fB\-m68020\fR|...] +.PP +\&\fITarget M68HC11 options:\fR + [\fB\-m68hc11\fR|\fB\-m68hc12\fR|\fB\-m68hcs12\fR] + [\fB\-mshort\fR|\fB\-mlong\fR] + [\fB\-mshort\-double\fR|\fB\-mlong\-double\fR] + [\fB\-\-force\-long\-branches\fR] [\fB\-\-short\-branches\fR] + [\fB\-\-strict\-direct\-mode\fR] [\fB\-\-print\-insn\-syntax\fR] + [\fB\-\-print\-opcodes\fR] [\fB\-\-generate\-example\fR] +.PP +\&\fITarget \s-1MCORE\s0 options:\fR + [\fB\-jsri2bsr\fR] [\fB\-sifilter\fR] [\fB\-relax\fR] + [\fB\-mcpu=[210|340]\fR] +.PP +\&\fITarget \s-1MIPS\s0 options:\fR + [\fB\-nocpp\fR] [\fB\-EL\fR] [\fB\-EB\fR] [\fB\-O\fR[\fIoptimization level\fR]] + [\fB\-g\fR[\fIdebug level\fR]] [\fB\-G\fR \fInum\fR] [\fB\-KPIC\fR] [\fB\-call_shared\fR] + [\fB\-non_shared\fR] [\fB\-xgot\fR [\fB\-mvxworks\-pic\fR] + [\fB\-mabi\fR=\fI\s-1ABI\s0\fR] [\fB\-32\fR] [\fB\-n32\fR] [\fB\-64\fR] [\fB\-mfp32\fR] [\fB\-mgp32\fR] + [\fB\-march\fR=\fI\s-1CPU\s0\fR] [\fB\-mtune\fR=\fI\s-1CPU\s0\fR] [\fB\-mips1\fR] [\fB\-mips2\fR] + [\fB\-mips3\fR] [\fB\-mips4\fR] [\fB\-mips5\fR] [\fB\-mips32\fR] [\fB\-mips32r2\fR] + [\fB\-mips64\fR] [\fB\-mips64r2\fR] + [\fB\-construct\-floats\fR] [\fB\-no\-construct\-floats\fR] + [\fB\-trap\fR] [\fB\-no\-break\fR] [\fB\-break\fR] [\fB\-no\-trap\fR] + [\fB\-mfix7000\fR] [\fB\-mno\-fix7000\fR] + [\fB\-mips16\fR] [\fB\-no\-mips16\fR] + [\fB\-msmartmips\fR] [\fB\-mno\-smartmips\fR] + [\fB\-mips3d\fR] [\fB\-no\-mips3d\fR] + [\fB\-mdmx\fR] [\fB\-no\-mdmx\fR] + [\fB\-mdsp\fR] [\fB\-mno\-dsp\fR] + [\fB\-mdspr2\fR] [\fB\-mno\-dspr2\fR] + [\fB\-mmt\fR] [\fB\-mno\-mt\fR] + [\fB\-mdebug\fR] [\fB\-no\-mdebug\fR] + [\fB\-mpdr\fR] [\fB\-mno\-pdr\fR] +.PP +\&\fITarget \s-1MMIX\s0 options:\fR + [\fB\-\-fixed\-special\-register\-names\fR] [\fB\-\-globalize\-symbols\fR] + [\fB\-\-gnu\-syntax\fR] [\fB\-\-relax\fR] [\fB\-\-no\-predefined\-symbols\fR] + [\fB\-\-no\-expand\fR] [\fB\-\-no\-merge\-gregs\fR] [\fB\-x\fR] + [\fB\-\-linker\-allocated\-gregs\fR] +.PP +\&\fITarget \s-1PDP11\s0 options:\fR + [\fB\-mpic\fR|\fB\-mno\-pic\fR] [\fB\-mall\fR] [\fB\-mno\-extensions\fR] + [\fB\-m\fR\fIextension\fR|\fB\-mno\-\fR\fIextension\fR] + [\fB\-m\fR\fIcpu\fR] [\fB\-m\fR\fImachine\fR] +.PP +\&\fITarget picoJava options:\fR + [\fB\-mb\fR|\fB\-me\fR] +.PP +\&\fITarget PowerPC options:\fR + [\fB\-mpwrx\fR|\fB\-mpwr2\fR|\fB\-mpwr\fR|\fB\-m601\fR|\fB\-mppc\fR|\fB\-mppc32\fR|\fB\-m603\fR|\fB\-m604\fR| + \fB\-m403\fR|\fB\-m405\fR|\fB\-mppc64\fR|\fB\-m620\fR|\fB\-mppc64bridge\fR|\fB\-mbooke\fR| + \fB\-mbooke32\fR|\fB\-mbooke64\fR] + [\fB\-mcom\fR|\fB\-many\fR|\fB\-maltivec\fR] [\fB\-memb\fR] + [\fB\-mregnames\fR|\fB\-mno\-regnames\fR] + [\fB\-mrelocatable\fR|\fB\-mrelocatable\-lib\fR] + [\fB\-mlittle\fR|\fB\-mlittle\-endian\fR|\fB\-mbig\fR|\fB\-mbig\-endian\fR] + [\fB\-msolaris\fR|\fB\-mno\-solaris\fR] +.PP +\&\fITarget \s-1SPARC\s0 options:\fR + [\fB\-Av6\fR|\fB\-Av7\fR|\fB\-Av8\fR|\fB\-Asparclet\fR|\fB\-Asparclite\fR + \fB\-Av8plus\fR|\fB\-Av8plusa\fR|\fB\-Av9\fR|\fB\-Av9a\fR] + [\fB\-xarch=v8plus\fR|\fB\-xarch=v8plusa\fR] [\fB\-bump\fR] + [\fB\-32\fR|\fB\-64\fR] +.PP +\&\fITarget \s-1TIC54X\s0 options:\fR + [\fB\-mcpu=54[123589]\fR|\fB\-mcpu=54[56]lp\fR] [\fB\-mfar\-mode\fR|\fB\-mf\fR] + [\fB\-merrors\-to\-file\fR \fI<filename>\fR|\fB\-me\fR \fI<filename>\fR] +.PP +\&\fITarget Z80 options:\fR + [\fB\-z80\fR] [\fB\-r800\fR] + [ \fB\-ignore\-undocumented\-instructions\fR] [\fB\-Wnud\fR] + [ \fB\-ignore\-unportable\-instructions\fR] [\fB\-Wnup\fR] + [ \fB\-warn\-undocumented\-instructions\fR] [\fB\-Wud\fR] + [ \fB\-warn\-unportable\-instructions\fR] [\fB\-Wup\fR] + [ \fB\-forbid\-undocumented\-instructions\fR] [\fB\-Fud\fR] + [ \fB\-forbid\-unportable\-instructions\fR] [\fB\-Fup\fR] +.PP +\&\fITarget Xtensa options:\fR + [\fB\-\-[no\-]text\-section\-literals\fR] [\fB\-\-[no\-]absolute\-literals\fR] + [\fB\-\-[no\-]target\-align\fR] [\fB\-\-[no\-]longcalls\fR] + [\fB\-\-[no\-]transform\fR] + [\fB\-\-rename\-section\fR \fIoldname\fR=\fInewname\fR] +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\s-1GNU\s0 \fBas\fR is really a family of assemblers. +If you use (or have used) the \s-1GNU\s0 assembler on one architecture, you +should find a fairly similar environment when you use it on another +architecture. Each version has much in common with the others, +including object file formats, most assembler directives (often called +\&\fIpseudo-ops\fR) and assembler syntax. +.PP +\&\fBas\fR is primarily intended to assemble the output of the +\&\s-1GNU\s0 C compiler \f(CW\*(C`gcc\*(C'\fR for use by the linker +\&\f(CW\*(C`ld\*(C'\fR. Nevertheless, we've tried to make \fBas\fR +assemble correctly everything that other assemblers for the same +machine would assemble. +Any exceptions are documented explicitly. +This doesn't mean \fBas\fR always uses the same syntax as another +assembler for the same architecture; for example, we know of several +incompatible versions of 680x0 assembly language syntax. +.PP +Each time you run \fBas\fR it assembles exactly one source +program. The source program is made up of one or more files. +(The standard input is also a file.) +.PP +You give \fBas\fR a command line that has zero or more input file +names. The input files are read (from left file name to right). A +command line argument (in any position) that has no special meaning +is taken to be an input file name. +.PP +If you give \fBas\fR no file names it attempts to read one input file +from the \fBas\fR standard input, which is normally your terminal. You +may have to type \fBctl-D\fR to tell \fBas\fR there is no more program +to assemble. +.PP +Use \fB\-\-\fR if you need to explicitly name the standard input file +in your command line. +.PP +If the source is empty, \fBas\fR produces a small, empty object +file. +.PP +\&\fBas\fR may write warnings and error messages to the standard error +file (usually your terminal). This should not happen when a compiler +runs \fBas\fR automatically. Warnings report an assumption made so +that \fBas\fR could keep assembling a flawed program; errors report a +grave problem that stops the assembly. +.PP +If you are invoking \fBas\fR via the \s-1GNU\s0 C compiler, +you can use the \fB\-Wa\fR option to pass arguments through to the assembler. +The assembler arguments must be separated from each other (and the \fB\-Wa\fR) +by commas. For example: +.PP +.Vb 1 +\& gcc \-c \-g \-O \-Wa,\-alh,\-L file.c +.Ve +.PP +This passes two options to the assembler: \fB\-alh\fR (emit a listing to +standard output with high-level and assembly source) and \fB\-L\fR (retain +local symbols in the symbol table). +.PP +Usually you do not need to use this \fB\-Wa\fR mechanism, since many compiler +command-line options are automatically passed to the assembler by the compiler. +(You can call the \s-1GNU\s0 compiler driver with the \fB\-v\fR option to see +precisely what options it passes to each compilation pass, including the +assembler.) +.SH "OPTIONS" +.IX Header "OPTIONS" +.IP "\fB@\fR\fIfile\fR" 4 +.IX Item "@file" +Read command-line options from \fIfile\fR. The options read are +inserted in place of the original @\fIfile\fR option. If \fIfile\fR +does not exist, or cannot be read, then the option will be treated +literally, and not removed. +.Sp +Options in \fIfile\fR are separated by whitespace. A whitespace +character may be included in an option by surrounding the entire +option in either single or double quotes. Any character (including a +backslash) may be included by prefixing the character to be included +with a backslash. The \fIfile\fR may itself contain additional +@\fIfile\fR options; any such options will be processed recursively. +.IP "\fB\-a[cdhlmns]\fR" 4 +.IX Item "-a[cdhlmns]" +Turn on listings, in any of a variety of ways: +.RS 4 +.IP "\fB\-ac\fR" 4 +.IX Item "-ac" +omit false conditionals +.IP "\fB\-ad\fR" 4 +.IX Item "-ad" +omit debugging directives +.IP "\fB\-ah\fR" 4 +.IX Item "-ah" +include high-level source +.IP "\fB\-al\fR" 4 +.IX Item "-al" +include assembly +.IP "\fB\-am\fR" 4 +.IX Item "-am" +include macro expansions +.IP "\fB\-an\fR" 4 +.IX Item "-an" +omit forms processing +.IP "\fB\-as\fR" 4 +.IX Item "-as" +include symbols +.IP "\fB=file\fR" 4 +.IX Item "=file" +set the name of the listing file +.RE +.RS 4 +.Sp +You may combine these options; for example, use \fB\-aln\fR for assembly +listing without forms processing. The \fB=file\fR option, if used, must be +the last one. By itself, \fB\-a\fR defaults to \fB\-ahls\fR. +.RE +.IP "\fB\-\-alternate\fR" 4 +.IX Item "--alternate" +Begin in alternate macro mode. +.IP "\fB\-D\fR" 4 +.IX Item "-D" +Ignored. This option is accepted for script compatibility with calls to +other assemblers. +.IP "\fB\-\-defsym\fR \fIsym\fR\fB=\fR\fIvalue\fR" 4 +.IX Item "--defsym sym=value" +Define the symbol \fIsym\fR to be \fIvalue\fR before assembling the input file. +\&\fIvalue\fR must be an integer constant. As in C, a leading \fB0x\fR +indicates a hexadecimal value, and a leading \fB0\fR indicates an octal +value. The value of the symbol can be overridden inside a source file via the +use of a \f(CW\*(C`.set\*(C'\fR pseudo-op. +.IP "\fB\-f\fR" 4 +.IX Item "-f" +\&\*(L"fast\*(R"\-\-\-skip whitespace and comment preprocessing (assume source is +compiler output). +.IP "\fB\-g\fR" 4 +.IX Item "-g" +.PD 0 +.IP "\fB\-\-gen\-debug\fR" 4 +.IX Item "--gen-debug" +.PD +Generate debugging information for each assembler source line using whichever +debug format is preferred by the target. This currently means either \s-1STABS\s0, +\&\s-1ECOFF\s0 or \s-1DWARF2\s0. +.IP "\fB\-\-gstabs\fR" 4 +.IX Item "--gstabs" +Generate stabs debugging information for each assembler line. This +may help debugging assembler code, if the debugger can handle it. +.IP "\fB\-\-gstabs+\fR" 4 +.IX Item "--gstabs+" +Generate stabs debugging information for each assembler line, with \s-1GNU\s0 +extensions that probably only gdb can handle, and that could make other +debuggers crash or refuse to read your program. This +may help debugging assembler code. Currently the only \s-1GNU\s0 extension is +the location of the current working directory at assembling time. +.IP "\fB\-\-gdwarf\-2\fR" 4 +.IX Item "--gdwarf-2" +Generate \s-1DWARF2\s0 debugging information for each assembler line. This +may help debugging assembler code, if the debugger can handle it. Note\-\-\-this +option is only supported by some targets, not all of them. +.IP "\fB\-\-help\fR" 4 +.IX Item "--help" +Print a summary of the command line options and exit. +.IP "\fB\-\-target\-help\fR" 4 +.IX Item "--target-help" +Print a summary of all target specific options and exit. +.IP "\fB\-I\fR \fIdir\fR" 4 +.IX Item "-I dir" +Add directory \fIdir\fR to the search list for \f(CW\*(C`.include\*(C'\fR directives. +.IP "\fB\-J\fR" 4 +.IX Item "-J" +Don't warn about signed overflow. +.IP "\fB\-K\fR" 4 +.IX Item "-K" +Issue warnings when difference tables altered for long displacements. +.IP "\fB\-L\fR" 4 +.IX Item "-L" +.PD 0 +.IP "\fB\-\-keep\-locals\fR" 4 +.IX Item "--keep-locals" +.PD +Keep (in the symbol table) local symbols. These symbols start with +system-specific local label prefixes, typically \fB.L\fR for \s-1ELF\s0 systems +or \fBL\fR for traditional a.out systems. +.IP "\fB\-\-listing\-lhs\-width=\fR\fInumber\fR" 4 +.IX Item "--listing-lhs-width=number" +Set the maximum width, in words, of the output data column for an assembler +listing to \fInumber\fR. +.IP "\fB\-\-listing\-lhs\-width2=\fR\fInumber\fR" 4 +.IX Item "--listing-lhs-width2=number" +Set the maximum width, in words, of the output data column for continuation +lines in an assembler listing to \fInumber\fR. +.IP "\fB\-\-listing\-rhs\-width=\fR\fInumber\fR" 4 +.IX Item "--listing-rhs-width=number" +Set the maximum width of an input source line, as displayed in a listing, to +\&\fInumber\fR bytes. +.IP "\fB\-\-listing\-cont\-lines=\fR\fInumber\fR" 4 +.IX Item "--listing-cont-lines=number" +Set the maximum number of lines printed in a listing for a single line of input +to \fInumber\fR + 1. +.IP "\fB\-o\fR \fIobjfile\fR" 4 +.IX Item "-o objfile" +Name the object-file output from \fBas\fR \fIobjfile\fR. +.IP "\fB\-R\fR" 4 +.IX Item "-R" +Fold the data section into the text section. +.Sp +Set the default size of \s-1GAS\s0's hash tables to a prime number close to +\&\fInumber\fR. Increasing this value can reduce the length of time it takes the +assembler to perform its tasks, at the expense of increasing the assembler's +memory requirements. Similarly reducing this value can reduce the memory +requirements at the expense of speed. +.IP "\fB\-\-reduce\-memory\-overheads\fR" 4 +.IX Item "--reduce-memory-overheads" +This option reduces \s-1GAS\s0's memory requirements, at the expense of making the +assembly processes slower. Currently this switch is a synonym for +\&\fB\-\-hash\-size=4051\fR, but in the future it may have other effects as well. +.IP "\fB\-\-statistics\fR" 4 +.IX Item "--statistics" +Print the maximum space (in bytes) and total time (in seconds) used by +assembly. +.IP "\fB\-\-strip\-local\-absolute\fR" 4 +.IX Item "--strip-local-absolute" +Remove local absolute symbols from the outgoing symbol table. +.IP "\fB\-v\fR" 4 +.IX Item "-v" +.PD 0 +.IP "\fB\-version\fR" 4 +.IX Item "-version" +.PD +Print the \fBas\fR version. +.IP "\fB\-\-version\fR" 4 +.IX Item "--version" +Print the \fBas\fR version and exit. +.IP "\fB\-W\fR" 4 +.IX Item "-W" +.PD 0 +.IP "\fB\-\-no\-warn\fR" 4 +.IX Item "--no-warn" +.PD +Suppress warning messages. +.IP "\fB\-\-fatal\-warnings\fR" 4 +.IX Item "--fatal-warnings" +Treat warnings as errors. +.IP "\fB\-\-warn\fR" 4 +.IX Item "--warn" +Don't suppress warning messages or treat them as errors. +.IP "\fB\-w\fR" 4 +.IX Item "-w" +Ignored. +.IP "\fB\-x\fR" 4 +.IX Item "-x" +Ignored. +.IP "\fB\-Z\fR" 4 +.IX Item "-Z" +Generate an object file even after errors. +.IP "\fB\-\- |\fR \fIfiles\fR \fB...\fR" 4 +.IX Item "-- | files ..." +Standard input, or source files to assemble. +.PP +The following options are available when as is configured for +an \s-1ARC\s0 processor. +.IP "\fB\-marc[5|6|7|8]\fR" 4 +.IX Item "-marc[5|6|7|8]" +This option selects the core processor variant. +.IP "\fB\-EB | \-EL\fR" 4 +.IX Item "-EB | -EL" +Select either big-endian (\-EB) or little-endian (\-EL) output. +.PP +The following options are available when as is configured for the \s-1ARM\s0 +processor family. +.IP "\fB\-mcpu=\fR\fIprocessor\fR\fB[+\fR\fIextension\fR\fB...]\fR" 4 +.IX Item "-mcpu=processor[+extension...]" +Specify which \s-1ARM\s0 processor variant is the target. +.IP "\fB\-march=\fR\fIarchitecture\fR\fB[+\fR\fIextension\fR\fB...]\fR" 4 +.IX Item "-march=architecture[+extension...]" +Specify which \s-1ARM\s0 architecture variant is used by the target. +.IP "\fB\-mfpu=\fR\fIfloating-point-format\fR" 4 +.IX Item "-mfpu=floating-point-format" +Select which Floating Point architecture is the target. +.IP "\fB\-mfloat\-abi=\fR\fIabi\fR" 4 +.IX Item "-mfloat-abi=abi" +Select which floating point \s-1ABI\s0 is in use. +.IP "\fB\-mthumb\fR" 4 +.IX Item "-mthumb" +Enable Thumb only instruction decoding. +.IP "\fB\-mapcs\-32 | \-mapcs\-26 | \-mapcs\-float | \-mapcs\-reentrant\fR" 4 +.IX Item "-mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant" +Select which procedure calling convention is in use. +.IP "\fB\-EB | \-EL\fR" 4 +.IX Item "-EB | -EL" +Select either big-endian (\-EB) or little-endian (\-EL) output. +.IP "\fB\-mthumb\-interwork\fR" 4 +.IX Item "-mthumb-interwork" +Specify that the code has been generated with interworking between Thumb and +\&\s-1ARM\s0 code in mind. +.IP "\fB\-k\fR" 4 +.IX Item "-k" +Specify that \s-1PIC\s0 code has been generated. +.PP +See the info pages for documentation of the CRIS-specific options. +.PP +The following options are available when as is configured for +a D10V processor. +.IP "\fB\-O\fR" 4 +.IX Item "-O" +Optimize output by parallelizing instructions. +.PP +The following options are available when as is configured for a D30V +processor. +.IP "\fB\-O\fR" 4 +.IX Item "-O" +Optimize output by parallelizing instructions. +.IP "\fB\-n\fR" 4 +.IX Item "-n" +Warn when nops are generated. +.IP "\fB\-N\fR" 4 +.IX Item "-N" +Warn when a nop after a 32\-bit multiply instruction is generated. +.PP +The following options are available when as is configured for the +Intel 80960 processor. +.IP "\fB\-ACA | \-ACA_A | \-ACB | \-ACC | \-AKA | \-AKB | \-AKC | \-AMC\fR" 4 +.IX Item "-ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC" +Specify which variant of the 960 architecture is the target. +.IP "\fB\-b\fR" 4 +.IX Item "-b" +Add code to collect statistics about branches taken. +.IP "\fB\-no\-relax\fR" 4 +.IX Item "-no-relax" +Do not alter compare-and-branch instructions for long displacements; +error if necessary. +.PP +The following options are available when as is configured for the +Ubicom \s-1IP2K\s0 series. +.IP "\fB\-mip2022ext\fR" 4 +.IX Item "-mip2022ext" +Specifies that the extended \s-1IP2022\s0 instructions are allowed. +.IP "\fB\-mip2022\fR" 4 +.IX Item "-mip2022" +Restores the default behaviour, which restricts the permitted instructions to +just the basic \s-1IP2022\s0 ones. +.PP +The following options are available when as is configured for the +Renesas M32C and M16C processors. +.IP "\fB\-m32c\fR" 4 +.IX Item "-m32c" +Assemble M32C instructions. +.IP "\fB\-m16c\fR" 4 +.IX Item "-m16c" +Assemble M16C instructions (the default). +.PP +The following options are available when as is configured for the +Renesas M32R (formerly Mitsubishi M32R) series. +.IP "\fB\-\-m32rx\fR" 4 +.IX Item "--m32rx" +Specify which processor in the M32R family is the target. The default +is normally the M32R, but this option changes it to the M32RX. +.IP "\fB\-\-warn\-explicit\-parallel\-conflicts or \-\-Wp\fR" 4 +.IX Item "--warn-explicit-parallel-conflicts or --Wp" +Produce warning messages when questionable parallel constructs are +encountered. +.IP "\fB\-\-no\-warn\-explicit\-parallel\-conflicts or \-\-Wnp\fR" 4 +.IX Item "--no-warn-explicit-parallel-conflicts or --Wnp" +Do not produce warning messages when questionable parallel constructs are +encountered. +.PP +The following options are available when as is configured for the +Motorola 68000 series. +.IP "\fB\-l\fR" 4 +.IX Item "-l" +Shorten references to undefined symbols, to one word instead of two. +.IP "\fB\-m68000 | \-m68008 | \-m68010 | \-m68020 | \-m68030\fR" 4 +.IX Item "-m68000 | -m68008 | -m68010 | -m68020 | -m68030" +.PD 0 +.IP "\fB| \-m68040 | \-m68060 | \-m68302 | \-m68331 | \-m68332\fR" 4 +.IX Item "| -m68040 | -m68060 | -m68302 | -m68331 | -m68332" +.IP "\fB| \-m68333 | \-m68340 | \-mcpu32 | \-m5200\fR" 4 +.IX Item "| -m68333 | -m68340 | -mcpu32 | -m5200" +.PD +Specify what processor in the 68000 family is the target. The default +is normally the 68020, but this can be changed at configuration time. +.IP "\fB\-m68881 | \-m68882 | \-mno\-68881 | \-mno\-68882\fR" 4 +.IX Item "-m68881 | -m68882 | -mno-68881 | -mno-68882" +The target machine does (or does not) have a floating-point coprocessor. +The default is to assume a coprocessor for 68020, 68030, and cpu32. Although +the basic 68000 is not compatible with the 68881, a combination of the +two can be specified, since it's possible to do emulation of the +coprocessor instructions with the main processor. +.IP "\fB\-m68851 | \-mno\-68851\fR" 4 +.IX Item "-m68851 | -mno-68851" +The target machine does (or does not) have a memory-management +unit coprocessor. The default is to assume an \s-1MMU\s0 for 68020 and up. +.PP +For details about the \s-1PDP\-11\s0 machine dependent features options, +see \fBPDP\-11\-Options\fR. +.IP "\fB\-mpic | \-mno\-pic\fR" 4 +.IX Item "-mpic | -mno-pic" +Generate position-independent (or position-dependent) code. The +default is \fB\-mpic\fR. +.IP "\fB\-mall\fR" 4 +.IX Item "-mall" +.PD 0 +.IP "\fB\-mall\-extensions\fR" 4 +.IX Item "-mall-extensions" +.PD +Enable all instruction set extensions. This is the default. +.IP "\fB\-mno\-extensions\fR" 4 +.IX Item "-mno-extensions" +Disable all instruction set extensions. +.IP "\fB\-m\fR\fIextension\fR \fB| \-mno\-\fR\fIextension\fR" 4 +.IX Item "-mextension | -mno-extension" +Enable (or disable) a particular instruction set extension. +.IP "\fB\-m\fR\fIcpu\fR" 4 +.IX Item "-mcpu" +Enable the instruction set extensions supported by a particular \s-1CPU\s0, and +disable all other extensions. +.IP "\fB\-m\fR\fImachine\fR" 4 +.IX Item "-mmachine" +Enable the instruction set extensions supported by a particular machine +model, and disable all other extensions. +.PP +The following options are available when as is configured for +a picoJava processor. +.IP "\fB\-mb\fR" 4 +.IX Item "-mb" +Generate \*(L"big endian\*(R" format output. +.IP "\fB\-ml\fR" 4 +.IX Item "-ml" +Generate \*(L"little endian\*(R" format output. +.PP +The following options are available when as is configured for the +Motorola 68HC11 or 68HC12 series. +.IP "\fB\-m68hc11 | \-m68hc12 | \-m68hcs12\fR" 4 +.IX Item "-m68hc11 | -m68hc12 | -m68hcs12" +Specify what processor is the target. The default is +defined by the configuration option when building the assembler. +.IP "\fB\-mshort\fR" 4 +.IX Item "-mshort" +Specify to use the 16\-bit integer \s-1ABI\s0. +.IP "\fB\-mlong\fR" 4 +.IX Item "-mlong" +Specify to use the 32\-bit integer \s-1ABI\s0. +.IP "\fB\-mshort\-double\fR" 4 +.IX Item "-mshort-double" +Specify to use the 32\-bit double \s-1ABI\s0. +.IP "\fB\-mlong\-double\fR" 4 +.IX Item "-mlong-double" +Specify to use the 64\-bit double \s-1ABI\s0. +.IP "\fB\-\-force\-long\-branches\fR" 4 +.IX Item "--force-long-branches" +Relative branches are turned into absolute ones. This concerns +conditional branches, unconditional branches and branches to a +sub routine. +.IP "\fB\-S | \-\-short\-branches\fR" 4 +.IX Item "-S | --short-branches" +Do not turn relative branches into absolute ones +when the offset is out of range. +.IP "\fB\-\-strict\-direct\-mode\fR" 4 +.IX Item "--strict-direct-mode" +Do not turn the direct addressing mode into extended addressing mode +when the instruction does not support direct addressing mode. +.IP "\fB\-\-print\-insn\-syntax\fR" 4 +.IX Item "--print-insn-syntax" +Print the syntax of instruction in case of error. +.IP "\fB\-\-print\-opcodes\fR" 4 +.IX Item "--print-opcodes" +print the list of instructions with syntax and then exit. +.IP "\fB\-\-generate\-example\fR" 4 +.IX Item "--generate-example" +print an example of instruction for each possible instruction and then exit. +This option is only useful for testing \fBas\fR. +.PP +The following options are available when \fBas\fR is configured +for the \s-1SPARC\s0 architecture: +.IP "\fB\-Av6 | \-Av7 | \-Av8 | \-Asparclet | \-Asparclite\fR" 4 +.IX Item "-Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite" +.PD 0 +.IP "\fB\-Av8plus | \-Av8plusa | \-Av9 | \-Av9a\fR" 4 +.IX Item "-Av8plus | -Av8plusa | -Av9 | -Av9a" +.PD +Explicitly select a variant of the \s-1SPARC\s0 architecture. +.Sp +\&\fB\-Av8plus\fR and \fB\-Av8plusa\fR select a 32 bit environment. +\&\fB\-Av9\fR and \fB\-Av9a\fR select a 64 bit environment. +.Sp +\&\fB\-Av8plusa\fR and \fB\-Av9a\fR enable the \s-1SPARC\s0 V9 instruction set with +UltraSPARC extensions. +.IP "\fB\-xarch=v8plus | \-xarch=v8plusa\fR" 4 +.IX Item "-xarch=v8plus | -xarch=v8plusa" +For compatibility with the Solaris v9 assembler. These options are +equivalent to \-Av8plus and \-Av8plusa, respectively. +.IP "\fB\-bump\fR" 4 +.IX Item "-bump" +Warn when the assembler switches to another architecture. +.PP +The following options are available when as is configured for the 'c54x +architecture. +.IP "\fB\-mfar\-mode\fR" 4 +.IX Item "-mfar-mode" +Enable extended addressing mode. All addresses and relocations will assume +extended addressing (usually 23 bits). +.IP "\fB\-mcpu=\fR\fI\s-1CPU_VERSION\s0\fR" 4 +.IX Item "-mcpu=CPU_VERSION" +Sets the \s-1CPU\s0 version being compiled for. +.IP "\fB\-merrors\-to\-file\fR \fI\s-1FILENAME\s0\fR" 4 +.IX Item "-merrors-to-file FILENAME" +Redirect error output to a file, for broken systems which don't support such +behaviour in the shell. +.PP +The following options are available when as is configured for +a \s-1MIPS\s0 processor. +.IP "\fB\-G\fR \fInum\fR" 4 +.IX Item "-G num" +This option sets the largest size of an object that can be referenced +implicitly with the \f(CW\*(C`gp\*(C'\fR register. It is only accepted for targets that +use \s-1ECOFF\s0 format, such as a DECstation running Ultrix. The default value is 8. +.IP "\fB\-EB\fR" 4 +.IX Item "-EB" +Generate \*(L"big endian\*(R" format output. +.IP "\fB\-EL\fR" 4 +.IX Item "-EL" +Generate \*(L"little endian\*(R" format output. +.IP "\fB\-mips1\fR" 4 +.IX Item "-mips1" +.PD 0 +.IP "\fB\-mips2\fR" 4 +.IX Item "-mips2" +.IP "\fB\-mips3\fR" 4 +.IX Item "-mips3" +.IP "\fB\-mips4\fR" 4 +.IX Item "-mips4" +.IP "\fB\-mips5\fR" 4 +.IX Item "-mips5" +.IP "\fB\-mips32\fR" 4 +.IX Item "-mips32" +.IP "\fB\-mips32r2\fR" 4 +.IX Item "-mips32r2" +.IP "\fB\-mips64\fR" 4 +.IX Item "-mips64" +.IP "\fB\-mips64r2\fR" 4 +.IX Item "-mips64r2" +.PD +Generate code for a particular \s-1MIPS\s0 Instruction Set Architecture level. +\&\fB\-mips1\fR is an alias for \fB\-march=r3000\fR, \fB\-mips2\fR is an +alias for \fB\-march=r6000\fR, \fB\-mips3\fR is an alias for +\&\fB\-march=r4000\fR and \fB\-mips4\fR is an alias for \fB\-march=r8000\fR. +\&\fB\-mips5\fR, \fB\-mips32\fR, \fB\-mips32r2\fR, \fB\-mips64\fR, and +\&\fB\-mips64r2\fR +correspond to generic +\&\fB\s-1MIPS\s0 V\fR, \fB\s-1MIPS32\s0\fR, \fB\s-1MIPS32\s0 Release 2\fR, \fB\s-1MIPS64\s0\fR, +and \fB\s-1MIPS64\s0 Release 2\fR +\&\s-1ISA\s0 processors, respectively. +.IP "\fB\-march=\fR\fI\s-1CPU\s0\fR" 4 +.IX Item "-march=CPU" +Generate code for a particular \s-1MIPS\s0 cpu. +.IP "\fB\-mtune=\fR\fIcpu\fR" 4 +.IX Item "-mtune=cpu" +Schedule and tune for a particular \s-1MIPS\s0 cpu. +.IP "\fB\-mfix7000\fR" 4 +.IX Item "-mfix7000" +.PD 0 +.IP "\fB\-mno\-fix7000\fR" 4 +.IX Item "-mno-fix7000" +.PD +Cause nops to be inserted if the read of the destination register +of an mfhi or mflo instruction occurs in the following two instructions. +.IP "\fB\-mdebug\fR" 4 +.IX Item "-mdebug" +.PD 0 +.IP "\fB\-no\-mdebug\fR" 4 +.IX Item "-no-mdebug" +.PD +Cause stabs-style debugging output to go into an ECOFF-style .mdebug +section instead of the standard \s-1ELF\s0 .stabs sections. +.IP "\fB\-mpdr\fR" 4 +.IX Item "-mpdr" +.PD 0 +.IP "\fB\-mno\-pdr\fR" 4 +.IX Item "-mno-pdr" +.PD +Control generation of \f(CW\*(C`.pdr\*(C'\fR sections. +.IP "\fB\-mgp32\fR" 4 +.IX Item "-mgp32" +.PD 0 +.IP "\fB\-mfp32\fR" 4 +.IX Item "-mfp32" +.PD +The register sizes are normally inferred from the \s-1ISA\s0 and \s-1ABI\s0, but these +flags force a certain group of registers to be treated as 32 bits wide at +all times. \fB\-mgp32\fR controls the size of general-purpose registers +and \fB\-mfp32\fR controls the size of floating-point registers. +.IP "\fB\-mips16\fR" 4 +.IX Item "-mips16" +.PD 0 +.IP "\fB\-no\-mips16\fR" 4 +.IX Item "-no-mips16" +.PD +Generate code for the \s-1MIPS\s0 16 processor. This is equivalent to putting +\&\f(CW\*(C`.set mips16\*(C'\fR at the start of the assembly file. \fB\-no\-mips16\fR +turns off this option. +.IP "\fB\-msmartmips\fR" 4 +.IX Item "-msmartmips" +.PD 0 +.IP "\fB\-mno\-smartmips\fR" 4 +.IX Item "-mno-smartmips" +.PD +Enables the SmartMIPS extension to the \s-1MIPS32\s0 instruction set. This is +equivalent to putting \f(CW\*(C`.set smartmips\*(C'\fR at the start of the assembly file. +\&\fB\-mno\-smartmips\fR turns off this option. +.IP "\fB\-mips3d\fR" 4 +.IX Item "-mips3d" +.PD 0 +.IP "\fB\-no\-mips3d\fR" 4 +.IX Item "-no-mips3d" +.PD +Generate code for the \s-1MIPS\-3D\s0 Application Specific Extension. +This tells the assembler to accept \s-1MIPS\-3D\s0 instructions. +\&\fB\-no\-mips3d\fR turns off this option. +.IP "\fB\-mdmx\fR" 4 +.IX Item "-mdmx" +.PD 0 +.IP "\fB\-no\-mdmx\fR" 4 +.IX Item "-no-mdmx" +.PD +Generate code for the \s-1MDMX\s0 Application Specific Extension. +This tells the assembler to accept \s-1MDMX\s0 instructions. +\&\fB\-no\-mdmx\fR turns off this option. +.IP "\fB\-mdsp\fR" 4 +.IX Item "-mdsp" +.PD 0 +.IP "\fB\-mno\-dsp\fR" 4 +.IX Item "-mno-dsp" +.PD +Generate code for the \s-1DSP\s0 Release 1 Application Specific Extension. +This tells the assembler to accept \s-1DSP\s0 Release 1 instructions. +\&\fB\-mno\-dsp\fR turns off this option. +.IP "\fB\-mdspr2\fR" 4 +.IX Item "-mdspr2" +.PD 0 +.IP "\fB\-mno\-dspr2\fR" 4 +.IX Item "-mno-dspr2" +.PD +Generate code for the \s-1DSP\s0 Release 2 Application Specific Extension. +This option implies \-mdsp. +This tells the assembler to accept \s-1DSP\s0 Release 2 instructions. +\&\fB\-mno\-dspr2\fR turns off this option. +.IP "\fB\-mmt\fR" 4 +.IX Item "-mmt" +.PD 0 +.IP "\fB\-mno\-mt\fR" 4 +.IX Item "-mno-mt" +.PD +Generate code for the \s-1MT\s0 Application Specific Extension. +This tells the assembler to accept \s-1MT\s0 instructions. +\&\fB\-mno\-mt\fR turns off this option. +.IP "\fB\-\-construct\-floats\fR" 4 +.IX Item "--construct-floats" +.PD 0 +.IP "\fB\-\-no\-construct\-floats\fR" 4 +.IX Item "--no-construct-floats" +.PD +The \fB\-\-no\-construct\-floats\fR option disables the construction of +double width floating point constants by loading the two halves of the +value into the two single width floating point registers that make up +the double width register. By default \fB\-\-construct\-floats\fR is +selected, allowing construction of these floating point constants. +.IP "\fB\-\-emulation=\fR\fIname\fR" 4 +.IX Item "--emulation=name" +This option causes \fBas\fR to emulate \fBas\fR configured +for some other target, in all respects, including output format (choosing +between \s-1ELF\s0 and \s-1ECOFF\s0 only), handling of pseudo-opcodes which may generate +debugging information or store symbol table information, and default +endianness. The available configuration names are: \fBmipsecoff\fR, +\&\fBmipself\fR, \fBmipslecoff\fR, \fBmipsbecoff\fR, \fBmipslelf\fR, +\&\fBmipsbelf\fR. The first two do not alter the default endianness from that +of the primary target for which the assembler was configured; the others change +the default to little\- or big-endian as indicated by the \fBb\fR or \fBl\fR +in the name. Using \fB\-EB\fR or \fB\-EL\fR will override the endianness +selection in any case. +.Sp +This option is currently supported only when the primary target +\&\fBas\fR is configured for is a \s-1MIPS\s0 \s-1ELF\s0 or \s-1ECOFF\s0 target. +Furthermore, the primary target or others specified with +\&\fB\-\-enable\-targets=...\fR at configuration time must include support for +the other format, if both are to be available. For example, the Irix 5 +configuration includes support for both. +.Sp +Eventually, this option will support more configurations, with more +fine-grained control over the assembler's behavior, and will be supported for +more processors. +.IP "\fB\-nocpp\fR" 4 +.IX Item "-nocpp" +\&\fBas\fR ignores this option. It is accepted for compatibility with +the native tools. +.IP "\fB\-\-trap\fR" 4 +.IX Item "--trap" +.PD 0 +.IP "\fB\-\-no\-trap\fR" 4 +.IX Item "--no-trap" +.IP "\fB\-\-break\fR" 4 +.IX Item "--break" +.IP "\fB\-\-no\-break\fR" 4 +.IX Item "--no-break" +.PD +Control how to deal with multiplication overflow and division by zero. +\&\fB\-\-trap\fR or \fB\-\-no\-break\fR (which are synonyms) take a trap exception +(and only work for Instruction Set Architecture level 2 and higher); +\&\fB\-\-break\fR or \fB\-\-no\-trap\fR (also synonyms, and the default) take a +break exception. +.IP "\fB\-n\fR" 4 +.IX Item "-n" +When this option is used, \fBas\fR will issue a warning every +time it generates a nop instruction from a macro. +.PP +The following options are available when as is configured for +an MCore processor. +.IP "\fB\-jsri2bsr\fR" 4 +.IX Item "-jsri2bsr" +.PD 0 +.IP "\fB\-nojsri2bsr\fR" 4 +.IX Item "-nojsri2bsr" +.PD +Enable or disable the \s-1JSRI\s0 to \s-1BSR\s0 transformation. By default this is enabled. +The command line option \fB\-nojsri2bsr\fR can be used to disable it. +.IP "\fB\-sifilter\fR" 4 +.IX Item "-sifilter" +.PD 0 +.IP "\fB\-nosifilter\fR" 4 +.IX Item "-nosifilter" +.PD +Enable or disable the silicon filter behaviour. By default this is disabled. +The default can be overridden by the \fB\-sifilter\fR command line option. +.IP "\fB\-relax\fR" 4 +.IX Item "-relax" +Alter jump instructions for long displacements. +.IP "\fB\-mcpu=[210|340]\fR" 4 +.IX Item "-mcpu=[210|340]" +Select the cpu type on the target hardware. This controls which instructions +can be assembled. +.IP "\fB\-EB\fR" 4 +.IX Item "-EB" +Assemble for a big endian target. +.IP "\fB\-EL\fR" 4 +.IX Item "-EL" +Assemble for a little endian target. +.PP +See the info pages for documentation of the MMIX-specific options. +.PP +The following options are available when as is configured for +an Xtensa processor. +.IP "\fB\-\-text\-section\-literals | \-\-no\-text\-section\-literals\fR" 4 +.IX Item "--text-section-literals | --no-text-section-literals" +With \fB\-\-text\-section\-literals\fR, literal pools are interspersed +in the text section. The default is +\&\fB\-\-no\-text\-section\-literals\fR, which places literals in a +separate section in the output file. These options only affect literals +referenced via PC-relative \f(CW\*(C`L32R\*(C'\fR instructions; literals for +absolute mode \f(CW\*(C`L32R\*(C'\fR instructions are handled separately. +.IP "\fB\-\-absolute\-literals | \-\-no\-absolute\-literals\fR" 4 +.IX Item "--absolute-literals | --no-absolute-literals" +Indicate to the assembler whether \f(CW\*(C`L32R\*(C'\fR instructions use absolute +or PC-relative addressing. The default is to assume absolute addressing +if the Xtensa processor includes the absolute \f(CW\*(C`L32R\*(C'\fR addressing +option. Otherwise, only the PC-relative \f(CW\*(C`L32R\*(C'\fR mode can be used. +.IP "\fB\-\-target\-align | \-\-no\-target\-align\fR" 4 +.IX Item "--target-align | --no-target-align" +Enable or disable automatic alignment to reduce branch penalties at the +expense of some code density. The default is \fB\-\-target\-align\fR. +.IP "\fB\-\-longcalls | \-\-no\-longcalls\fR" 4 +.IX Item "--longcalls | --no-longcalls" +Enable or disable transformation of call instructions to allow calls +across a greater range of addresses. The default is +\&\fB\-\-no\-longcalls\fR. +.IP "\fB\-\-transform | \-\-no\-transform\fR" 4 +.IX Item "--transform | --no-transform" +Enable or disable all assembler transformations of Xtensa instructions. +The default is \fB\-\-transform\fR; +\&\fB\-\-no\-transform\fR should be used only in the rare cases when the +instructions must be exactly as specified in the assembly source. +.PP +The following options are available when as is configured for +a Z80 family processor. +.IP "\fB\-z80\fR" 4 +.IX Item "-z80" +Assemble for Z80 processor. +.IP "\fB\-r800\fR" 4 +.IX Item "-r800" +Assemble for R800 processor. +.IP "\fB\-ignore\-undocumented\-instructions\fR" 4 +.IX Item "-ignore-undocumented-instructions" +.PD 0 +.IP "\fB\-Wnud\fR" 4 +.IX Item "-Wnud" +.PD +Assemble undocumented Z80 instructions that also work on R800 without warning. +.IP "\fB\-ignore\-unportable\-instructions\fR" 4 +.IX Item "-ignore-unportable-instructions" +.PD 0 +.IP "\fB\-Wnup\fR" 4 +.IX Item "-Wnup" +.PD +Assemble all undocumented Z80 instructions without warning. +.IP "\fB\-warn\-undocumented\-instructions\fR" 4 +.IX Item "-warn-undocumented-instructions" +.PD 0 +.IP "\fB\-Wud\fR" 4 +.IX Item "-Wud" +.PD +Issue a warning for undocumented Z80 instructions that also work on R800. +.IP "\fB\-warn\-unportable\-instructions\fR" 4 +.IX Item "-warn-unportable-instructions" +.PD 0 +.IP "\fB\-Wup\fR" 4 +.IX Item "-Wup" +.PD +Issue a warning for undocumented Z80 instructions that do not work on R800. +.IP "\fB\-forbid\-undocumented\-instructions\fR" 4 +.IX Item "-forbid-undocumented-instructions" +.PD 0 +.IP "\fB\-Fud\fR" 4 +.IX Item "-Fud" +.PD +Treat all undocumented instructions as errors. +.IP "\fB\-forbid\-unportable\-instructions\fR" 4 +.IX Item "-forbid-unportable-instructions" +.PD 0 +.IP "\fB\-Fup\fR" 4 +.IX Item "-Fup" +.PD +Treat undocumented Z80 instructions that do not work on R800 as errors. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIgcc\fR\|(1), \fIld\fR\|(1), and the Info entries for \fIbinutils\fR and \fIld\fR. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001, 2002, +2006, 2007 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 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 \*(L"\s-1GNU\s0 Free Documentation License\*(R". diff --git a/gnu/usr.bin/binutils/ld/ld.1 b/gnu/usr.bin/binutils/ld/ld.1 new file mode 100644 index 0000000..d1e29b8 --- /dev/null +++ b/gnu/usr.bin/binutils/ld/ld.1 @@ -0,0 +1,2156 @@ +.\" $FreeBSD$ +.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "LD 1" +.TH LD 1 "2010-10-30" "binutils-2.17.50" "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +ld \- The GNU linker +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +ld [\fBoptions\fR] \fIobjfile\fR ... +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBld\fR combines a number of object and archive files, relocates +their data and ties up symbol references. Usually the last step in +compiling a program is to run \fBld\fR. +.PP +\&\fBld\fR accepts Linker Command Language files written in +a superset of \s-1AT&T\s0's Link Editor Command Language syntax, +to provide explicit and total control over the linking process. +.PP +This man page does not describe the command language; see the +\&\fBld\fR entry in \f(CW\*(C`info\*(C'\fR for full details on the command +language and on other aspects of the \s-1GNU\s0 linker. +.PP +This version of \fBld\fR uses the general purpose \s-1BFD\s0 libraries +to operate on object files. This allows \fBld\fR to read, combine, and +write object files in many different formats\-\-\-for example, \s-1COFF\s0 or +\&\f(CW\*(C`a.out\*(C'\fR. Different formats may be linked together to produce any +available kind of object file. +.PP +Aside from its flexibility, the \s-1GNU\s0 linker is more helpful than other +linkers in providing diagnostic information. Many linkers abandon +execution immediately upon encountering an error; whenever possible, +\&\fBld\fR continues executing, allowing you to identify other errors +(or, in some cases, to get an output file in spite of the error). +.PP +The \s-1GNU\s0 linker \fBld\fR is meant to cover a broad range of situations, +and to be as compatible as possible with other linkers. As a result, +you have many choices to control its behavior. +.SH "OPTIONS" +.IX Header "OPTIONS" +The linker supports a plethora of command-line options, but in actual +practice few of them are used in any particular context. +For instance, a frequent use of \fBld\fR is to link standard Unix +object files on a standard, supported Unix system. On such a system, to +link a file \f(CW\*(C`hello.o\*(C'\fR: +.PP +.Vb 1 +\& ld \-o <output> /lib/crt0.o hello.o \-lc +.Ve +.PP +This tells \fBld\fR to produce a file called \fIoutput\fR as the +result of linking the file \f(CW\*(C`/lib/crt0.o\*(C'\fR with \f(CW\*(C`hello.o\*(C'\fR and +the library \f(CW\*(C`libc.a\*(C'\fR, which will come from the standard search +directories. (See the discussion of the \fB\-l\fR option below.) +.PP +Some of the command-line options to \fBld\fR may be specified at any +point in the command line. However, options which refer to files, such +as \fB\-l\fR or \fB\-T\fR, cause the file to be read at the point at +which the option appears in the command line, relative to the object +files and other file options. Repeating non-file options with a +different argument will either have no further effect, or override prior +occurrences (those further to the left on the command line) of that +option. Options which may be meaningfully specified more than once are +noted in the descriptions below. +.PP +Non-option arguments are object files or archives which are to be linked +together. They may follow, precede, or be mixed in with command-line +options, except that an object file argument may not be placed between +an option and its argument. +.PP +Usually the linker is invoked with at least one object file, but you can +specify other forms of binary input files using \fB\-l\fR, \fB\-R\fR, +and the script command language. If \fIno\fR binary input files at all +are specified, the linker does not produce any output, and issues the +message \fBNo input files\fR. +.PP +If the linker cannot recognize the format of an object file, it will +assume that it is a linker script. A script specified in this way +augments the main linker script used for the link (either the default +linker script or the one specified by using \fB\-T\fR). This feature +permits the linker to link against a file which appears to be an object +or an archive, but actually merely defines some symbol values, or uses +\&\f(CW\*(C`INPUT\*(C'\fR or \f(CW\*(C`GROUP\*(C'\fR to load other objects. Note that +specifying a script in this way merely augments the main linker script; +use the \fB\-T\fR option to replace the default linker script entirely. +.PP +For options whose names are a single letter, +option arguments must either follow the option letter without intervening +whitespace, or be given as separate arguments immediately following the +option that requires them. +.PP +For options whose names are multiple letters, either one dash or two can +precede the option name; for example, \fB\-trace\-symbol\fR and +\&\fB\-\-trace\-symbol\fR are equivalent. Note\-\-\-there is one exception to +this rule. Multiple letter options that start with a lower case 'o' can +only be preceded by two dashes. This is to reduce confusion with the +\&\fB\-o\fR option. So for example \fB\-omagic\fR sets the output file +name to \fBmagic\fR whereas \fB\-\-omagic\fR sets the \s-1NMAGIC\s0 flag on the +output. +.PP +Arguments to multiple-letter options must either be separated from the +option name by an equals sign, or be given as separate arguments +immediately following the option that requires them. For example, +\&\fB\-\-trace\-symbol foo\fR and \fB\-\-trace\-symbol=foo\fR are equivalent. +Unique abbreviations of the names of multiple-letter options are +accepted. +.PP +Note\-\-\-if the linker is being invoked indirectly, via a compiler driver +(e.g. \fBgcc\fR) then all the linker command line options should be +prefixed by \fB\-Wl,\fR (or whatever is appropriate for the particular +compiler driver) like this: +.PP +.Vb 1 +\& gcc \-Wl,\-\-startgroup foo.o bar.o \-Wl,\-\-endgroup +.Ve +.PP +This is important, because otherwise the compiler driver program may +silently drop the linker options, resulting in a bad link. +.PP +Here is a table of the generic command line switches accepted by the \s-1GNU\s0 +linker: +.IP "\fB@\fR\fIfile\fR" 4 +.IX Item "@file" +Read command-line options from \fIfile\fR. The options read are +inserted in place of the original @\fIfile\fR option. If \fIfile\fR +does not exist, or cannot be read, then the option will be treated +literally, and not removed. +.Sp +Options in \fIfile\fR are separated by whitespace. A whitespace +character may be included in an option by surrounding the entire +option in either single or double quotes. Any character (including a +backslash) may be included by prefixing the character to be included +with a backslash. The \fIfile\fR may itself contain additional +@\fIfile\fR options; any such options will be processed recursively. +.IP "\fB\-a\fR\fIkeyword\fR" 4 +.IX Item "-akeyword" +This option is supported for \s-1HP/UX\s0 compatibility. The \fIkeyword\fR +argument must be one of the strings \fBarchive\fR, \fBshared\fR, or +\&\fBdefault\fR. \fB\-aarchive\fR is functionally equivalent to +\&\fB\-Bstatic\fR, and the other two keywords are functionally equivalent +to \fB\-Bdynamic\fR. This option may be used any number of times. +.IP "\fB\-A\fR\fIarchitecture\fR" 4 +.IX Item "-Aarchitecture" +.PD 0 +.IP "\fB\-\-architecture=\fR\fIarchitecture\fR" 4 +.IX Item "--architecture=architecture" +.PD +In the current release of \fBld\fR, this option is useful only for the +Intel 960 family of architectures. In that \fBld\fR configuration, the +\&\fIarchitecture\fR argument identifies the particular architecture in +the 960 family, enabling some safeguards and modifying the +archive-library search path. +.Sp +Future releases of \fBld\fR may support similar functionality for +other architecture families. +.IP "\fB\-b\fR \fIinput-format\fR" 4 +.IX Item "-b input-format" +.PD 0 +.IP "\fB\-\-format=\fR\fIinput-format\fR" 4 +.IX Item "--format=input-format" +.PD +\&\fBld\fR may be configured to support more than one kind of object +file. If your \fBld\fR is configured this way, you can use the +\&\fB\-b\fR option to specify the binary format for input object files +that follow this option on the command line. Even when \fBld\fR is +configured to support alternative object formats, you don't usually need +to specify this, as \fBld\fR should be configured to expect as a +default input format the most usual format on each machine. +\&\fIinput-format\fR is a text string, the name of a particular format +supported by the \s-1BFD\s0 libraries. (You can list the available binary +formats with \fBobjdump \-i\fR.) +.Sp +You may want to use this option if you are linking files with an unusual +binary format. You can also use \fB\-b\fR to switch formats explicitly (when +linking object files of different formats), by including +\&\fB\-b\fR \fIinput-format\fR before each group of object files in a +particular format. +.Sp +The default format is taken from the environment variable +\&\f(CW\*(C`GNUTARGET\*(C'\fR. +.Sp +You can also define the input format from a script, using the command +\&\f(CW\*(C`TARGET\*(C'\fR; +.IP "\fB\-c\fR \fIMRI-commandfile\fR" 4 +.IX Item "-c MRI-commandfile" +.PD 0 +.IP "\fB\-\-mri\-script=\fR\fIMRI-commandfile\fR" 4 +.IX Item "--mri-script=MRI-commandfile" +.PD +For compatibility with linkers produced by \s-1MRI\s0, \fBld\fR accepts script +files written in an alternate, restricted command language, described in +the \s-1MRI\s0 Compatible Script Files section of \s-1GNU\s0 ld documentation. +Introduce \s-1MRI\s0 script files with +the option \fB\-c\fR; use the \fB\-T\fR option to run linker +scripts written in the general-purpose \fBld\fR scripting language. +If \fIMRI-cmdfile\fR does not exist, \fBld\fR looks for it in the directories +specified by any \fB\-L\fR options. +.IP "\fB\-d\fR" 4 +.IX Item "-d" +.PD 0 +.IP "\fB\-dc\fR" 4 +.IX Item "-dc" +.IP "\fB\-dp\fR" 4 +.IX Item "-dp" +.PD +These three options are equivalent; multiple forms are supported for +compatibility with other linkers. They assign space to common symbols +even if a relocatable output file is specified (with \fB\-r\fR). The +script command \f(CW\*(C`FORCE_COMMON_ALLOCATION\*(C'\fR has the same effect. +.IP "\fB\-e\fR \fIentry\fR" 4 +.IX Item "-e entry" +.PD 0 +.IP "\fB\-\-entry=\fR\fIentry\fR" 4 +.IX Item "--entry=entry" +.PD +Use \fIentry\fR as the explicit symbol for beginning execution of your +program, rather than the default entry point. If there is no symbol +named \fIentry\fR, the linker will try to parse \fIentry\fR as a number, +and use that as the entry address (the number will be interpreted in +base 10; you may use a leading \fB0x\fR for base 16, or a leading +\&\fB0\fR for base 8). +.IP "\fB\-\-exclude\-libs\fR \fIlib\fR\fB,\fR\fIlib\fR\fB,...\fR" 4 +.IX Item "--exclude-libs lib,lib,..." +Specifies a list of archive libraries from which symbols should not be automatically +exported. The library names may be delimited by commas or colons. Specifying +\&\f(CW\*(C`\-\-exclude\-libs ALL\*(C'\fR excludes symbols in all archive libraries from +automatic export. This option is available only for the i386 \s-1PE\s0 targeted +port of the linker and for \s-1ELF\s0 targeted ports. For i386 \s-1PE\s0, symbols +explicitly listed in a .def file are still exported, regardless of this +option. For \s-1ELF\s0 targeted ports, symbols affected by this option will +be treated as hidden. +.IP "\fB\-E\fR" 4 +.IX Item "-E" +.PD 0 +.IP "\fB\-\-export\-dynamic\fR" 4 +.IX Item "--export-dynamic" +.PD +When creating a dynamically linked executable, add all symbols to the +dynamic symbol table. The dynamic symbol table is the set of symbols +which are visible from dynamic objects at run time. +.Sp +If you do not use this option, the dynamic symbol table will normally +contain only those symbols which are referenced by some dynamic object +mentioned in the link. +.Sp +If you use \f(CW\*(C`dlopen\*(C'\fR to load a dynamic object which needs to refer +back to the symbols defined by the program, rather than some other +dynamic object, then you will probably need to use this option when +linking the program itself. +.Sp +You can also use the dynamic list to control what symbols should +be added to the dynamic symbol table if the output format supports it. +See the description of \fB\-\-dynamic\-list\fR. +.IP "\fB\-EB\fR" 4 +.IX Item "-EB" +Link big-endian objects. This affects the default output format. +.IP "\fB\-EL\fR" 4 +.IX Item "-EL" +Link little-endian objects. This affects the default output format. +.IP "\fB\-f\fR" 4 +.IX Item "-f" +.PD 0 +.IP "\fB\-\-auxiliary\fR \fIname\fR" 4 +.IX Item "--auxiliary name" +.PD +When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_AUXILIARY\s0 field +to the specified name. This tells the dynamic linker that the symbol +table of the shared object should be used as an auxiliary filter on the +symbol table of the shared object \fIname\fR. +.Sp +If you later link a program against this filter object, then, when you +run the program, the dynamic linker will see the \s-1DT_AUXILIARY\s0 field. If +the dynamic linker resolves any symbols from the filter object, it will +first check whether there is a definition in the shared object +\&\fIname\fR. If there is one, it will be used instead of the definition +in the filter object. The shared object \fIname\fR need not exist. +Thus the shared object \fIname\fR may be used to provide an alternative +implementation of certain functions, perhaps for debugging or for +machine specific performance. +.Sp +This option may be specified more than once. The \s-1DT_AUXILIARY\s0 entries +will be created in the order in which they appear on the command line. +.IP "\fB\-F\fR \fIname\fR" 4 +.IX Item "-F name" +.PD 0 +.IP "\fB\-\-filter\fR \fIname\fR" 4 +.IX Item "--filter name" +.PD +When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_FILTER\s0 field to +the specified name. This tells the dynamic linker that the symbol table +of the shared object which is being created should be used as a filter +on the symbol table of the shared object \fIname\fR. +.Sp +If you later link a program against this filter object, then, when you +run the program, the dynamic linker will see the \s-1DT_FILTER\s0 field. The +dynamic linker will resolve symbols according to the symbol table of the +filter object as usual, but it will actually link to the definitions +found in the shared object \fIname\fR. Thus the filter object can be +used to select a subset of the symbols provided by the object +\&\fIname\fR. +.Sp +Some older linkers used the \fB\-F\fR option throughout a compilation +toolchain for specifying object-file format for both input and output +object files. +The \s-1GNU\s0 linker uses other mechanisms for this purpose: the +\&\fB\-b\fR, \fB\-\-format\fR, \fB\-\-oformat\fR options, the +\&\f(CW\*(C`TARGET\*(C'\fR command in linker scripts, and the \f(CW\*(C`GNUTARGET\*(C'\fR +environment variable. +The \s-1GNU\s0 linker will ignore the \fB\-F\fR option when not +creating an \s-1ELF\s0 shared object. +.IP "\fB\-fini\fR \fIname\fR" 4 +.IX Item "-fini name" +When creating an \s-1ELF\s0 executable or shared object, call \s-1NAME\s0 when the +executable or shared object is unloaded, by setting \s-1DT_FINI\s0 to the +address of the function. By default, the linker uses \f(CW\*(C`_fini\*(C'\fR as +the function to call. +.IP "\fB\-g\fR" 4 +.IX Item "-g" +Ignored. Provided for compatibility with other tools. +.IP "\fB\-G\fR\fIvalue\fR" 4 +.IX Item "-Gvalue" +.PD 0 +.IP "\fB\-\-gpsize=\fR\fIvalue\fR" 4 +.IX Item "--gpsize=value" +.PD +Set the maximum size of objects to be optimized using the \s-1GP\s0 register to +\&\fIsize\fR. This is only meaningful for object file formats such as +\&\s-1MIPS\s0 \s-1ECOFF\s0 which supports putting large and small objects into different +sections. This is ignored for other object file formats. +.IP "\fB\-h\fR\fIname\fR" 4 +.IX Item "-hname" +.PD 0 +.IP "\fB\-soname=\fR\fIname\fR" 4 +.IX Item "-soname=name" +.PD +When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_SONAME\s0 field to +the specified name. When an executable is linked with a shared object +which has a \s-1DT_SONAME\s0 field, then when the executable is run the dynamic +linker will attempt to load the shared object specified by the \s-1DT_SONAME\s0 +field rather than the using the file name given to the linker. +.IP "\fB\-i\fR" 4 +.IX Item "-i" +Perform an incremental link (same as option \fB\-r\fR). +.IP "\fB\-init\fR \fIname\fR" 4 +.IX Item "-init name" +When creating an \s-1ELF\s0 executable or shared object, call \s-1NAME\s0 when the +executable or shared object is loaded, by setting \s-1DT_INIT\s0 to the address +of the function. By default, the linker uses \f(CW\*(C`_init\*(C'\fR as the +function to call. +.IP "\fB\-l\fR\fInamespec\fR" 4 +.IX Item "-lnamespec" +.PD 0 +.IP "\fB\-\-library=\fR\fInamespec\fR" 4 +.IX Item "--library=namespec" +.PD +Add the archive or object file specified by \fInamespec\fR to the +list of files to link. This option may be used any number of times. +If \fInamespec\fR is of the form \fI:\fIfilename\fI\fR, \fBld\fR +will search the library path for a file called \fIfilename\fR, otherise it +will search the library path for a file called \fIlib\fInamespec\fI.a\fR. +.Sp +On systems which support shared libraries, \fBld\fR may also search for +files other than \fIlib\fInamespec\fI.a\fR. Specifically, on \s-1ELF\s0 +and SunOS systems, \fBld\fR will search a directory for a library +called \fIlib\fInamespec\fI.so\fR before searching for one called +\&\fIlib\fInamespec\fI.a\fR. (By convention, a \f(CW\*(C`.so\*(C'\fR extension +indicates a shared library.) Note that this behavior does not apply +to \fI:\fIfilename\fI\fR, which always specifies a file called +\&\fIfilename\fR. +.Sp +The linker will search an archive only once, at the location where it is +specified on the command line. If the archive defines a symbol which +was undefined in some object which appeared before the archive on the +command line, the linker will include the appropriate file(s) from the +archive. However, an undefined symbol in an object appearing later on +the command line will not cause the linker to search the archive again. +.Sp +See the \fB\-(\fR option for a way to force the linker to search +archives multiple times. +.Sp +You may list the same archive multiple times on the command line. +.Sp +This type of archive searching is standard for Unix linkers. However, +if you are using \fBld\fR on \s-1AIX\s0, note that it is different from the +behaviour of the \s-1AIX\s0 linker. +.IP "\fB\-L\fR\fIsearchdir\fR" 4 +.IX Item "-Lsearchdir" +.PD 0 +.IP "\fB\-\-library\-path=\fR\fIsearchdir\fR" 4 +.IX Item "--library-path=searchdir" +.PD +Add path \fIsearchdir\fR to the list of paths that \fBld\fR will search +for archive libraries and \fBld\fR control scripts. You may use this +option any number of times. The directories are searched in the order +in which they are specified on the command line. Directories specified +on the command line are searched before the default directories. All +\&\fB\-L\fR options apply to all \fB\-l\fR options, regardless of the +order in which the options appear. +.Sp +If \fIsearchdir\fR begins with \f(CW\*(C`=\*(C'\fR, then the \f(CW\*(C`=\*(C'\fR will be replaced +by the \fIsysroot prefix\fR, a path specified when the linker is configured. +.Sp +The default set of paths searched (without being specified with +\&\fB\-L\fR) depends on which emulation mode \fBld\fR is using, and in +some cases also on how it was configured. +.Sp +The paths can also be specified in a link script with the +\&\f(CW\*(C`SEARCH_DIR\*(C'\fR command. Directories specified this way are searched +at the point in which the linker script appears in the command line. +.IP "\fB\-m\fR\fIemulation\fR" 4 +.IX Item "-memulation" +Emulate the \fIemulation\fR linker. You can list the available +emulations with the \fB\-\-verbose\fR or \fB\-V\fR options. +.Sp +If the \fB\-m\fR option is not used, the emulation is taken from the +\&\f(CW\*(C`LDEMULATION\*(C'\fR environment variable, if that is defined. +.Sp +Otherwise, the default emulation depends upon how the linker was +configured. +.IP "\fB\-M\fR" 4 +.IX Item "-M" +.PD 0 +.IP "\fB\-\-print\-map\fR" 4 +.IX Item "--print-map" +.PD +Print a link map to the standard output. A link map provides +information about the link, including the following: +.RS 4 +.IP "\(bu" 4 +Where object files are mapped into memory. +.IP "\(bu" 4 +How common symbols are allocated. +.IP "\(bu" 4 +All archive members included in the link, with a mention of the symbol +which caused the archive member to be brought in. +.IP "\(bu" 4 +The values assigned to symbols. +.Sp +Note \- symbols whose values are computed by an expression which +involves a reference to a previous value of the same symbol may not +have correct result displayed in the link map. This is because the +linker discards intermediate results and only retains the final value +of an expression. Under such circumstances the linker will display +the final value enclosed by square brackets. Thus for example a +linker script containing: +.Sp +.Vb 3 +\& foo = 1 +\& foo = foo * 4 +\& foo = foo + 8 +.Ve +.Sp +will produce the following output in the link map if the \fB\-M\fR +option is used: +.Sp +.Vb 3 +\& 0x00000001 foo = 0x1 +\& [0x0000000c] foo = (foo * 0x4) +\& [0x0000000c] foo = (foo + 0x8) +.Ve +.Sp +See \fBExpressions\fR for more information about expressions in linker +scripts. +.RE +.RS 4 +.RE +.IP "\fB\-n\fR" 4 +.IX Item "-n" +.PD 0 +.IP "\fB\-\-nmagic\fR" 4 +.IX Item "--nmagic" +.PD +Turn off page alignment of sections, and mark the output as +\&\f(CW\*(C`NMAGIC\*(C'\fR if possible. +.IP "\fB\-N\fR" 4 +.IX Item "-N" +.PD 0 +.IP "\fB\-\-omagic\fR" 4 +.IX Item "--omagic" +.PD +Set the text and data sections to be readable and writable. Also, do +not page-align the data segment, and disable linking against shared +libraries. If the output format supports Unix style magic numbers, +mark the output as \f(CW\*(C`OMAGIC\*(C'\fR. Note: Although a writable text section +is allowed for PE-COFF targets, it does not conform to the format +specification published by Microsoft. +.IP "\fB\-\-no\-omagic\fR" 4 +.IX Item "--no-omagic" +This option negates most of the effects of the \fB\-N\fR option. It +sets the text section to be read-only, and forces the data segment to +be page-aligned. Note \- this option does not enable linking against +shared libraries. Use \fB\-Bdynamic\fR for this. +.IP "\fB\-o\fR \fIoutput\fR" 4 +.IX Item "-o output" +.PD 0 +.IP "\fB\-\-output=\fR\fIoutput\fR" 4 +.IX Item "--output=output" +.PD +Use \fIoutput\fR as the name for the program produced by \fBld\fR; if this +option is not specified, the name \fIa.out\fR is used by default. The +script command \f(CW\*(C`OUTPUT\*(C'\fR can also specify the output file name. +.IP "\fB\-O\fR \fIlevel\fR" 4 +.IX Item "-O level" +If \fIlevel\fR is a numeric values greater than zero \fBld\fR optimizes +the output. This might take significantly longer and therefore probably +should only be enabled for the final binary. +.IP "\fB\-q\fR" 4 +.IX Item "-q" +.PD 0 +.IP "\fB\-\-emit\-relocs\fR" 4 +.IX Item "--emit-relocs" +.PD +Leave relocation sections and contents in fully linked executables. +Post link analysis and optimization tools may need this information in +order to perform correct modifications of executables. This results +in larger executables. +.Sp +This option is currently only supported on \s-1ELF\s0 platforms. +.IP "\fB\-\-force\-dynamic\fR" 4 +.IX Item "--force-dynamic" +Force the output file to have dynamic sections. This option is specific +to VxWorks targets. +.IP "\fB\-r\fR" 4 +.IX Item "-r" +.PD 0 +.IP "\fB\-\-relocatable\fR" 4 +.IX Item "--relocatable" +.PD +Generate relocatable output\-\-\-i.e., generate an output file that can in +turn serve as input to \fBld\fR. This is often called \fIpartial +linking\fR. As a side effect, in environments that support standard Unix +magic numbers, this option also sets the output file's magic number to +\&\f(CW\*(C`OMAGIC\*(C'\fR. +If this option is not specified, an absolute file is produced. When +linking \*(C+ programs, this option \fIwill not\fR resolve references to +constructors; to do that, use \fB\-Ur\fR. +.Sp +When an input file does not have the same format as the output file, +partial linking is only supported if that input file does not contain any +relocations. Different output formats can have further restrictions; for +example some \f(CW\*(C`a.out\*(C'\fR\-based formats do not support partial linking +with input files in other formats at all. +.Sp +This option does the same thing as \fB\-i\fR. +.IP "\fB\-R\fR \fIfilename\fR" 4 +.IX Item "-R filename" +.PD 0 +.IP "\fB\-\-just\-symbols=\fR\fIfilename\fR" 4 +.IX Item "--just-symbols=filename" +.PD +Read symbol names and their addresses from \fIfilename\fR, but do not +relocate it or include it in the output. This allows your output file +to refer symbolically to absolute locations of memory defined in other +programs. You may use this option more than once. +.Sp +For compatibility with other \s-1ELF\s0 linkers, if the \fB\-R\fR option is +followed by a directory name, rather than a file name, it is treated as +the \fB\-rpath\fR option. +.IP "\fB\-s\fR" 4 +.IX Item "-s" +.PD 0 +.IP "\fB\-\-strip\-all\fR" 4 +.IX Item "--strip-all" +.PD +Omit all symbol information from the output file. +.IP "\fB\-S\fR" 4 +.IX Item "-S" +.PD 0 +.IP "\fB\-\-strip\-debug\fR" 4 +.IX Item "--strip-debug" +.PD +Omit debugger symbol information (but not all symbols) from the output file. +.IP "\fB\-t\fR" 4 +.IX Item "-t" +.PD 0 +.IP "\fB\-\-trace\fR" 4 +.IX Item "--trace" +.PD +Print the names of the input files as \fBld\fR processes them. +.IP "\fB\-T\fR \fIscriptfile\fR" 4 +.IX Item "-T scriptfile" +.PD 0 +.IP "\fB\-\-script=\fR\fIscriptfile\fR" 4 +.IX Item "--script=scriptfile" +.PD +Use \fIscriptfile\fR as the linker script. This script replaces +\&\fBld\fR's default linker script (rather than adding to it), so +\&\fIcommandfile\fR must specify everything necessary to describe the +output file. If \fIscriptfile\fR does not exist in +the current directory, \f(CW\*(C`ld\*(C'\fR looks for it in the directories +specified by any preceding \fB\-L\fR options. Multiple \fB\-T\fR +options accumulate. +.IP "\fB\-dT\fR \fIscriptfile\fR" 4 +.IX Item "-dT scriptfile" +.PD 0 +.IP "\fB\-\-default\-script=\fR\fIscriptfile\fR" 4 +.IX Item "--default-script=scriptfile" +.PD +Use \fIscriptfile\fR as the default linker script. +.Sp +This option is similar to the \fB\-\-script\fR option except that +processing of the script is delayed until after the rest of the +command line has been processed. This allows options placed after the +\&\fB\-\-default\-script\fR option on the command line to affect the +behaviour of the linker script, which can be important when the linker +command line cannot be directly controlled by the user. (eg because +the command line is being constructed by another tool, such as +\&\fBgcc\fR). +.IP "\fB\-u\fR \fIsymbol\fR" 4 +.IX Item "-u symbol" +.PD 0 +.IP "\fB\-\-undefined=\fR\fIsymbol\fR" 4 +.IX Item "--undefined=symbol" +.PD +Force \fIsymbol\fR to be entered in the output file as an undefined +symbol. Doing this may, for example, trigger linking of additional +modules from standard libraries. \fB\-u\fR may be repeated with +different option arguments to enter additional undefined symbols. This +option is equivalent to the \f(CW\*(C`EXTERN\*(C'\fR linker script command. +.IP "\fB\-Ur\fR" 4 +.IX Item "-Ur" +For anything other than \*(C+ programs, this option is equivalent to +\&\fB\-r\fR: it generates relocatable output\-\-\-i.e., an output file that can in +turn serve as input to \fBld\fR. When linking \*(C+ programs, \fB\-Ur\fR +\&\fIdoes\fR resolve references to constructors, unlike \fB\-r\fR. +It does not work to use \fB\-Ur\fR on files that were themselves linked +with \fB\-Ur\fR; once the constructor table has been built, it cannot +be added to. Use \fB\-Ur\fR only for the last partial link, and +\&\fB\-r\fR for the others. +.IP "\fB\-\-unique[=\fR\fI\s-1SECTION\s0\fR\fB]\fR" 4 +.IX Item "--unique[=SECTION]" +Creates a separate output section for every input section matching +\&\fI\s-1SECTION\s0\fR, or if the optional wildcard \fI\s-1SECTION\s0\fR argument is +missing, for every orphan input section. An orphan section is one not +specifically mentioned in a linker script. You may use this option +multiple times on the command line; It prevents the normal merging of +input sections with the same name, overriding output section assignments +in a linker script. +.IP "\fB\-v\fR" 4 +.IX Item "-v" +.PD 0 +.IP "\fB\-\-version\fR" 4 +.IX Item "--version" +.IP "\fB\-V\fR" 4 +.IX Item "-V" +.PD +Display the version number for \fBld\fR. The \fB\-V\fR option also +lists the supported emulations. +.IP "\fB\-x\fR" 4 +.IX Item "-x" +.PD 0 +.IP "\fB\-\-discard\-all\fR" 4 +.IX Item "--discard-all" +.PD +Delete all local symbols. +.IP "\fB\-X\fR" 4 +.IX Item "-X" +.PD 0 +.IP "\fB\-\-discard\-locals\fR" 4 +.IX Item "--discard-locals" +.PD +Delete all temporary local symbols. (These symbols start with +system-specific local label prefixes, typically \fB.L\fR for \s-1ELF\s0 systems +or \fBL\fR for traditional a.out systems.) +.IP "\fB\-y\fR \fIsymbol\fR" 4 +.IX Item "-y symbol" +.PD 0 +.IP "\fB\-\-trace\-symbol=\fR\fIsymbol\fR" 4 +.IX Item "--trace-symbol=symbol" +.PD +Print the name of each linked file in which \fIsymbol\fR appears. This +option may be given any number of times. On many systems it is necessary +to prepend an underscore. +.Sp +This option is useful when you have an undefined symbol in your link but +don't know where the reference is coming from. +.IP "\fB\-Y\fR \fIpath\fR" 4 +.IX Item "-Y path" +Add \fIpath\fR to the default library search path. This option exists +for Solaris compatibility. +.IP "\fB\-z\fR \fIkeyword\fR" 4 +.IX Item "-z keyword" +The recognized keywords are: +.RS 4 +.IP "\fBcombreloc\fR" 4 +.IX Item "combreloc" +Combines multiple reloc sections and sorts them to make dynamic symbol +lookup caching possible. +.IP "\fBdefs\fR" 4 +.IX Item "defs" +Disallows undefined symbols in object files. Undefined symbols in +shared libraries are still allowed. +.IP "\fBexecstack\fR" 4 +.IX Item "execstack" +Marks the object as requiring executable stack. +.IP "\fBinitfirst\fR" 4 +.IX Item "initfirst" +This option is only meaningful when building a shared object. +It marks the object so that its runtime initialization will occur +before the runtime initialization of any other objects brought into +the process at the same time. Similarly the runtime finalization of +the object will occur after the runtime finalization of any other +objects. +.IP "\fBinterpose\fR" 4 +.IX Item "interpose" +Marks the object that its symbol table interposes before all symbols +but the primary executable. +.IP "\fBlazy\fR" 4 +.IX Item "lazy" +When generating an executable or shared library, mark it to tell the +dynamic linker to defer function call resolution to the point when +the function is called (lazy binding), rather than at load time. +Lazy binding is the default. +.IP "\fBloadfltr\fR" 4 +.IX Item "loadfltr" +Marks the object that its filters be processed immediately at +runtime. +.IP "\fBmuldefs\fR" 4 +.IX Item "muldefs" +Allows multiple definitions. +.IP "\fBnocombreloc\fR" 4 +.IX Item "nocombreloc" +Disables multiple reloc sections combining. +.IP "\fBnocopyreloc\fR" 4 +.IX Item "nocopyreloc" +Disables production of copy relocs. +.IP "\fBnodefaultlib\fR" 4 +.IX Item "nodefaultlib" +Marks the object that the search for dependencies of this object will +ignore any default library search paths. +.IP "\fBnodelete\fR" 4 +.IX Item "nodelete" +Marks the object shouldn't be unloaded at runtime. +.IP "\fBnodlopen\fR" 4 +.IX Item "nodlopen" +Marks the object not available to \f(CW\*(C`dlopen\*(C'\fR. +.IP "\fBnodump\fR" 4 +.IX Item "nodump" +Marks the object can not be dumped by \f(CW\*(C`dldump\*(C'\fR. +.IP "\fBnoexecstack\fR" 4 +.IX Item "noexecstack" +Marks the object as not requiring executable stack. +.IP "\fBnorelro\fR" 4 +.IX Item "norelro" +Don't create an \s-1ELF\s0 \f(CW\*(C`PT_GNU_RELRO\*(C'\fR segment header in the object. +.IP "\fBnow\fR" 4 +.IX Item "now" +When generating an executable or shared library, mark it to tell the +dynamic linker to resolve all symbols when the program is started, or +when the shared library is linked to using dlopen, instead of +deferring function call resolution to the point when the function is +first called. +.IP "\fBorigin\fR" 4 +.IX Item "origin" +Marks the object may contain \f(CW$ORIGIN\fR. +.IP "\fBrelro\fR" 4 +.IX Item "relro" +Create an \s-1ELF\s0 \f(CW\*(C`PT_GNU_RELRO\*(C'\fR segment header in the object. +.IP "\fBmax\-page\-size=\fR\fIvalue\fR" 4 +.IX Item "max-page-size=value" +Set the emulation maximum page size to \fIvalue\fR. +.IP "\fBcommon\-page\-size=\fR\fIvalue\fR" 4 +.IX Item "common-page-size=value" +Set the emulation common page size to \fIvalue\fR. +.RE +.RS 4 +.Sp +Other keywords are ignored for Solaris compatibility. +.RE +.IP "\fB\-(\fR \fIarchives\fR \fB\-)\fR" 4 +.IX Item "-( archives -)" +.PD 0 +.IP "\fB\-\-start\-group\fR \fIarchives\fR \fB\-\-end\-group\fR" 4 +.IX Item "--start-group archives --end-group" +.PD +The \fIarchives\fR should be a list of archive files. They may be +either explicit file names, or \fB\-l\fR options. +.Sp +The specified archives are searched repeatedly until no new undefined +references are created. Normally, an archive is searched only once in +the order that it is specified on the command line. If a symbol in that +archive is needed to resolve an undefined symbol referred to by an +object in an archive that appears later on the command line, the linker +would not be able to resolve that reference. By grouping the archives, +they all be searched repeatedly until all possible references are +resolved. +.Sp +Using this option has a significant performance cost. It is best to use +it only when there are unavoidable circular references between two or +more archives. +.IP "\fB\-\-accept\-unknown\-input\-arch\fR" 4 +.IX Item "--accept-unknown-input-arch" +.PD 0 +.IP "\fB\-\-no\-accept\-unknown\-input\-arch\fR" 4 +.IX Item "--no-accept-unknown-input-arch" +.PD +Tells the linker to accept input files whose architecture cannot be +recognised. The assumption is that the user knows what they are doing +and deliberately wants to link in these unknown input files. This was +the default behaviour of the linker, before release 2.14. The default +behaviour from release 2.14 onwards is to reject such input files, and +so the \fB\-\-accept\-unknown\-input\-arch\fR option has been added to +restore the old behaviour. +.IP "\fB\-\-as\-needed\fR" 4 +.IX Item "--as-needed" +.PD 0 +.IP "\fB\-\-no\-as\-needed\fR" 4 +.IX Item "--no-as-needed" +.PD +This option affects \s-1ELF\s0 \s-1DT_NEEDED\s0 tags for dynamic libraries mentioned +on the command line after the \fB\-\-as\-needed\fR option. Normally, +the linker will add a \s-1DT_NEEDED\s0 tag for each dynamic library mentioned +on the command line, regardless of whether the library is actually +needed. \fB\-\-as\-needed\fR causes \s-1DT_NEEDED\s0 tags to only be emitted +for libraries that satisfy some symbol reference from regular objects +which is undefined at the point that the library was linked. +\&\fB\-\-no\-as\-needed\fR restores the default behaviour. +.IP "\fB\-\-add\-needed\fR" 4 +.IX Item "--add-needed" +.PD 0 +.IP "\fB\-\-no\-add\-needed\fR" 4 +.IX Item "--no-add-needed" +.PD +This option affects the treatment of dynamic libraries from \s-1ELF\s0 +\&\s-1DT_NEEDED\s0 tags in dynamic libraries mentioned on the command line after +the \fB\-\-no\-add\-needed\fR option. Normally, the linker will add +a \s-1DT_NEEDED\s0 tag for each dynamic library from \s-1DT_NEEDED\s0 tags. +\&\fB\-\-no\-add\-needed\fR causes \s-1DT_NEEDED\s0 tags will never be emitted +for those libraries from \s-1DT_NEEDED\s0 tags. \fB\-\-add\-needed\fR restores +the default behaviour. +.IP "\fB\-assert\fR \fIkeyword\fR" 4 +.IX Item "-assert keyword" +This option is ignored for SunOS compatibility. +.IP "\fB\-Bdynamic\fR" 4 +.IX Item "-Bdynamic" +.PD 0 +.IP "\fB\-dy\fR" 4 +.IX Item "-dy" +.IP "\fB\-call_shared\fR" 4 +.IX Item "-call_shared" +.PD +Link against dynamic libraries. This is only meaningful on platforms +for which shared libraries are supported. This option is normally the +default on such platforms. The different variants of this option are +for compatibility with various systems. You may use this option +multiple times on the command line: it affects library searching for +\&\fB\-l\fR options which follow it. +.IP "\fB\-Bgroup\fR" 4 +.IX Item "-Bgroup" +Set the \f(CW\*(C`DF_1_GROUP\*(C'\fR flag in the \f(CW\*(C`DT_FLAGS_1\*(C'\fR entry in the dynamic +section. This causes the runtime linker to handle lookups in this +object and its dependencies to be performed only inside the group. +\&\fB\-\-unresolved\-symbols=report\-all\fR is implied. This option is +only meaningful on \s-1ELF\s0 platforms which support shared libraries. +.IP "\fB\-Bstatic\fR" 4 +.IX Item "-Bstatic" +.PD 0 +.IP "\fB\-dn\fR" 4 +.IX Item "-dn" +.IP "\fB\-non_shared\fR" 4 +.IX Item "-non_shared" +.IP "\fB\-static\fR" 4 +.IX Item "-static" +.PD +Do not link against shared libraries. This is only meaningful on +platforms for which shared libraries are supported. The different +variants of this option are for compatibility with various systems. You +may use this option multiple times on the command line: it affects +library searching for \fB\-l\fR options which follow it. This +option also implies \fB\-\-unresolved\-symbols=report\-all\fR. This +option can be used with \fB\-shared\fR. Doing so means that a +shared library is being created but that all of the library's external +references must be resolved by pulling in entries from static +libraries. +.IP "\fB\-Bsymbolic\fR" 4 +.IX Item "-Bsymbolic" +When creating a shared library, bind references to global symbols to the +definition within the shared library, if any. Normally, it is possible +for a program linked against a shared library to override the definition +within the shared library. This option is only meaningful on \s-1ELF\s0 +platforms which support shared libraries. +.IP "\fB\-Bsymbolic\-functions\fR" 4 +.IX Item "-Bsymbolic-functions" +When creating a shared library, bind references to global function +symbols to the definition within the shared library, if any. +This option is only meaningful on \s-1ELF\s0 platforms which support shared +libraries. +.IP "\fB\-\-dynamic\-list=\fR\fIdynamic-list-file\fR" 4 +.IX Item "--dynamic-list=dynamic-list-file" +Specify the name of a dynamic list file to the linker. This is +typically used when creating shared libraries to specify a list of +global symbols whose references shouldn't be bound to the definition +within the shared library, or creating dynamically linked executables +to specify a list of symbols which should be added to the symbol table +in the executable. This option is only meaningful on \s-1ELF\s0 platforms +which support shared libraries. +.Sp +The format of the dynamic list is the same as the version node without +scope and node name. See \fB\s-1VERSION\s0\fR for more information. +.IP "\fB\-\-dynamic\-list\-data\fR" 4 +.IX Item "--dynamic-list-data" +Include all global data symbols to the dynamic list. +.IP "\fB\-\-dynamic\-list\-cpp\-new\fR" 4 +.IX Item "--dynamic-list-cpp-new" +Provide the builtin dynamic list for \*(C+ operator new and delete. It +is mainly useful for building shared libstdc++. +.IP "\fB\-\-dynamic\-list\-cpp\-typeinfo\fR" 4 +.IX Item "--dynamic-list-cpp-typeinfo" +Provide the builtin dynamic list for \*(C+ runtime type identification. +.IP "\fB\-\-check\-sections\fR" 4 +.IX Item "--check-sections" +.PD 0 +.IP "\fB\-\-no\-check\-sections\fR" 4 +.IX Item "--no-check-sections" +.PD +Asks the linker \fInot\fR to check section addresses after they have +been assigned to see if there are any overlaps. Normally the linker will +perform this check, and if it finds any overlaps it will produce +suitable error messages. The linker does know about, and does make +allowances for sections in overlays. The default behaviour can be +restored by using the command line switch \fB\-\-check\-sections\fR. +.IP "\fB\-\-cref\fR" 4 +.IX Item "--cref" +Output a cross reference table. If a linker map file is being +generated, the cross reference table is printed to the map file. +Otherwise, it is printed on the standard output. +.Sp +The format of the table is intentionally simple, so that it may be +easily processed by a script if necessary. The symbols are printed out, +sorted by name. For each symbol, a list of file names is given. If the +symbol is defined, the first file listed is the location of the +definition. The remaining files contain references to the symbol. +.IP "\fB\-\-no\-define\-common\fR" 4 +.IX Item "--no-define-common" +This option inhibits the assignment of addresses to common symbols. +The script command \f(CW\*(C`INHIBIT_COMMON_ALLOCATION\*(C'\fR has the same effect. +.Sp +The \fB\-\-no\-define\-common\fR option allows decoupling +the decision to assign addresses to Common symbols from the choice +of the output file type; otherwise a non-Relocatable output type +forces assigning addresses to Common symbols. +Using \fB\-\-no\-define\-common\fR allows Common symbols that are referenced +from a shared library to be assigned addresses only in the main program. +This eliminates the unused duplicate space in the shared library, +and also prevents any possible confusion over resolving to the wrong +duplicate when there are many dynamic modules with specialized search +paths for runtime symbol resolution. +.IP "\fB\-\-defsym\fR \fIsymbol\fR\fB=\fR\fIexpression\fR" 4 +.IX Item "--defsym symbol=expression" +Create a global symbol in the output file, containing the absolute +address given by \fIexpression\fR. You may use this option as many +times as necessary to define multiple symbols in the command line. A +limited form of arithmetic is supported for the \fIexpression\fR in this +context: you may give a hexadecimal constant or the name of an existing +symbol, or use \f(CW\*(C`+\*(C'\fR and \f(CW\*(C`\-\*(C'\fR to add or subtract hexadecimal +constants or symbols. If you need more elaborate expressions, consider +using the linker command language from a script. \fINote:\fR there should be no white +space between \fIsymbol\fR, the equals sign ("\fB=\fR"), and +\&\fIexpression\fR. +.IP "\fB\-\-demangle[=\fR\fIstyle\fR\fB]\fR" 4 +.IX Item "--demangle[=style]" +.PD 0 +.IP "\fB\-\-no\-demangle\fR" 4 +.IX Item "--no-demangle" +.PD +These options control whether to demangle symbol names in error messages +and other output. When the linker is told to demangle, it tries to +present symbol names in a readable fashion: it strips leading +underscores if they are used by the object file format, and converts \*(C+ +mangled symbol names into user readable names. Different compilers have +different mangling styles. The optional demangling style argument can be used +to choose an appropriate demangling style for your compiler. The linker will +demangle by default unless the environment variable \fB\s-1COLLECT_NO_DEMANGLE\s0\fR +is set. These options may be used to override the default. +.IP "\fB\-\-dynamic\-linker\fR \fIfile\fR" 4 +.IX Item "--dynamic-linker file" +Set the name of the dynamic linker. This is only meaningful when +generating dynamically linked \s-1ELF\s0 executables. The default dynamic +linker is normally correct; don't use this unless you know what you are +doing. +.IP "\fB\-\-fatal\-warnings\fR" 4 +.IX Item "--fatal-warnings" +Treat all warnings as errors. +.IP "\fB\-\-force\-exe\-suffix\fR" 4 +.IX Item "--force-exe-suffix" +Make sure that an output file has a .exe suffix. +.Sp +If a successfully built fully linked output file does not have a +\&\f(CW\*(C`.exe\*(C'\fR or \f(CW\*(C`.dll\*(C'\fR suffix, this option forces the linker to copy +the output file to one of the same name with a \f(CW\*(C`.exe\*(C'\fR suffix. This +option is useful when using unmodified Unix makefiles on a Microsoft +Windows host, since some versions of Windows won't run an image unless +it ends in a \f(CW\*(C`.exe\*(C'\fR suffix. +.IP "\fB\-\-gc\-sections\fR" 4 +.IX Item "--gc-sections" +.PD 0 +.IP "\fB\-\-no\-gc\-sections\fR" 4 +.IX Item "--no-gc-sections" +.PD +Enable garbage collection of unused input sections. It is ignored on +targets that do not support this option. This option is not compatible +with \fB\-r\fR or \fB\-\-emit\-relocs\fR. The default behaviour (of not +performing this garbage collection) can be restored by specifying +\&\fB\-\-no\-gc\-sections\fR on the command line. +.IP "\fB\-\-print\-gc\-sections\fR" 4 +.IX Item "--print-gc-sections" +.PD 0 +.IP "\fB\-\-no\-print\-gc\-sections\fR" 4 +.IX Item "--no-print-gc-sections" +.PD +List all sections removed by garbage collection. The listing is +printed on stderr. This option is only effective if garbage +collection has been enabled via the \fB\-\-gc\-sections\fR) option. The +default behaviour (of not listing the sections that are removed) can +be restored by specifying \fB\-\-no\-print\-gc\-sections\fR on the command +line. +.IP "\fB\-\-help\fR" 4 +.IX Item "--help" +Print a summary of the command-line options on the standard output and exit. +.IP "\fB\-\-target\-help\fR" 4 +.IX Item "--target-help" +Print a summary of all target specific options on the standard output and exit. +.IP "\fB\-Map\fR \fImapfile\fR" 4 +.IX Item "-Map mapfile" +Print a link map to the file \fImapfile\fR. See the description of the +\&\fB\-M\fR option, above. +.IP "\fB\-\-no\-keep\-memory\fR" 4 +.IX Item "--no-keep-memory" +\&\fBld\fR normally optimizes for speed over memory usage by caching the +symbol tables of input files in memory. This option tells \fBld\fR to +instead optimize for memory usage, by rereading the symbol tables as +necessary. This may be required if \fBld\fR runs out of memory space +while linking a large executable. +.IP "\fB\-\-no\-undefined\fR" 4 +.IX Item "--no-undefined" +.PD 0 +.IP "\fB\-z defs\fR" 4 +.IX Item "-z defs" +.PD +Report unresolved symbol references from regular object files. This +is done even if the linker is creating a non-symbolic shared library. +The switch \fB\-\-[no\-]allow\-shlib\-undefined\fR controls the +behaviour for reporting unresolved references found in shared +libraries being linked in. +.IP "\fB\-\-allow\-multiple\-definition\fR" 4 +.IX Item "--allow-multiple-definition" +.PD 0 +.IP "\fB\-z muldefs\fR" 4 +.IX Item "-z muldefs" +.PD +Normally when a symbol is defined multiple times, the linker will +report a fatal error. These options allow multiple definitions and the +first definition will be used. +.IP "\fB\-\-allow\-shlib\-undefined\fR" 4 +.IX Item "--allow-shlib-undefined" +.PD 0 +.IP "\fB\-\-no\-allow\-shlib\-undefined\fR" 4 +.IX Item "--no-allow-shlib-undefined" +.PD +Allows (the default) or disallows undefined symbols in shared libraries. +This switch is similar to \fB\-\-no\-undefined\fR except that it +determines the behaviour when the undefined symbols are in a +shared library rather than a regular object file. It does not affect +how undefined symbols in regular object files are handled. +.Sp +The reason that \fB\-\-allow\-shlib\-undefined\fR is the default is that +the shared library being specified at link time may not be the same as +the one that is available at load time, so the symbols might actually be +resolvable at load time. Plus there are some systems, (eg BeOS) where +undefined symbols in shared libraries is normal. (The kernel patches +them at load time to select which function is most appropriate +for the current architecture. This is used for example to dynamically +select an appropriate memset function). Apparently it is also normal +for \s-1HPPA\s0 shared libraries to have undefined symbols. +.IP "\fB\-\-no\-undefined\-version\fR" 4 +.IX Item "--no-undefined-version" +Normally when a symbol has an undefined version, the linker will ignore +it. This option disallows symbols with undefined version and a fatal error +will be issued instead. +.IP "\fB\-\-default\-symver\fR" 4 +.IX Item "--default-symver" +Create and use a default symbol version (the soname) for unversioned +exported symbols. +.IP "\fB\-\-default\-imported\-symver\fR" 4 +.IX Item "--default-imported-symver" +Create and use a default symbol version (the soname) for unversioned +imported symbols. +.IP "\fB\-\-no\-warn\-mismatch\fR" 4 +.IX Item "--no-warn-mismatch" +Normally \fBld\fR will give an error if you try to link together input +files that are mismatched for some reason, perhaps because they have +been compiled for different processors or for different endiannesses. +This option tells \fBld\fR that it should silently permit such possible +errors. This option should only be used with care, in cases when you +have taken some special action that ensures that the linker errors are +inappropriate. +.IP "\fB\-\-no\-warn\-search\-mismatch\fR" 4 +.IX Item "--no-warn-search-mismatch" +Normally \fBld\fR will give a warning if it finds an incompatible +library during a library search. This option silences the warning. +.IP "\fB\-\-no\-whole\-archive\fR" 4 +.IX Item "--no-whole-archive" +Turn off the effect of the \fB\-\-whole\-archive\fR option for subsequent +archive files. +.IP "\fB\-\-noinhibit\-exec\fR" 4 +.IX Item "--noinhibit-exec" +Retain the executable output file whenever it is still usable. +Normally, the linker will not produce an output file if it encounters +errors during the link process; it exits without writing an output file +when it issues any error whatsoever. +.IP "\fB\-nostdlib\fR" 4 +.IX Item "-nostdlib" +Only search library directories explicitly specified on the +command line. Library directories specified in linker scripts +(including linker scripts specified on the command line) are ignored. +.IP "\fB\-\-oformat\fR \fIoutput-format\fR" 4 +.IX Item "--oformat output-format" +\&\fBld\fR may be configured to support more than one kind of object +file. If your \fBld\fR is configured this way, you can use the +\&\fB\-\-oformat\fR option to specify the binary format for the output +object file. Even when \fBld\fR is configured to support alternative +object formats, you don't usually need to specify this, as \fBld\fR +should be configured to produce as a default output format the most +usual format on each machine. \fIoutput-format\fR is a text string, the +name of a particular format supported by the \s-1BFD\s0 libraries. (You can +list the available binary formats with \fBobjdump \-i\fR.) The script +command \f(CW\*(C`OUTPUT_FORMAT\*(C'\fR can also specify the output format, but +this option overrides it. +.IP "\fB\-pie\fR" 4 +.IX Item "-pie" +.PD 0 +.IP "\fB\-\-pic\-executable\fR" 4 +.IX Item "--pic-executable" +.PD +Create a position independent executable. This is currently only supported on +\&\s-1ELF\s0 platforms. Position independent executables are similar to shared +libraries in that they are relocated by the dynamic linker to the virtual +address the \s-1OS\s0 chooses for them (which can vary between invocations). Like +normal dynamically linked executables they can be executed and symbols +defined in the executable cannot be overridden by shared libraries. +.IP "\fB\-qmagic\fR" 4 +.IX Item "-qmagic" +This option is ignored for Linux compatibility. +.IP "\fB\-Qy\fR" 4 +.IX Item "-Qy" +This option is ignored for \s-1SVR4\s0 compatibility. +.IP "\fB\-\-relax\fR" 4 +.IX Item "--relax" +An option with machine dependent effects. +This option is only supported on a few targets. +.Sp +On some platforms, the \fB\-\-relax\fR option performs global +optimizations that become possible when the linker resolves addressing +in the program, such as relaxing address modes and synthesizing new +instructions in the output object file. +.Sp +On some platforms these link time global optimizations may make symbolic +debugging of the resulting executable impossible. +This is known to be +the case for the Matsushita \s-1MN10200\s0 and \s-1MN10300\s0 family of processors. +.Sp +On platforms where this is not supported, \fB\-\-relax\fR is accepted, +but ignored. +.IP "\fB\-\-retain\-symbols\-file\fR \fIfilename\fR" 4 +.IX Item "--retain-symbols-file filename" +Retain \fIonly\fR the symbols listed in the file \fIfilename\fR, +discarding all others. \fIfilename\fR is simply a flat file, with one +symbol name per line. This option is especially useful in environments +(such as VxWorks) +where a large global symbol table is accumulated gradually, to conserve +run-time memory. +.Sp +\&\fB\-\-retain\-symbols\-file\fR does \fInot\fR discard undefined symbols, +or symbols needed for relocations. +.Sp +You may only specify \fB\-\-retain\-symbols\-file\fR once in the command +line. It overrides \fB\-s\fR and \fB\-S\fR. +.IP "\fB\-rpath\fR \fIdir\fR" 4 +.IX Item "-rpath dir" +Add a directory to the runtime library search path. This is used when +linking an \s-1ELF\s0 executable with shared objects. All \fB\-rpath\fR +arguments are concatenated and passed to the runtime linker, which uses +them to locate shared objects at runtime. The \fB\-rpath\fR option is +also used when locating shared objects which are needed by shared +objects explicitly included in the link; see the description of the +\&\fB\-rpath\-link\fR option. If \fB\-rpath\fR is not used when linking an +\&\s-1ELF\s0 executable, the contents of the environment variable +\&\f(CW\*(C`LD_RUN_PATH\*(C'\fR will be used if it is defined. +.Sp +The \fB\-rpath\fR option may also be used on SunOS. By default, on +SunOS, the linker will form a runtime search patch out of all the +\&\fB\-L\fR options it is given. If a \fB\-rpath\fR option is used, the +runtime search path will be formed exclusively using the \fB\-rpath\fR +options, ignoring the \fB\-L\fR options. This can be useful when using +gcc, which adds many \fB\-L\fR options which may be on \s-1NFS\s0 mounted +file systems. +.Sp +For compatibility with other \s-1ELF\s0 linkers, if the \fB\-R\fR option is +followed by a directory name, rather than a file name, it is treated as +the \fB\-rpath\fR option. +.IP "\fB\-rpath\-link\fR \fI\s-1DIR\s0\fR" 4 +.IX Item "-rpath-link DIR" +When using \s-1ELF\s0 or SunOS, one shared library may require another. This +happens when an \f(CW\*(C`ld \-shared\*(C'\fR link includes a shared library as one +of the input files. +.Sp +When the linker encounters such a dependency when doing a non-shared, +non-relocatable link, it will automatically try to locate the required +shared library and include it in the link, if it is not included +explicitly. In such a case, the \fB\-rpath\-link\fR option +specifies the first set of directories to search. The +\&\fB\-rpath\-link\fR option may specify a sequence of directory names +either by specifying a list of names separated by colons, or by +appearing multiple times. +.Sp +This option should be used with caution as it overrides the search path +that may have been hard compiled into a shared library. In such a case it +is possible to use unintentionally a different search path than the +runtime linker would do. +.Sp +The linker uses the following search paths to locate required shared +libraries: +.RS 4 +.IP "1." 4 +Any directories specified by \fB\-rpath\-link\fR options. +.IP "2." 4 +Any directories specified by \fB\-rpath\fR options. The difference +between \fB\-rpath\fR and \fB\-rpath\-link\fR is that directories +specified by \fB\-rpath\fR options are included in the executable and +used at runtime, whereas the \fB\-rpath\-link\fR option is only effective +at link time. Searching \fB\-rpath\fR in this way is only supported +by native linkers and cross linkers which have been configured with +the \fB\-\-with\-sysroot\fR option. +.IP "3." 4 +On an \s-1ELF\s0 system, if the \fB\-rpath\fR and \f(CW\*(C`rpath\-link\*(C'\fR options +were not used, search the contents of the environment variable +\&\f(CW\*(C`LD_RUN_PATH\*(C'\fR. It is for the native linker only. +.IP "4." 4 +On SunOS, if the \fB\-rpath\fR option was not used, search any +directories specified using \fB\-L\fR options. +.IP "5." 4 +For a native linker, the contents of the environment variable +\&\f(CW\*(C`LD_LIBRARY_PATH\*(C'\fR. +.IP "6." 4 +For a native \s-1ELF\s0 linker, the directories in \f(CW\*(C`DT_RUNPATH\*(C'\fR or +\&\f(CW\*(C`DT_RPATH\*(C'\fR of a shared library are searched for shared +libraries needed by it. The \f(CW\*(C`DT_RPATH\*(C'\fR entries are ignored if +\&\f(CW\*(C`DT_RUNPATH\*(C'\fR entries exist. +.IP "7." 4 +The default directories, normally \fI/lib\fR and \fI/usr/lib\fR. +.IP "8." 4 +For a native linker on an \s-1ELF\s0 system, if the file \fI/etc/ld.so.conf\fR +exists, the list of directories found in that file. +.RE +.RS 4 +.Sp +If the required shared library is not found, the linker will issue a +warning and continue with the link. +.RE +.IP "\fB\-shared\fR" 4 +.IX Item "-shared" +.PD 0 +.IP "\fB\-Bshareable\fR" 4 +.IX Item "-Bshareable" +.PD +Create a shared library. This is currently only supported on \s-1ELF\s0, \s-1XCOFF\s0 +and SunOS platforms. On SunOS, the linker will automatically create a +shared library if the \fB\-e\fR option is not used and there are +undefined symbols in the link. +.IP "\fB\-\-sort\-common\fR" 4 +.IX Item "--sort-common" +This option tells \fBld\fR to sort the common symbols by size when it +places them in the appropriate output sections. First come all the one +byte symbols, then all the two byte, then all the four byte, and then +everything else. This is to prevent gaps between symbols due to +alignment constraints. +.IP "\fB\-\-sort\-section name\fR" 4 +.IX Item "--sort-section name" +This option will apply \f(CW\*(C`SORT_BY_NAME\*(C'\fR to all wildcard section +patterns in the linker script. +.IP "\fB\-\-sort\-section alignment\fR" 4 +.IX Item "--sort-section alignment" +This option will apply \f(CW\*(C`SORT_BY_ALIGNMENT\*(C'\fR to all wildcard section +patterns in the linker script. +.IP "\fB\-\-split\-by\-file [\fR\fIsize\fR\fB]\fR" 4 +.IX Item "--split-by-file [size]" +Similar to \fB\-\-split\-by\-reloc\fR but creates a new output section for +each input file when \fIsize\fR is reached. \fIsize\fR defaults to a +size of 1 if not given. +.IP "\fB\-\-split\-by\-reloc [\fR\fIcount\fR\fB]\fR" 4 +.IX Item "--split-by-reloc [count]" +Tries to creates extra sections in the output file so that no single +output section in the file contains more than \fIcount\fR relocations. +This is useful when generating huge relocatable files for downloading into +certain real time kernels with the \s-1COFF\s0 object file format; since \s-1COFF\s0 +cannot represent more than 65535 relocations in a single section. Note +that this will fail to work with object file formats which do not +support arbitrary sections. The linker will not split up individual +input sections for redistribution, so if a single input section contains +more than \fIcount\fR relocations one output section will contain that +many relocations. \fIcount\fR defaults to a value of 32768. +.IP "\fB\-\-stats\fR" 4 +.IX Item "--stats" +Compute and display statistics about the operation of the linker, such +as execution time and memory usage. +.IP "\fB\-\-sysroot=\fR\fIdirectory\fR" 4 +.IX Item "--sysroot=directory" +Use \fIdirectory\fR as the location of the sysroot, overriding the +configure-time default. This option is only supported by linkers +that were configured using \fB\-\-with\-sysroot\fR. +.IP "\fB\-\-traditional\-format\fR" 4 +.IX Item "--traditional-format" +For some targets, the output of \fBld\fR is different in some ways from +the output of some existing linker. This switch requests \fBld\fR to +use the traditional format instead. +.Sp +For example, on SunOS, \fBld\fR combines duplicate entries in the +symbol string table. This can reduce the size of an output file with +full debugging information by over 30 percent. Unfortunately, the SunOS +\&\f(CW\*(C`dbx\*(C'\fR program can not read the resulting program (\f(CW\*(C`gdb\*(C'\fR has no +trouble). The \fB\-\-traditional\-format\fR switch tells \fBld\fR to not +combine duplicate entries. +.IP "\fB\-\-section\-start\fR \fIsectionname\fR\fB=\fR\fIorg\fR" 4 +.IX Item "--section-start sectionname=org" +Locate a section in the output file at the absolute +address given by \fIorg\fR. You may use this option as many +times as necessary to locate multiple sections in the command +line. +\&\fIorg\fR must be a single hexadecimal integer; +for compatibility with other linkers, you may omit the leading +\&\fB0x\fR usually associated with hexadecimal values. \fINote:\fR there +should be no white space between \fIsectionname\fR, the equals +sign ("\fB=\fR"), and \fIorg\fR. +.IP "\fB\-Tbss\fR \fIorg\fR" 4 +.IX Item "-Tbss org" +.PD 0 +.IP "\fB\-Tdata\fR \fIorg\fR" 4 +.IX Item "-Tdata org" +.IP "\fB\-Ttext\fR \fIorg\fR" 4 +.IX Item "-Ttext org" +.PD +Same as \-\-section\-start, with \f(CW\*(C`.bss\*(C'\fR, \f(CW\*(C`.data\*(C'\fR or +\&\f(CW\*(C`.text\*(C'\fR as the \fIsectionname\fR. +.IP "\fB\-\-unresolved\-symbols=\fR\fImethod\fR" 4 +.IX Item "--unresolved-symbols=method" +Determine how to handle unresolved symbols. There are four possible +values for \fBmethod\fR: +.RS 4 +.IP "\fBignore-all\fR" 4 +.IX Item "ignore-all" +Do not report any unresolved symbols. +.IP "\fBreport-all\fR" 4 +.IX Item "report-all" +Report all unresolved symbols. This is the default. +.IP "\fBignore-in-object-files\fR" 4 +.IX Item "ignore-in-object-files" +Report unresolved symbols that are contained in shared libraries, but +ignore them if they come from regular object files. +.IP "\fBignore-in-shared-libs\fR" 4 +.IX Item "ignore-in-shared-libs" +Report unresolved symbols that come from regular object files, but +ignore them if they come from shared libraries. This can be useful +when creating a dynamic binary and it is known that all the shared +libraries that it should be referencing are included on the linker's +command line. +.RE +.RS 4 +.Sp +The behaviour for shared libraries on their own can also be controlled +by the \fB\-\-[no\-]allow\-shlib\-undefined\fR option. +.Sp +Normally the linker will generate an error message for each reported +unresolved symbol but the option \fB\-\-warn\-unresolved\-symbols\fR +can change this to a warning. +.RE +.IP "\fB\-\-dll\-verbose\fR" 4 +.IX Item "--dll-verbose" +.PD 0 +.IP "\fB\-\-verbose\fR" 4 +.IX Item "--verbose" +.PD +Display the version number for \fBld\fR and list the linker emulations +supported. Display which input files can and cannot be opened. Display +the linker script being used by the linker. +.IP "\fB\-\-version\-script=\fR\fIversion-scriptfile\fR" 4 +.IX Item "--version-script=version-scriptfile" +Specify the name of a version script to the linker. This is typically +used when creating shared libraries to specify additional information +about the version hierarchy for the library being created. This option +is only meaningful on \s-1ELF\s0 platforms which support shared libraries. +.IP "\fB\-\-warn\-common\fR" 4 +.IX Item "--warn-common" +Warn when a common symbol is combined with another common symbol or with +a symbol definition. Unix linkers allow this somewhat sloppy practise, +but linkers on some other operating systems do not. This option allows +you to find potential problems from combining global symbols. +Unfortunately, some C libraries use this practise, so you may get some +warnings about symbols in the libraries as well as in your programs. +.Sp +There are three kinds of global symbols, illustrated here by C examples: +.RS 4 +.IP "\fBint i = 1;\fR" 4 +.IX Item "int i = 1;" +A definition, which goes in the initialized data section of the output +file. +.IP "\fBextern int i;\fR" 4 +.IX Item "extern int i;" +An undefined reference, which does not allocate space. +There must be either a definition or a common symbol for the +variable somewhere. +.IP "\fBint i;\fR" 4 +.IX Item "int i;" +A common symbol. If there are only (one or more) common symbols for a +variable, it goes in the uninitialized data area of the output file. +The linker merges multiple common symbols for the same variable into a +single symbol. If they are of different sizes, it picks the largest +size. The linker turns a common symbol into a declaration, if there is +a definition of the same variable. +.RE +.RS 4 +.Sp +The \fB\-\-warn\-common\fR option can produce five kinds of warnings. +Each warning consists of a pair of lines: the first describes the symbol +just encountered, and the second describes the previous symbol +encountered with the same name. One or both of the two symbols will be +a common symbol. +.IP "1." 4 +Turning a common symbol into a reference, because there is already a +definition for the symbol. +.Sp +.Vb 3 +\& <file>(<section>): warning: common of \`<symbol>\*(Aq +\& overridden by definition +\& <file>(<section>): warning: defined here +.Ve +.IP "2." 4 +Turning a common symbol into a reference, because a later definition for +the symbol is encountered. This is the same as the previous case, +except that the symbols are encountered in a different order. +.Sp +.Vb 3 +\& <file>(<section>): warning: definition of \`<symbol>\*(Aq +\& overriding common +\& <file>(<section>): warning: common is here +.Ve +.IP "3." 4 +Merging a common symbol with a previous same-sized common symbol. +.Sp +.Vb 3 +\& <file>(<section>): warning: multiple common +\& of \`<symbol>\*(Aq +\& <file>(<section>): warning: previous common is here +.Ve +.IP "4." 4 +Merging a common symbol with a previous larger common symbol. +.Sp +.Vb 3 +\& <file>(<section>): warning: common of \`<symbol>\*(Aq +\& overridden by larger common +\& <file>(<section>): warning: larger common is here +.Ve +.IP "5." 4 +Merging a common symbol with a previous smaller common symbol. This is +the same as the previous case, except that the symbols are +encountered in a different order. +.Sp +.Vb 3 +\& <file>(<section>): warning: common of \`<symbol>\*(Aq +\& overriding smaller common +\& <file>(<section>): warning: smaller common is here +.Ve +.RE +.RS 4 +.RE +.IP "\fB\-\-warn\-constructors\fR" 4 +.IX Item "--warn-constructors" +Warn if any global constructors are used. This is only useful for a few +object file formats. For formats like \s-1COFF\s0 or \s-1ELF\s0, the linker can not +detect the use of global constructors. +.IP "\fB\-\-warn\-multiple\-gp\fR" 4 +.IX Item "--warn-multiple-gp" +Warn if multiple global pointer values are required in the output file. +This is only meaningful for certain processors, such as the Alpha. +Specifically, some processors put large-valued constants in a special +section. A special register (the global pointer) points into the middle +of this section, so that constants can be loaded efficiently via a +base-register relative addressing mode. Since the offset in +base-register relative mode is fixed and relatively small (e.g., 16 +bits), this limits the maximum size of the constant pool. Thus, in +large programs, it is often necessary to use multiple global pointer +values in order to be able to address all possible constants. This +option causes a warning to be issued whenever this case occurs. +.IP "\fB\-\-warn\-once\fR" 4 +.IX Item "--warn-once" +Only warn once for each undefined symbol, rather than once per module +which refers to it. +.IP "\fB\-\-warn\-section\-align\fR" 4 +.IX Item "--warn-section-align" +Warn if the address of an output section is changed because of +alignment. Typically, the alignment will be set by an input section. +The address will only be changed if it not explicitly specified; that +is, if the \f(CW\*(C`SECTIONS\*(C'\fR command does not specify a start address for +the section. +.IP "\fB\-\-warn\-shared\-textrel\fR" 4 +.IX Item "--warn-shared-textrel" +Warn if the linker adds a \s-1DT_TEXTREL\s0 to a shared object. +.IP "\fB\-\-warn\-unresolved\-symbols\fR" 4 +.IX Item "--warn-unresolved-symbols" +If the linker is going to report an unresolved symbol (see the option +\&\fB\-\-unresolved\-symbols\fR) it will normally generate an error. +This option makes it generate a warning instead. +.IP "\fB\-\-error\-unresolved\-symbols\fR" 4 +.IX Item "--error-unresolved-symbols" +This restores the linker's default behaviour of generating errors when +it is reporting unresolved symbols. +.IP "\fB\-\-whole\-archive\fR" 4 +.IX Item "--whole-archive" +For each archive mentioned on the command line after the +\&\fB\-\-whole\-archive\fR option, include every object file in the archive +in the link, rather than searching the archive for the required object +files. This is normally used to turn an archive file into a shared +library, forcing every object to be included in the resulting shared +library. This option may be used more than once. +.Sp +Two notes when using this option from gcc: First, gcc doesn't know +about this option, so you have to use \fB\-Wl,\-whole\-archive\fR. +Second, don't forget to use \fB\-Wl,\-no\-whole\-archive\fR after your +list of archives, because gcc will add its own list of archives to +your link and you may not want this flag to affect those as well. +.IP "\fB\-\-wrap\fR \fIsymbol\fR" 4 +.IX Item "--wrap symbol" +Use a wrapper function for \fIsymbol\fR. Any undefined reference to +\&\fIsymbol\fR will be resolved to \f(CW\*(C`_\|_wrap_\f(CIsymbol\f(CW\*(C'\fR. Any +undefined reference to \f(CW\*(C`_\|_real_\f(CIsymbol\f(CW\*(C'\fR will be resolved to +\&\fIsymbol\fR. +.Sp +This can be used to provide a wrapper for a system function. The +wrapper function should be called \f(CW\*(C`_\|_wrap_\f(CIsymbol\f(CW\*(C'\fR. If it +wishes to call the system function, it should call +\&\f(CW\*(C`_\|_real_\f(CIsymbol\f(CW\*(C'\fR. +.Sp +Here is a trivial example: +.Sp +.Vb 6 +\& void * +\& _\|_wrap_malloc (size_t c) +\& { +\& printf ("malloc called with %zu\en", c); +\& return _\|_real_malloc (c); +\& } +.Ve +.Sp +If you link other code with this file using \fB\-\-wrap malloc\fR, then +all calls to \f(CW\*(C`malloc\*(C'\fR will call the function \f(CW\*(C`_\|_wrap_malloc\*(C'\fR +instead. The call to \f(CW\*(C`_\|_real_malloc\*(C'\fR in \f(CW\*(C`_\|_wrap_malloc\*(C'\fR will +call the real \f(CW\*(C`malloc\*(C'\fR function. +.Sp +You may wish to provide a \f(CW\*(C`_\|_real_malloc\*(C'\fR function as well, so that +links without the \fB\-\-wrap\fR option will succeed. If you do this, +you should not put the definition of \f(CW\*(C`_\|_real_malloc\*(C'\fR in the same +file as \f(CW\*(C`_\|_wrap_malloc\*(C'\fR; if you do, the assembler may resolve the +call before the linker has a chance to wrap it to \f(CW\*(C`malloc\*(C'\fR. +.IP "\fB\-\-eh\-frame\-hdr\fR" 4 +.IX Item "--eh-frame-hdr" +Request creation of \f(CW\*(C`.eh_frame_hdr\*(C'\fR section and \s-1ELF\s0 +\&\f(CW\*(C`PT_GNU_EH_FRAME\*(C'\fR segment header. +.IP "\fB\-\-enable\-new\-dtags\fR" 4 +.IX Item "--enable-new-dtags" +.PD 0 +.IP "\fB\-\-disable\-new\-dtags\fR" 4 +.IX Item "--disable-new-dtags" +.PD +This linker can create the new dynamic tags in \s-1ELF\s0. But the older \s-1ELF\s0 +systems may not understand them. If you specify +\&\fB\-\-enable\-new\-dtags\fR, the dynamic tags will be created as needed. +If you specify \fB\-\-disable\-new\-dtags\fR, no new dynamic tags will be +created. By default, the new dynamic tags are not created. Note that +those options are only available for \s-1ELF\s0 systems. +.IP "\fB\-\-hash\-size=\fR\fInumber\fR" 4 +.IX Item "--hash-size=number" +Set the default size of the linker's hash tables to a prime number +close to \fInumber\fR. Increasing this value can reduce the length of +time it takes the linker to perform its tasks, at the expense of +increasing the linker's memory requirements. Similarly reducing this +value can reduce the memory requirements at the expense of speed. +.IP "\fB\-\-hash\-style=\fR\fIstyle\fR" 4 +.IX Item "--hash-style=style" +Set the type of linker's hash table(s). \fIstyle\fR can be either +\&\f(CW\*(C`sysv\*(C'\fR for classic \s-1ELF\s0 \f(CW\*(C`.hash\*(C'\fR section, \f(CW\*(C`gnu\*(C'\fR for +new style \s-1GNU\s0 \f(CW\*(C`.gnu.hash\*(C'\fR section or \f(CW\*(C`both\*(C'\fR for both +the classic \s-1ELF\s0 \f(CW\*(C`.hash\*(C'\fR and new style \s-1GNU\s0 \f(CW\*(C`.gnu.hash\*(C'\fR +hash tables. The default is \f(CW\*(C`sysv\*(C'\fR. +.IP "\fB\-\-reduce\-memory\-overheads\fR" 4 +.IX Item "--reduce-memory-overheads" +This option reduces memory requirements at ld runtime, at the expense of +linking speed. This was introduced to select the old O(n^2) algorithm +for link map file generation, rather than the new O(n) algorithm which uses +about 40% more memory for symbol storage. +.Sp +Another effect of the switch is to set the default hash table size to +1021, which again saves memory at the cost of lengthening the linker's +run time. This is not done however if the \fB\-\-hash\-size\fR switch +has been used. +.Sp +The \fB\-\-reduce\-memory\-overheads\fR switch may be also be used to +enable other tradeoffs in future versions of the linker. +.PP +The i386 \s-1PE\s0 linker supports the \fB\-shared\fR option, which causes +the output to be a dynamically linked library (\s-1DLL\s0) instead of a +normal executable. You should name the output \f(CW\*(C`*.dll\*(C'\fR when you +use this option. In addition, the linker fully supports the standard +\&\f(CW\*(C`*.def\*(C'\fR files, which may be specified on the linker command line +like an object file (in fact, it should precede archives it exports +symbols from, to ensure that they get linked in, just like a normal +object file). +.PP +In addition to the options common to all targets, the i386 \s-1PE\s0 linker +support additional command line options that are specific to the i386 +\&\s-1PE\s0 target. Options that take values may be separated from their +values by either a space or an equals sign. +.IP "\fB\-\-add\-stdcall\-alias\fR" 4 +.IX Item "--add-stdcall-alias" +If given, symbols with a stdcall suffix (@\fInn\fR) will be exported +as-is and also with the suffix stripped. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-base\-file\fR \fIfile\fR" 4 +.IX Item "--base-file file" +Use \fIfile\fR as the name of a file in which to save the base +addresses of all the relocations needed for generating DLLs with +\&\fIdlltool\fR. +[This is an i386 \s-1PE\s0 specific option] +.IP "\fB\-\-dll\fR" 4 +.IX Item "--dll" +Create a \s-1DLL\s0 instead of a regular executable. You may also use +\&\fB\-shared\fR or specify a \f(CW\*(C`LIBRARY\*(C'\fR in a given \f(CW\*(C`.def\*(C'\fR +file. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-enable\-stdcall\-fixup\fR" 4 +.IX Item "--enable-stdcall-fixup" +.PD 0 +.IP "\fB\-\-disable\-stdcall\-fixup\fR" 4 +.IX Item "--disable-stdcall-fixup" +.PD +If the link finds a symbol that it cannot resolve, it will attempt to +do \*(L"fuzzy linking\*(R" by looking for another defined symbol that differs +only in the format of the symbol name (cdecl vs stdcall) and will +resolve that symbol by linking to the match. For example, the +undefined symbol \f(CW\*(C`_foo\*(C'\fR might be linked to the function +\&\f(CW\*(C`_foo@12\*(C'\fR, or the undefined symbol \f(CW\*(C`_bar@16\*(C'\fR might be linked +to the function \f(CW\*(C`_bar\*(C'\fR. When the linker does this, it prints a +warning, since it normally should have failed to link, but sometimes +import libraries generated from third-party dlls may need this feature +to be usable. If you specify \fB\-\-enable\-stdcall\-fixup\fR, this +feature is fully enabled and warnings are not printed. If you specify +\&\fB\-\-disable\-stdcall\-fixup\fR, this feature is disabled and such +mismatches are considered to be errors. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-export\-all\-symbols\fR" 4 +.IX Item "--export-all-symbols" +If given, all global symbols in the objects used to build a \s-1DLL\s0 will +be exported by the \s-1DLL\s0. Note that this is the default if there +otherwise wouldn't be any exported symbols. When symbols are +explicitly exported via \s-1DEF\s0 files or implicitly exported via function +attributes, the default is to not export anything else unless this +option is given. Note that the symbols \f(CW\*(C`DllMain@12\*(C'\fR, +\&\f(CW\*(C`DllEntryPoint@0\*(C'\fR, \f(CW\*(C`DllMainCRTStartup@12\*(C'\fR, and +\&\f(CW\*(C`impure_ptr\*(C'\fR will not be automatically +exported. Also, symbols imported from other DLLs will not be +re-exported, nor will symbols specifying the \s-1DLL\s0's internal layout +such as those beginning with \f(CW\*(C`_head_\*(C'\fR or ending with +\&\f(CW\*(C`_iname\*(C'\fR. In addition, no symbols from \f(CW\*(C`libgcc\*(C'\fR, +\&\f(CW\*(C`libstd++\*(C'\fR, \f(CW\*(C`libmingw32\*(C'\fR, or \f(CW\*(C`crtX.o\*(C'\fR will be exported. +Symbols whose names begin with \f(CW\*(C`_\|_rtti_\*(C'\fR or \f(CW\*(C`_\|_builtin_\*(C'\fR will +not be exported, to help with \*(C+ DLLs. Finally, there is an +extensive list of cygwin-private symbols that are not exported +(obviously, this applies on when building DLLs for cygwin targets). +These cygwin-excludes are: \f(CW\*(C`_cygwin_dll_entry@12\*(C'\fR, +\&\f(CW\*(C`_cygwin_crt0_common@8\*(C'\fR, \f(CW\*(C`_cygwin_noncygwin_dll_entry@12\*(C'\fR, +\&\f(CW\*(C`_fmode\*(C'\fR, \f(CW\*(C`_impure_ptr\*(C'\fR, \f(CW\*(C`cygwin_attach_dll\*(C'\fR, +\&\f(CW\*(C`cygwin_premain0\*(C'\fR, \f(CW\*(C`cygwin_premain1\*(C'\fR, \f(CW\*(C`cygwin_premain2\*(C'\fR, +\&\f(CW\*(C`cygwin_premain3\*(C'\fR, and \f(CW\*(C`environ\*(C'\fR. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-exclude\-symbols\fR \fIsymbol\fR\fB,\fR\fIsymbol\fR\fB,...\fR" 4 +.IX Item "--exclude-symbols symbol,symbol,..." +Specifies a list of symbols which should not be automatically +exported. The symbol names may be delimited by commas or colons. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-file\-alignment\fR" 4 +.IX Item "--file-alignment" +Specify the file alignment. Sections in the file will always begin at +file offsets which are multiples of this number. This defaults to +512. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-heap\fR \fIreserve\fR" 4 +.IX Item "--heap reserve" +.PD 0 +.IP "\fB\-\-heap\fR \fIreserve\fR\fB,\fR\fIcommit\fR" 4 +.IX Item "--heap reserve,commit" +.PD +Specify the amount of memory to reserve (and optionally commit) to be +used as heap for this program. The default is 1Mb reserved, 4K +committed. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-image\-base\fR \fIvalue\fR" 4 +.IX Item "--image-base value" +Use \fIvalue\fR as the base address of your program or dll. This is +the lowest memory location that will be used when your program or dll +is loaded. To reduce the need to relocate and improve performance of +your dlls, each should have a unique base address and not overlap any +other dlls. The default is 0x400000 for executables, and 0x10000000 +for dlls. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-kill\-at\fR" 4 +.IX Item "--kill-at" +If given, the stdcall suffixes (@\fInn\fR) will be stripped from +symbols before they are exported. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-large\-address\-aware\fR" 4 +.IX Item "--large-address-aware" +If given, the appropriate bit in the \*(L"Characteristics\*(R" field of the \s-1COFF\s0 +header is set to indicate that this executable supports virtual addresses +greater than 2 gigabytes. This should be used in conjunction with the /3GB +or /USERVA=\fIvalue\fR megabytes switch in the \*(L"[operating systems]\*(R" +section of the \s-1BOOT\s0.INI. Otherwise, this bit has no effect. +[This option is specific to \s-1PE\s0 targeted ports of the linker] +.IP "\fB\-\-major\-image\-version\fR \fIvalue\fR" 4 +.IX Item "--major-image-version value" +Sets the major number of the \*(L"image version\*(R". Defaults to 1. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-major\-os\-version\fR \fIvalue\fR" 4 +.IX Item "--major-os-version value" +Sets the major number of the \*(L"os version\*(R". Defaults to 4. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-major\-subsystem\-version\fR \fIvalue\fR" 4 +.IX Item "--major-subsystem-version value" +Sets the major number of the \*(L"subsystem version\*(R". Defaults to 4. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-minor\-image\-version\fR \fIvalue\fR" 4 +.IX Item "--minor-image-version value" +Sets the minor number of the \*(L"image version\*(R". Defaults to 0. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-minor\-os\-version\fR \fIvalue\fR" 4 +.IX Item "--minor-os-version value" +Sets the minor number of the \*(L"os version\*(R". Defaults to 0. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-minor\-subsystem\-version\fR \fIvalue\fR" 4 +.IX Item "--minor-subsystem-version value" +Sets the minor number of the \*(L"subsystem version\*(R". Defaults to 0. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-output\-def\fR \fIfile\fR" 4 +.IX Item "--output-def file" +The linker will create the file \fIfile\fR which will contain a \s-1DEF\s0 +file corresponding to the \s-1DLL\s0 the linker is generating. This \s-1DEF\s0 file +(which should be called \f(CW\*(C`*.def\*(C'\fR) may be used to create an import +library with \f(CW\*(C`dlltool\*(C'\fR or may be used as a reference to +automatically or implicitly exported symbols. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-out\-implib\fR \fIfile\fR" 4 +.IX Item "--out-implib file" +The linker will create the file \fIfile\fR which will contain an +import lib corresponding to the \s-1DLL\s0 the linker is generating. This +import lib (which should be called \f(CW\*(C`*.dll.a\*(C'\fR or \f(CW\*(C`*.a\*(C'\fR +may be used to link clients against the generated \s-1DLL\s0; this behaviour +makes it possible to skip a separate \f(CW\*(C`dlltool\*(C'\fR import library +creation step. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-enable\-auto\-image\-base\fR" 4 +.IX Item "--enable-auto-image-base" +Automatically choose the image base for DLLs, unless one is specified +using the \f(CW\*(C`\-\-image\-base\*(C'\fR argument. By using a hash generated +from the dllname to create unique image bases for each \s-1DLL\s0, in-memory +collisions and relocations which can delay program execution are +avoided. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-disable\-auto\-image\-base\fR" 4 +.IX Item "--disable-auto-image-base" +Do not automatically generate a unique image base. If there is no +user-specified image base (\f(CW\*(C`\-\-image\-base\*(C'\fR) then use the platform +default. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-dll\-search\-prefix\fR \fIstring\fR" 4 +.IX Item "--dll-search-prefix string" +When linking dynamically to a dll without an import library, +search for \f(CW\*(C`<string><basename>.dll\*(C'\fR in preference to +\&\f(CW\*(C`lib<basename>.dll\*(C'\fR. This behaviour allows easy distinction +between DLLs built for the various \*(L"subplatforms\*(R": native, cygwin, +uwin, pw, etc. For instance, cygwin DLLs typically use +\&\f(CW\*(C`\-\-dll\-search\-prefix=cyg\*(C'\fR. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-enable\-auto\-import\fR" 4 +.IX Item "--enable-auto-import" +Do sophisticated linking of \f(CW\*(C`_symbol\*(C'\fR to \f(CW\*(C`_\|_imp_\|_symbol\*(C'\fR for +\&\s-1DATA\s0 imports from DLLs, and create the necessary thunking symbols when +building the import libraries with those \s-1DATA\s0 exports. Note: Use of the +\&'auto\-import' extension will cause the text section of the image file +to be made writable. This does not conform to the PE-COFF format +specification published by Microsoft. +.Sp +Using 'auto\-import' generally will 'just work' \*(-- but sometimes you may +see this message: +.Sp +"variable '<var>' can't be auto-imported. Please read the +documentation for ld's \f(CW\*(C`\-\-enable\-auto\-import\*(C'\fR for details." +.Sp +This message occurs when some (sub)expression accesses an address +ultimately given by the sum of two constants (Win32 import tables only +allow one). Instances where this may occur include accesses to member +fields of struct variables imported from a \s-1DLL\s0, as well as using a +constant index into an array variable imported from a \s-1DLL\s0. Any +multiword variable (arrays, structs, long long, etc) may trigger +this error condition. However, regardless of the exact data type +of the offending exported variable, ld will always detect it, issue +the warning, and exit. +.Sp +There are several ways to address this difficulty, regardless of the +data type of the exported variable: +.Sp +One way is to use \-\-enable\-runtime\-pseudo\-reloc switch. This leaves the task +of adjusting references in your client code for runtime environment, so +this method works only when runtime environment supports this feature. +.Sp +A second solution is to force one of the 'constants' to be a variable \*(-- +that is, unknown and un-optimizable at compile time. For arrays, +there are two possibilities: a) make the indexee (the array's address) +a variable, or b) make the 'constant' index a variable. Thus: +.Sp +.Vb 3 +\& extern type extern_array[]; +\& extern_array[1] \-\-> +\& { volatile type *t=extern_array; t[1] } +.Ve +.Sp +or +.Sp +.Vb 3 +\& extern type extern_array[]; +\& extern_array[1] \-\-> +\& { volatile int t=1; extern_array[t] } +.Ve +.Sp +For structs (and most other multiword data types) the only option +is to make the struct itself (or the long long, or the ...) variable: +.Sp +.Vb 3 +\& extern struct s extern_struct; +\& extern_struct.field \-\-> +\& { volatile struct s *t=&extern_struct; t\->field } +.Ve +.Sp +or +.Sp +.Vb 3 +\& extern long long extern_ll; +\& extern_ll \-\-> +\& { volatile long long * local_ll=&extern_ll; *local_ll } +.Ve +.Sp +A third method of dealing with this difficulty is to abandon +\&'auto\-import' for the offending symbol and mark it with +\&\f(CW\*(C`_\|_declspec(dllimport)\*(C'\fR. However, in practise that +requires using compile-time #defines to indicate whether you are +building a \s-1DLL\s0, building client code that will link to the \s-1DLL\s0, or +merely building/linking to a static library. In making the choice +between the various methods of resolving the 'direct address with +constant offset' problem, you should consider typical real-world usage: +.Sp +Original: +.Sp +.Vb 7 +\& \-\-foo.h +\& extern int arr[]; +\& \-\-foo.c +\& #include "foo.h" +\& void main(int argc, char **argv){ +\& printf("%d\en",arr[1]); +\& } +.Ve +.Sp +Solution 1: +.Sp +.Vb 9 +\& \-\-foo.h +\& extern int arr[]; +\& \-\-foo.c +\& #include "foo.h" +\& void main(int argc, char **argv){ +\& /* This workaround is for win32 and cygwin; do not "optimize" */ +\& volatile int *parr = arr; +\& printf("%d\en",parr[1]); +\& } +.Ve +.Sp +Solution 2: +.Sp +.Vb 10 +\& \-\-foo.h +\& /* Note: auto\-export is assumed (no _\|_declspec(dllexport)) */ +\& #if (defined(_WIN32) || defined(_\|_CYGWIN_\|_)) && \e +\& !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC)) +\& #define FOO_IMPORT _\|_declspec(dllimport) +\& #else +\& #define FOO_IMPORT +\& #endif +\& extern FOO_IMPORT int arr[]; +\& \-\-foo.c +\& #include "foo.h" +\& void main(int argc, char **argv){ +\& printf("%d\en",arr[1]); +\& } +.Ve +.Sp +A fourth way to avoid this problem is to re-code your +library to use a functional interface rather than a data interface +for the offending variables (e.g. \fIset_foo()\fR and \fIget_foo()\fR accessor +functions). +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-disable\-auto\-import\fR" 4 +.IX Item "--disable-auto-import" +Do not attempt to do sophisticated linking of \f(CW\*(C`_symbol\*(C'\fR to +\&\f(CW\*(C`_\|_imp_\|_symbol\*(C'\fR for \s-1DATA\s0 imports from DLLs. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-enable\-runtime\-pseudo\-reloc\fR" 4 +.IX Item "--enable-runtime-pseudo-reloc" +If your code contains expressions described in \-\-enable\-auto\-import section, +that is, \s-1DATA\s0 imports from \s-1DLL\s0 with non-zero offset, this switch will create +a vector of 'runtime pseudo relocations' which can be used by runtime +environment to adjust references to such data in your client code. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-disable\-runtime\-pseudo\-reloc\fR" 4 +.IX Item "--disable-runtime-pseudo-reloc" +Do not create pseudo relocations for non-zero offset \s-1DATA\s0 imports from +DLLs. This is the default. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-enable\-extra\-pe\-debug\fR" 4 +.IX Item "--enable-extra-pe-debug" +Show additional debug info related to auto-import symbol thunking. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-section\-alignment\fR" 4 +.IX Item "--section-alignment" +Sets the section alignment. Sections in memory will always begin at +addresses which are a multiple of this number. Defaults to 0x1000. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-stack\fR \fIreserve\fR" 4 +.IX Item "--stack reserve" +.PD 0 +.IP "\fB\-\-stack\fR \fIreserve\fR\fB,\fR\fIcommit\fR" 4 +.IX Item "--stack reserve,commit" +.PD +Specify the amount of memory to reserve (and optionally commit) to be +used as stack for this program. The default is 2Mb reserved, 4K +committed. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.IP "\fB\-\-subsystem\fR \fIwhich\fR" 4 +.IX Item "--subsystem which" +.PD 0 +.IP "\fB\-\-subsystem\fR \fIwhich\fR\fB:\fR\fImajor\fR" 4 +.IX Item "--subsystem which:major" +.IP "\fB\-\-subsystem\fR \fIwhich\fR\fB:\fR\fImajor\fR\fB.\fR\fIminor\fR" 4 +.IX Item "--subsystem which:major.minor" +.PD +Specifies the subsystem under which your program will execute. The +legal values for \fIwhich\fR are \f(CW\*(C`native\*(C'\fR, \f(CW\*(C`windows\*(C'\fR, +\&\f(CW\*(C`console\*(C'\fR, \f(CW\*(C`posix\*(C'\fR, and \f(CW\*(C`xbox\*(C'\fR. You may optionally set +the subsystem version also. Numeric values are also accepted for +\&\fIwhich\fR. +[This option is specific to the i386 \s-1PE\s0 targeted port of the linker] +.PP +The 68HC11 and 68HC12 linkers support specific options to control the +memory bank switching mapping and trampoline code generation. +.IP "\fB\-\-no\-trampoline\fR" 4 +.IX Item "--no-trampoline" +This option disables the generation of trampoline. By default a trampoline +is generated for each far function which is called using a \f(CW\*(C`jsr\*(C'\fR +instruction (this happens when a pointer to a far function is taken). +.IP "\fB\-\-bank\-window\fR \fIname\fR" 4 +.IX Item "--bank-window name" +This option indicates to the linker the name of the memory region in +the \fB\s-1MEMORY\s0\fR specification that describes the memory bank window. +The definition of such region is then used by the linker to compute +paging and addresses within the memory window. +.SH "ENVIRONMENT" +.IX Header "ENVIRONMENT" +You can change the behaviour of \fBld\fR with the environment variables +\&\f(CW\*(C`GNUTARGET\*(C'\fR, +\&\f(CW\*(C`LDEMULATION\*(C'\fR and \f(CW\*(C`COLLECT_NO_DEMANGLE\*(C'\fR. +.PP +\&\f(CW\*(C`GNUTARGET\*(C'\fR determines the input-file object format if you don't +use \fB\-b\fR (or its synonym \fB\-\-format\fR). Its value should be one +of the \s-1BFD\s0 names for an input format. If there is no +\&\f(CW\*(C`GNUTARGET\*(C'\fR in the environment, \fBld\fR uses the natural format +of the target. If \f(CW\*(C`GNUTARGET\*(C'\fR is set to \f(CW\*(C`default\*(C'\fR then \s-1BFD\s0 +attempts to discover the input format by examining binary input files; +this method often succeeds, but there are potential ambiguities, since +there is no method of ensuring that the magic number used to specify +object-file formats is unique. However, the configuration procedure for +\&\s-1BFD\s0 on each system places the conventional format for that system first +in the search-list, so ambiguities are resolved in favor of convention. +.PP +\&\f(CW\*(C`LDEMULATION\*(C'\fR determines the default emulation if you don't use the +\&\fB\-m\fR option. The emulation can affect various aspects of linker +behaviour, particularly the default linker script. You can list the +available emulations with the \fB\-\-verbose\fR or \fB\-V\fR options. If +the \fB\-m\fR option is not used, and the \f(CW\*(C`LDEMULATION\*(C'\fR environment +variable is not defined, the default emulation depends upon how the +linker was configured. +.PP +Normally, the linker will default to demangling symbols. However, if +\&\f(CW\*(C`COLLECT_NO_DEMANGLE\*(C'\fR is set in the environment, then it will +default to not demangling symbols. This environment variable is used in +a similar fashion by the \f(CW\*(C`gcc\*(C'\fR linker wrapper program. The default +may be overridden by the \fB\-\-demangle\fR and \fB\-\-no\-demangle\fR +options. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIar\fR\|(1), \fInm\fR\|(1), \fIobjcopy\fR\|(1), \fIobjdump\fR\|(1), \fIreadelf\fR\|(1) and +the Info entries for \fIbinutils\fR and +\&\fIld\fR. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001, +2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 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 \*(L"\s-1GNU\s0 Free Documentation License\*(R". diff --git a/gnu/usr.bin/binutils/nm/nm.1 b/gnu/usr.bin/binutils/nm/nm.1 new file mode 100644 index 0000000..e94e472 --- /dev/null +++ b/gnu/usr.bin/binutils/nm/nm.1 @@ -0,0 +1,450 @@ +.\" $FreeBSD$ +.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "NM 1" +.TH NM 1 "2010-10-30" "binutils-2.17.50" "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +nm \- list symbols from object files +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +nm [\fB\-a\fR|\fB\-\-debug\-syms\fR] [\fB\-g\fR|\fB\-\-extern\-only\fR] + [\fB\-B\fR] [\fB\-C\fR|\fB\-\-demangle\fR[=\fIstyle\fR]] [\fB\-D\fR|\fB\-\-dynamic\fR] + [\fB\-S\fR|\fB\-\-print\-size\fR] [\fB\-s\fR|\fB\-\-print\-armap\fR] + [\fB\-A\fR|\fB\-o\fR|\fB\-\-print\-file\-name\fR][\fB\-\-special\-syms\fR] + [\fB\-n\fR|\fB\-v\fR|\fB\-\-numeric\-sort\fR] [\fB\-p\fR|\fB\-\-no\-sort\fR] + [\fB\-r\fR|\fB\-\-reverse\-sort\fR] [\fB\-\-size\-sort\fR] [\fB\-u\fR|\fB\-\-undefined\-only\fR] + [\fB\-t\fR \fIradix\fR|\fB\-\-radix=\fR\fIradix\fR] [\fB\-P\fR|\fB\-\-portability\fR] + [\fB\-\-target=\fR\fIbfdname\fR] [\fB\-f\fR\fIformat\fR|\fB\-\-format=\fR\fIformat\fR] + [\fB\-\-defined\-only\fR] [\fB\-l\fR|\fB\-\-line\-numbers\fR] [\fB\-\-no\-demangle\fR] + [\fB\-V\fR|\fB\-\-version\fR] [\fB\-X 32_64\fR] [\fB\-\-help\fR] [\fIobjfile\fR...] +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\s-1GNU\s0 \fBnm\fR lists the symbols from object files \fIobjfile\fR.... +If no object files are listed as arguments, \fBnm\fR assumes the file +\&\fIa.out\fR. +.PP +For each symbol, \fBnm\fR shows: +.IP "\(bu" 4 +The symbol value, in the radix selected by options (see below), or +hexadecimal by default. +.IP "\(bu" 4 +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). +.RS 4 +.ie n .IP """A""" 4 +.el .IP "\f(CWA\fR" 4 +.IX Item "A" +The symbol's value is absolute, and will not be changed by further +linking. +.ie n .IP """B""" 4 +.el .IP "\f(CWB\fR" 4 +.IX Item "B" +The symbol is in the uninitialized data section (known as \s-1BSS\s0). +.ie n .IP """C""" 4 +.el .IP "\f(CWC\fR" 4 +.IX Item "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. +.ie n .IP """D""" 4 +.el .IP "\f(CWD\fR" 4 +.IX Item "D" +The symbol is in the initialized data section. +.ie n .IP """G""" 4 +.el .IP "\f(CWG\fR" 4 +.IX Item "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. +.ie n .IP """I""" 4 +.el .IP "\f(CWI\fR" 4 +.IX Item "I" +The symbol is an indirect reference to another symbol. This is a \s-1GNU\s0 +extension to the a.out object file format which is rarely used. +.ie n .IP """N""" 4 +.el .IP "\f(CWN\fR" 4 +.IX Item "N" +The symbol is a debugging symbol. +.ie n .IP """R""" 4 +.el .IP "\f(CWR\fR" 4 +.IX Item "R" +The symbol is in a read only data section. +.ie n .IP """S""" 4 +.el .IP "\f(CWS\fR" 4 +.IX Item "S" +The symbol is in an uninitialized data section for small objects. +.ie n .IP """T""" 4 +.el .IP "\f(CWT\fR" 4 +.IX Item "T" +The symbol is in the text (code) section. +.ie n .IP """U""" 4 +.el .IP "\f(CWU\fR" 4 +.IX Item "U" +The symbol is undefined. +.ie n .IP """V""" 4 +.el .IP "\f(CWV\fR" 4 +.IX Item "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. +.ie n .IP """W""" 4 +.el .IP "\f(CWW\fR" 4 +.IX Item "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 symbol is determined in a system-specific manner without +error. On some systems, uppercase indicates that a default value has been +specified. +.ie n .IP """\-""" 4 +.el .IP "\f(CW\-\fR" 4 +.IX Item "-" +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. +.ie n .IP """?""" 4 +.el .IP "\f(CW?\fR" 4 +.IX Item "?" +The symbol type is unknown, or object file format specific. +.RE +.RS 4 +.RE +.IP "\(bu" 4 +The symbol name. +.SH "OPTIONS" +.IX Header "OPTIONS" +The long and short forms of options, shown here as alternatives, are +equivalent. +.IP "\fB\-A\fR" 4 +.IX Item "-A" +.PD 0 +.IP "\fB\-o\fR" 4 +.IX Item "-o" +.IP "\fB\-\-print\-file\-name\fR" 4 +.IX Item "--print-file-name" +.PD +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. +.IP "\fB\-a\fR" 4 +.IX Item "-a" +.PD 0 +.IP "\fB\-\-debug\-syms\fR" 4 +.IX Item "--debug-syms" +.PD +Display all symbols, even debugger-only symbols; normally these are not +listed. +.IP "\fB\-B\fR" 4 +.IX Item "-B" +The same as \fB\-\-format=bsd\fR (for compatibility with the \s-1MIPS\s0 \fBnm\fR). +.IP "\fB\-C\fR" 4 +.IX Item "-C" +.PD 0 +.IP "\fB\-\-demangle[=\fR\fIstyle\fR\fB]\fR" 4 +.IX Item "--demangle[=style]" +.PD +Decode (\fIdemangle\fR) 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. +.IP "\fB\-\-no\-demangle\fR" 4 +.IX Item "--no-demangle" +Do not demangle low-level symbol names. This is the default. +.IP "\fB\-D\fR" 4 +.IX Item "-D" +.PD 0 +.IP "\fB\-\-dynamic\fR" 4 +.IX Item "--dynamic" +.PD +Display the dynamic symbols rather than the normal symbols. This is +only meaningful for dynamic objects, such as certain types of shared +libraries. +.IP "\fB\-f\fR \fIformat\fR" 4 +.IX Item "-f format" +.PD 0 +.IP "\fB\-\-format=\fR\fIformat\fR" 4 +.IX Item "--format=format" +.PD +Use the output format \fIformat\fR, which can be \f(CW\*(C`bsd\*(C'\fR, +\&\f(CW\*(C`sysv\*(C'\fR, or \f(CW\*(C`posix\*(C'\fR. The default is \f(CW\*(C`bsd\*(C'\fR. +Only the first character of \fIformat\fR is significant; it can be +either upper or lower case. +.IP "\fB\-g\fR" 4 +.IX Item "-g" +.PD 0 +.IP "\fB\-\-extern\-only\fR" 4 +.IX Item "--extern-only" +.PD +Display only external symbols. +.IP "\fB\-l\fR" 4 +.IX Item "-l" +.PD 0 +.IP "\fB\-\-line\-numbers\fR" 4 +.IX Item "--line-numbers" +.PD +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. +.IP "\fB\-n\fR" 4 +.IX Item "-n" +.PD 0 +.IP "\fB\-v\fR" 4 +.IX Item "-v" +.IP "\fB\-\-numeric\-sort\fR" 4 +.IX Item "--numeric-sort" +.PD +Sort symbols numerically by their addresses, rather than alphabetically +by their names. +.IP "\fB\-p\fR" 4 +.IX Item "-p" +.PD 0 +.IP "\fB\-\-no\-sort\fR" 4 +.IX Item "--no-sort" +.PD +Do not bother to sort the symbols in any order; print them in the order +encountered. +.IP "\fB\-P\fR" 4 +.IX Item "-P" +.PD 0 +.IP "\fB\-\-portability\fR" 4 +.IX Item "--portability" +.PD +Use the \s-1POSIX\s0.2 standard output format instead of the default format. +Equivalent to \fB\-f posix\fR. +.IP "\fB\-S\fR" 4 +.IX Item "-S" +.PD 0 +.IP "\fB\-\-print\-size\fR" 4 +.IX Item "--print-size" +.PD +Print size, not the value, of defined symbols for the \f(CW\*(C`bsd\*(C'\fR output format. +.IP "\fB\-s\fR" 4 +.IX Item "-s" +.PD 0 +.IP "\fB\-\-print\-armap\fR" 4 +.IX Item "--print-armap" +.PD +When listing symbols from archive members, include the index: a mapping +(stored in the archive by \fBar\fR or \fBranlib\fR) of which modules +contain definitions for which names. +.IP "\fB\-r\fR" 4 +.IX Item "-r" +.PD 0 +.IP "\fB\-\-reverse\-sort\fR" 4 +.IX Item "--reverse-sort" +.PD +Reverse the order of the sort (whether numeric or alphabetic); let the +last come first. +.IP "\fB\-\-size\-sort\fR" 4 +.IX Item "--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. If the \f(CW\*(C`bsd\*(C'\fR output format is used the size of the symbol +is printed, rather than the value, and \fB\-S\fR must be used in order +both size and value to be printed. +.IP "\fB\-\-special\-syms\fR" 4 +.IX Item "--special-syms" +Display symbols which have a target-specific special meaning. These +symbols are usually used by the target for some special processing and +are not normally helpful when included included in the normal symbol +lists. For example for \s-1ARM\s0 targets this option would skip the mapping +symbols used to mark transitions between \s-1ARM\s0 code, \s-1THUMB\s0 code and +data. +.IP "\fB\-t\fR \fIradix\fR" 4 +.IX Item "-t radix" +.PD 0 +.IP "\fB\-\-radix=\fR\fIradix\fR" 4 +.IX Item "--radix=radix" +.PD +Use \fIradix\fR as the radix for printing the symbol values. It must be +\&\fBd\fR for decimal, \fBo\fR for octal, or \fBx\fR for hexadecimal. +.IP "\fB\-\-target=\fR\fIbfdname\fR" 4 +.IX Item "--target=bfdname" +Specify an object code format other than your system's default format. +.IP "\fB\-u\fR" 4 +.IX Item "-u" +.PD 0 +.IP "\fB\-\-undefined\-only\fR" 4 +.IX Item "--undefined-only" +.PD +Display only undefined symbols (those external to each object file). +.IP "\fB\-\-defined\-only\fR" 4 +.IX Item "--defined-only" +Display only defined symbols for each object file. +.IP "\fB\-V\fR" 4 +.IX Item "-V" +.PD 0 +.IP "\fB\-\-version\fR" 4 +.IX Item "--version" +.PD +Show the version number of \fBnm\fR and exit. +.IP "\fB\-X\fR" 4 +.IX Item "-X" +This option is ignored for compatibility with the \s-1AIX\s0 version of +\&\fBnm\fR. It takes one parameter which must be the string +\&\fB32_64\fR. The default mode of \s-1AIX\s0 \fBnm\fR corresponds +to \fB\-X 32\fR, which is not supported by \s-1GNU\s0 \fBnm\fR. +.IP "\fB\-\-help\fR" 4 +.IX Item "--help" +Show a summary of the options to \fBnm\fR and exit. +.IP "\fB@\fR\fIfile\fR" 4 +.IX Item "@file" +Read command-line options from \fIfile\fR. The options read are +inserted in place of the original @\fIfile\fR option. If \fIfile\fR +does not exist, or cannot be read, then the option will be treated +literally, and not removed. +.Sp +Options in \fIfile\fR are separated by whitespace. A whitespace +character may be included in an option by surrounding the entire +option in either single or double quotes. Any character (including a +backslash) may be included by prefixing the character to be included +with a backslash. The \fIfile\fR may itself contain additional +@\fIfile\fR options; any such options will be processed recursively. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIar\fR\|(1), \fIobjdump\fR\|(1), \fIranlib\fR\|(1), and the Info entries for \fIbinutils\fR. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, +2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 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 \*(L"\s-1GNU\s0 Free Documentation License\*(R". diff --git a/gnu/usr.bin/binutils/objcopy/objcopy.1 b/gnu/usr.bin/binutils/objcopy/objcopy.1 new file mode 100644 index 0000000..bf45017 --- /dev/null +++ b/gnu/usr.bin/binutils/objcopy/objcopy.1 @@ -0,0 +1,858 @@ +.\" $FreeBSD$ +.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "OBJCOPY 1" +.TH OBJCOPY 1 "2010-10-30" "binutils-2.17.50" "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +objcopy \- copy and translate object files +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +objcopy [\fB\-F\fR \fIbfdname\fR|\fB\-\-target=\fR\fIbfdname\fR] + [\fB\-I\fR \fIbfdname\fR|\fB\-\-input\-target=\fR\fIbfdname\fR] + [\fB\-O\fR \fIbfdname\fR|\fB\-\-output\-target=\fR\fIbfdname\fR] + [\fB\-B\fR \fIbfdarch\fR|\fB\-\-binary\-architecture=\fR\fIbfdarch\fR] + [\fB\-S\fR|\fB\-\-strip\-all\fR] + [\fB\-g\fR|\fB\-\-strip\-debug\fR] + [\fB\-K\fR \fIsymbolname\fR|\fB\-\-keep\-symbol=\fR\fIsymbolname\fR] + [\fB\-N\fR \fIsymbolname\fR|\fB\-\-strip\-symbol=\fR\fIsymbolname\fR] + [\fB\-\-strip\-unneeded\-symbol=\fR\fIsymbolname\fR] + [\fB\-G\fR \fIsymbolname\fR|\fB\-\-keep\-global\-symbol=\fR\fIsymbolname\fR] + [\fB\-\-localize\-hidden\fR] + [\fB\-L\fR \fIsymbolname\fR|\fB\-\-localize\-symbol=\fR\fIsymbolname\fR] + [\fB\-\-globalize\-symbol=\fR\fIsymbolname\fR] + [\fB\-W\fR \fIsymbolname\fR|\fB\-\-weaken\-symbol=\fR\fIsymbolname\fR] + [\fB\-w\fR|\fB\-\-wildcard\fR] + [\fB\-x\fR|\fB\-\-discard\-all\fR] + [\fB\-X\fR|\fB\-\-discard\-locals\fR] + [\fB\-b\fR \fIbyte\fR|\fB\-\-byte=\fR\fIbyte\fR] + [\fB\-i\fR \fIinterleave\fR|\fB\-\-interleave=\fR\fIinterleave\fR] + [\fB\-j\fR \fIsectionname\fR|\fB\-\-only\-section=\fR\fIsectionname\fR] + [\fB\-R\fR \fIsectionname\fR|\fB\-\-remove\-section=\fR\fIsectionname\fR] + [\fB\-p\fR|\fB\-\-preserve\-dates\fR] + [\fB\-\-debugging\fR] + [\fB\-\-gap\-fill=\fR\fIval\fR] + [\fB\-\-pad\-to=\fR\fIaddress\fR] + [\fB\-\-set\-start=\fR\fIval\fR] + [\fB\-\-adjust\-start=\fR\fIincr\fR] + [\fB\-\-change\-addresses=\fR\fIincr\fR] + [\fB\-\-change\-section\-address\fR \fIsection\fR{=,+,\-}\fIval\fR] + [\fB\-\-change\-section\-lma\fR \fIsection\fR{=,+,\-}\fIval\fR] + [\fB\-\-change\-section\-vma\fR \fIsection\fR{=,+,\-}\fIval\fR] + [\fB\-\-change\-warnings\fR] [\fB\-\-no\-change\-warnings\fR] + [\fB\-\-set\-section\-flags\fR \fIsection\fR=\fIflags\fR] + [\fB\-\-add\-section\fR \fIsectionname\fR=\fIfilename\fR] + [\fB\-\-rename\-section\fR \fIoldname\fR=\fInewname\fR[,\fIflags\fR]] + [\fB\-\-change\-leading\-char\fR] [\fB\-\-remove\-leading\-char\fR] + [\fB\-\-reverse\-bytes=\fR\fInum\fR] + [\fB\-\-srec\-len=\fR\fIival\fR] [\fB\-\-srec\-forceS3\fR] + [\fB\-\-redefine\-sym\fR \fIold\fR=\fInew\fR] + [\fB\-\-redefine\-syms=\fR\fIfilename\fR] + [\fB\-\-weaken\fR] + [\fB\-\-keep\-symbols=\fR\fIfilename\fR] + [\fB\-\-strip\-symbols=\fR\fIfilename\fR] + [\fB\-\-strip\-unneeded\-symbols=\fR\fIfilename\fR] + [\fB\-\-keep\-global\-symbols=\fR\fIfilename\fR] + [\fB\-\-localize\-symbols=\fR\fIfilename\fR] + [\fB\-\-globalize\-symbols=\fR\fIfilename\fR] + [\fB\-\-weaken\-symbols=\fR\fIfilename\fR] + [\fB\-\-alt\-machine\-code=\fR\fIindex\fR] + [\fB\-\-prefix\-symbols=\fR\fIstring\fR] + [\fB\-\-prefix\-sections=\fR\fIstring\fR] + [\fB\-\-prefix\-alloc\-sections=\fR\fIstring\fR] + [\fB\-\-add\-gnu\-debuglink=\fR\fIpath-to-file\fR] + [\fB\-\-keep\-file\-symbols\fR] + [\fB\-\-only\-keep\-debug\fR] + [\fB\-\-extract\-symbol\fR] + [\fB\-\-writable\-text\fR] + [\fB\-\-readonly\-text\fR] + [\fB\-\-pure\fR] + [\fB\-\-impure\fR] + [\fB\-v\fR|\fB\-\-verbose\fR] + [\fB\-V\fR|\fB\-\-version\fR] + [\fB\-\-help\fR] [\fB\-\-info\fR] + \fIinfile\fR [\fIoutfile\fR] +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \s-1GNU\s0 \fBobjcopy\fR utility copies the contents of an object +file to another. \fBobjcopy\fR uses the \s-1GNU\s0 \s-1BFD\s0 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 \fBobjcopy\fR is controlled by command-line options. +Note that \fBobjcopy\fR 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. +.PP +\&\fBobjcopy\fR creates temporary files to do its translations and +deletes them afterward. \fBobjcopy\fR uses \s-1BFD\s0 to do all its +translation work; it has access to all the formats described in \s-1BFD\s0 +and thus is able to recognize most formats without being told +explicitly. +.PP +\&\fBobjcopy\fR can be used to generate S\-records by using an output +target of \fBsrec\fR (e.g., use \fB\-O srec\fR). +.PP +\&\fBobjcopy\fR can be used to generate a raw binary file by using an +output target of \fBbinary\fR (e.g., use \fB\-O binary\fR). When +\&\fBobjcopy\fR 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. +.PP +When generating an S\-record or a raw binary file, it may be helpful to +use \fB\-S\fR to remove sections containing debugging information. In +some cases \fB\-R\fR will be useful to remove sections which contain +information that is not needed by the binary file. +.PP +Note\-\-\-\fBobjcopy\fR is not able to change the endianness of its input +files. If the input format has an endianness (some formats do not), +\&\fBobjcopy\fR can only copy the inputs into file formats that have the +same endianness or which have no endianness (e.g., \fBsrec\fR). +(However, see the \fB\-\-reverse\-bytes\fR option.) +.SH "OPTIONS" +.IX Header "OPTIONS" +.IP "\fIinfile\fR" 4 +.IX Item "infile" +.PD 0 +.IP "\fIoutfile\fR" 4 +.IX Item "outfile" +.PD +The input and output files, respectively. +If you do not specify \fIoutfile\fR, \fBobjcopy\fR creates a +temporary file and destructively renames the result with +the name of \fIinfile\fR. +.IP "\fB\-I\fR \fIbfdname\fR" 4 +.IX Item "-I bfdname" +.PD 0 +.IP "\fB\-\-input\-target=\fR\fIbfdname\fR" 4 +.IX Item "--input-target=bfdname" +.PD +Consider the source file's object format to be \fIbfdname\fR, rather than +attempting to deduce it. +.IP "\fB\-O\fR \fIbfdname\fR" 4 +.IX Item "-O bfdname" +.PD 0 +.IP "\fB\-\-output\-target=\fR\fIbfdname\fR" 4 +.IX Item "--output-target=bfdname" +.PD +Write the output file using the object format \fIbfdname\fR. +.IP "\fB\-F\fR \fIbfdname\fR" 4 +.IX Item "-F bfdname" +.PD 0 +.IP "\fB\-\-target=\fR\fIbfdname\fR" 4 +.IX Item "--target=bfdname" +.PD +Use \fIbfdname\fR as the object format for both the input and the output +file; i.e., simply transfer data from source to destination with no +translation. +.IP "\fB\-B\fR \fIbfdarch\fR" 4 +.IX Item "-B bfdarch" +.PD 0 +.IP "\fB\-\-binary\-architecture=\fR\fIbfdarch\fR" 4 +.IX Item "--binary-architecture=bfdarch" +.PD +Useful when transforming a raw binary input file into an object file. +In this case the output architecture can be set to \fIbfdarch\fR. This +option will be ignored if the input file has a known \fIbfdarch\fR. You +can access this binary data inside a program by referencing the special +symbols that are created by the conversion process. These symbols are +called _binary_\fIobjfile\fR_start, _binary_\fIobjfile\fR_end and +_binary_\fIobjfile\fR_size. e.g. you can transform a picture file into +an object file and then access it in your code using these symbols. +.IP "\fB\-j\fR \fIsectionname\fR" 4 +.IX Item "-j sectionname" +.PD 0 +.IP "\fB\-\-only\-section=\fR\fIsectionname\fR" 4 +.IX Item "--only-section=sectionname" +.PD +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. +.IP "\fB\-R\fR \fIsectionname\fR" 4 +.IX Item "-R sectionname" +.PD 0 +.IP "\fB\-\-remove\-section=\fR\fIsectionname\fR" 4 +.IX Item "--remove-section=sectionname" +.PD +Remove any section named \fIsectionname\fR from the output file. This +option may be given more than once. Note that using this option +inappropriately may make the output file unusable. +.IP "\fB\-S\fR" 4 +.IX Item "-S" +.PD 0 +.IP "\fB\-\-strip\-all\fR" 4 +.IX Item "--strip-all" +.PD +Do not copy relocation and symbol information from the source file. +.IP "\fB\-g\fR" 4 +.IX Item "-g" +.PD 0 +.IP "\fB\-\-strip\-debug\fR" 4 +.IX Item "--strip-debug" +.PD +Do not copy debugging symbols or sections from the source file. +.IP "\fB\-\-strip\-unneeded\fR" 4 +.IX Item "--strip-unneeded" +Strip all symbols that are not needed for relocation processing. +.IP "\fB\-K\fR \fIsymbolname\fR" 4 +.IX Item "-K symbolname" +.PD 0 +.IP "\fB\-\-keep\-symbol=\fR\fIsymbolname\fR" 4 +.IX Item "--keep-symbol=symbolname" +.PD +When stripping symbols, keep symbol \fIsymbolname\fR even if it would +normally be stripped. This option may be given more than once. +.IP "\fB\-N\fR \fIsymbolname\fR" 4 +.IX Item "-N symbolname" +.PD 0 +.IP "\fB\-\-strip\-symbol=\fR\fIsymbolname\fR" 4 +.IX Item "--strip-symbol=symbolname" +.PD +Do not copy symbol \fIsymbolname\fR from the source file. This option +may be given more than once. +.IP "\fB\-\-strip\-unneeded\-symbol=\fR\fIsymbolname\fR" 4 +.IX Item "--strip-unneeded-symbol=symbolname" +Do not copy symbol \fIsymbolname\fR from the source file unless it is needed +by a relocation. This option may be given more than once. +.IP "\fB\-G\fR \fIsymbolname\fR" 4 +.IX Item "-G symbolname" +.PD 0 +.IP "\fB\-\-keep\-global\-symbol=\fR\fIsymbolname\fR" 4 +.IX Item "--keep-global-symbol=symbolname" +.PD +Keep only symbol \fIsymbolname\fR global. Make all other symbols local +to the file, so that they are not visible externally. This option may +be given more than once. +.IP "\fB\-\-localize\-hidden\fR" 4 +.IX Item "--localize-hidden" +In an \s-1ELF\s0 object, mark all symbols that have hidden or internal visibility +as local. This option applies on top of symbol-specific localization options +such as \fB\-L\fR. +.IP "\fB\-L\fR \fIsymbolname\fR" 4 +.IX Item "-L symbolname" +.PD 0 +.IP "\fB\-\-localize\-symbol=\fR\fIsymbolname\fR" 4 +.IX Item "--localize-symbol=symbolname" +.PD +Make symbol \fIsymbolname\fR local to the file, so that it is not +visible externally. This option may be given more than once. +.IP "\fB\-W\fR \fIsymbolname\fR" 4 +.IX Item "-W symbolname" +.PD 0 +.IP "\fB\-\-weaken\-symbol=\fR\fIsymbolname\fR" 4 +.IX Item "--weaken-symbol=symbolname" +.PD +Make symbol \fIsymbolname\fR weak. This option may be given more than once. +.IP "\fB\-\-globalize\-symbol=\fR\fIsymbolname\fR" 4 +.IX Item "--globalize-symbol=symbolname" +Give symbol \fIsymbolname\fR global scoping so that it is visible +outside of the file in which it is defined. This option may be given +more than once. +.IP "\fB\-w\fR" 4 +.IX Item "-w" +.PD 0 +.IP "\fB\-\-wildcard\fR" 4 +.IX Item "--wildcard" +.PD +Permit regular expressions in \fIsymbolname\fRs used in other command +line options. The question mark (?), asterisk (*), backslash (\e) and +square brackets ([]) operators can be used anywhere in the symbol +name. If the first character of the symbol name is the exclamation +point (!) then the sense of the switch is reversed for that symbol. +For example: +.Sp +.Vb 1 +\& \-w \-W !foo \-W fo* +.Ve +.Sp +would cause objcopy to weaken all symbols that start with \*(L"fo\*(R" +except for the symbol \*(L"foo\*(R". +.IP "\fB\-x\fR" 4 +.IX Item "-x" +.PD 0 +.IP "\fB\-\-discard\-all\fR" 4 +.IX Item "--discard-all" +.PD +Do not copy non-global symbols from the source file. +.IP "\fB\-X\fR" 4 +.IX Item "-X" +.PD 0 +.IP "\fB\-\-discard\-locals\fR" 4 +.IX Item "--discard-locals" +.PD +Do not copy compiler-generated local symbols. +(These usually start with \fBL\fR or \fB.\fR.) +.IP "\fB\-b\fR \fIbyte\fR" 4 +.IX Item "-b byte" +.PD 0 +.IP "\fB\-\-byte=\fR\fIbyte\fR" 4 +.IX Item "--byte=byte" +.PD +Keep only every \fIbyte\fRth byte of the input file (header data is not +affected). \fIbyte\fR can be in the range from 0 to \fIinterleave\fR\-1, +where \fIinterleave\fR is given by the \fB\-i\fR or \fB\-\-interleave\fR +option, or the default of 4. This option is useful for creating files +to program \s-1ROM\s0. It is typically used with an \f(CW\*(C`srec\*(C'\fR output +target. +.IP "\fB\-i\fR \fIinterleave\fR" 4 +.IX Item "-i interleave" +.PD 0 +.IP "\fB\-\-interleave=\fR\fIinterleave\fR" 4 +.IX Item "--interleave=interleave" +.PD +Only copy one out of every \fIinterleave\fR bytes. Select which byte to +copy with the \fB\-b\fR or \fB\-\-byte\fR option. The default is 4. +\&\fBobjcopy\fR ignores this option if you do not specify either \fB\-b\fR or +\&\fB\-\-byte\fR. +.IP "\fB\-p\fR" 4 +.IX Item "-p" +.PD 0 +.IP "\fB\-\-preserve\-dates\fR" 4 +.IX Item "--preserve-dates" +.PD +Set the access and modification dates of the output file to be the same +as those of the input file. +.IP "\fB\-\-debugging\fR" 4 +.IX Item "--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. +.IP "\fB\-\-gap\-fill\fR \fIval\fR" 4 +.IX Item "--gap-fill val" +Fill gaps between sections with \fIval\fR. This operation applies to +the \fIload address\fR (\s-1LMA\s0) 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 \fIval\fR. +.IP "\fB\-\-pad\-to\fR \fIaddress\fR" 4 +.IX Item "--pad-to address" +Pad the output file up to the load address \fIaddress\fR. This is +done by increasing the size of the last section. The extra space is +filled in with the value specified by \fB\-\-gap\-fill\fR (default zero). +.IP "\fB\-\-set\-start\fR \fIval\fR" 4 +.IX Item "--set-start val" +Set the start address of the new file to \fIval\fR. Not all object file +formats support setting the start address. +.IP "\fB\-\-change\-start\fR \fIincr\fR" 4 +.IX Item "--change-start incr" +.PD 0 +.IP "\fB\-\-adjust\-start\fR \fIincr\fR" 4 +.IX Item "--adjust-start incr" +.PD +Change the start address by adding \fIincr\fR. Not all object file +formats support setting the start address. +.IP "\fB\-\-change\-addresses\fR \fIincr\fR" 4 +.IX Item "--change-addresses incr" +.PD 0 +.IP "\fB\-\-adjust\-vma\fR \fIincr\fR" 4 +.IX Item "--adjust-vma incr" +.PD +Change the \s-1VMA\s0 and \s-1LMA\s0 addresses of all sections, as well as the start +address, by adding \fIincr\fR. 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. +.IP "\fB\-\-change\-section\-address\fR \fIsection\fR\fB{=,+,\-}\fR\fIval\fR" 4 +.IX Item "--change-section-address section{=,+,-}val" +.PD 0 +.IP "\fB\-\-adjust\-section\-vma\fR \fIsection\fR\fB{=,+,\-}\fR\fIval\fR" 4 +.IX Item "--adjust-section-vma section{=,+,-}val" +.PD +Set or change both the \s-1VMA\s0 address and the \s-1LMA\s0 address of the named +\&\fIsection\fR. If \fB=\fR is used, the section address is set to +\&\fIval\fR. Otherwise, \fIval\fR is added to or subtracted from the +section address. See the comments under \fB\-\-change\-addresses\fR, +above. If \fIsection\fR does not exist in the input file, a warning will +be issued, unless \fB\-\-no\-change\-warnings\fR is used. +.IP "\fB\-\-change\-section\-lma\fR \fIsection\fR\fB{=,+,\-}\fR\fIval\fR" 4 +.IX Item "--change-section-lma section{=,+,-}val" +Set or change the \s-1LMA\s0 address of the named \fIsection\fR. The \s-1LMA\s0 +address is the address where the section will be loaded into memory at +program load time. Normally this is the same as the \s-1VMA\s0 address, which +is the address of the section at program run time, but on some systems, +especially those where a program is held in \s-1ROM\s0, the two can be +different. If \fB=\fR is used, the section address is set to +\&\fIval\fR. Otherwise, \fIval\fR is added to or subtracted from the +section address. See the comments under \fB\-\-change\-addresses\fR, +above. If \fIsection\fR does not exist in the input file, a warning +will be issued, unless \fB\-\-no\-change\-warnings\fR is used. +.IP "\fB\-\-change\-section\-vma\fR \fIsection\fR\fB{=,+,\-}\fR\fIval\fR" 4 +.IX Item "--change-section-vma section{=,+,-}val" +Set or change the \s-1VMA\s0 address of the named \fIsection\fR. The \s-1VMA\s0 +address is the address where the section will be located once the +program has started executing. Normally this is the same as the \s-1LMA\s0 +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 +\&\s-1ROM\s0, the two can be different. If \fB=\fR is used, the section address +is set to \fIval\fR. Otherwise, \fIval\fR is added to or subtracted +from the section address. See the comments under +\&\fB\-\-change\-addresses\fR, above. If \fIsection\fR does not exist in +the input file, a warning will be issued, unless +\&\fB\-\-no\-change\-warnings\fR is used. +.IP "\fB\-\-change\-warnings\fR" 4 +.IX Item "--change-warnings" +.PD 0 +.IP "\fB\-\-adjust\-warnings\fR" 4 +.IX Item "--adjust-warnings" +.PD +If \fB\-\-change\-section\-address\fR or \fB\-\-change\-section\-lma\fR or +\&\fB\-\-change\-section\-vma\fR is used, and the named section does not +exist, issue a warning. This is the default. +.IP "\fB\-\-no\-change\-warnings\fR" 4 +.IX Item "--no-change-warnings" +.PD 0 +.IP "\fB\-\-no\-adjust\-warnings\fR" 4 +.IX Item "--no-adjust-warnings" +.PD +Do not issue a warning if \fB\-\-change\-section\-address\fR or +\&\fB\-\-adjust\-section\-lma\fR or \fB\-\-adjust\-section\-vma\fR is used, even +if the named section does not exist. +.IP "\fB\-\-set\-section\-flags\fR \fIsection\fR\fB=\fR\fIflags\fR" 4 +.IX Item "--set-section-flags section=flags" +Set the flags for the named section. The \fIflags\fR argument is a +comma separated string of flag names. The recognized names are +\&\fBalloc\fR, \fBcontents\fR, \fBload\fR, \fBnoload\fR, +\&\fBreadonly\fR, \fBcode\fR, \fBdata\fR, \fBrom\fR, \fBshare\fR, and +\&\fBdebug\fR. You can set the \fBcontents\fR flag for a section which +does not have contents, but it is not meaningful to clear the +\&\fBcontents\fR flag of a section which does have contents\*(--just remove +the section instead. Not all flags are meaningful for all object file +formats. +.IP "\fB\-\-add\-section\fR \fIsectionname\fR\fB=\fR\fIfilename\fR" 4 +.IX Item "--add-section sectionname=filename" +Add a new section named \fIsectionname\fR while copying the file. The +contents of the new section are taken from the file \fIfilename\fR. 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. +.IP "\fB\-\-rename\-section\fR \fIoldname\fR\fB=\fR\fInewname\fR\fB[,\fR\fIflags\fR\fB]\fR" 4 +.IX Item "--rename-section oldname=newname[,flags]" +Rename a section from \fIoldname\fR to \fInewname\fR, optionally +changing the section's flags to \fIflags\fR in the process. This has +the advantage over usng a linker script to perform the rename in that +the output stays as an object file and does not become a linked +executable. +.Sp +This option is particularly helpful when the input format is binary, +since this will always create a section called .data. If for example, +you wanted instead to create a section called .rodata containing binary +data you could use the following command line to achieve it: +.Sp +.Vb 3 +\& objcopy \-I binary \-O <output_format> \-B <architecture> \e +\& \-\-rename\-section .data=.rodata,alloc,load,readonly,data,contents \e +\& <input_binary_file> <output_object_file> +.Ve +.IP "\fB\-\-change\-leading\-char\fR" 4 +.IX Item "--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 \fBobjcopy\fR 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. +.IP "\fB\-\-remove\-leading\-char\fR" 4 +.IX Item "--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 +\&\fB\-\-change\-leading\-char\fR because it always changes the symbol name +when appropriate, regardless of the object file format of the output +file. +.IP "\fB\-\-reverse\-bytes=\fR\fInum\fR" 4 +.IX Item "--reverse-bytes=num" +Reverse the bytes in a section with output contents. A section length must +be evenly divisible by the value given in order for the swap to be able to +take place. Reversing takes place before the interleaving is performed. +.Sp +This option is used typically in generating \s-1ROM\s0 images for problematic +target systems. For example, on some target boards, the 32\-bit words +fetched from 8\-bit ROMs are re-assembled in little-endian byte order +regardless of the \s-1CPU\s0 byte order. Depending on the programming model, the +endianness of the \s-1ROM\s0 may need to be modified. +.Sp +Consider a simple file with a section containing the following eight +bytes: \f(CW12345678\fR. +.Sp +Using \fB\-\-reverse\-bytes=2\fR for the above example, the bytes in the +output file would be ordered \f(CW21436587\fR. +.Sp +Using \fB\-\-reverse\-bytes=4\fR for the above example, the bytes in the +output file would be ordered \f(CW43218765\fR. +.Sp +By using \fB\-\-reverse\-bytes=2\fR for the above example, followed by +\&\fB\-\-reverse\-bytes=4\fR on the output file, the bytes in the second +output file would be ordered \f(CW34127856\fR. +.IP "\fB\-\-srec\-len=\fR\fIival\fR" 4 +.IX Item "--srec-len=ival" +Meaningful only for srec output. Set the maximum length of the Srecords +being produced to \fIival\fR. This length covers both address, data and +crc fields. +.IP "\fB\-\-srec\-forceS3\fR" 4 +.IX Item "--srec-forceS3" +Meaningful only for srec output. Avoid generation of S1/S2 records, +creating S3\-only record format. +.IP "\fB\-\-redefine\-sym\fR \fIold\fR\fB=\fR\fInew\fR" 4 +.IX Item "--redefine-sym old=new" +Change the name of a symbol \fIold\fR, to \fInew\fR. This can be useful +when one is trying link two things together for which you have no +source, and there are name collisions. +.IP "\fB\-\-redefine\-syms=\fR\fIfilename\fR" 4 +.IX Item "--redefine-syms=filename" +Apply \fB\-\-redefine\-sym\fR to each symbol pair "\fIold\fR \fInew\fR" +listed in the file \fIfilename\fR. \fIfilename\fR is simply a flat file, +with one symbol pair per line. Line comments may be introduced by the hash +character. This option may be given more than once. +.IP "\fB\-\-weaken\fR" 4 +.IX Item "--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 \fB\-R\fR option to the linker. This option is only effective when +using an object file format which supports weak symbols. +.IP "\fB\-\-keep\-symbols=\fR\fIfilename\fR" 4 +.IX Item "--keep-symbols=filename" +Apply \fB\-\-keep\-symbol\fR option to each symbol listed in the file +\&\fIfilename\fR. \fIfilename\fR 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. +.IP "\fB\-\-strip\-symbols=\fR\fIfilename\fR" 4 +.IX Item "--strip-symbols=filename" +Apply \fB\-\-strip\-symbol\fR option to each symbol listed in the file +\&\fIfilename\fR. \fIfilename\fR 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. +.IP "\fB\-\-strip\-unneeded\-symbols=\fR\fIfilename\fR" 4 +.IX Item "--strip-unneeded-symbols=filename" +Apply \fB\-\-strip\-unneeded\-symbol\fR option to each symbol listed in +the file \fIfilename\fR. \fIfilename\fR 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. +.IP "\fB\-\-keep\-global\-symbols=\fR\fIfilename\fR" 4 +.IX Item "--keep-global-symbols=filename" +Apply \fB\-\-keep\-global\-symbol\fR option to each symbol listed in the +file \fIfilename\fR. \fIfilename\fR 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. +.IP "\fB\-\-localize\-symbols=\fR\fIfilename\fR" 4 +.IX Item "--localize-symbols=filename" +Apply \fB\-\-localize\-symbol\fR option to each symbol listed in the file +\&\fIfilename\fR. \fIfilename\fR 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. +.IP "\fB\-\-globalize\-symbols=\fR\fIfilename\fR" 4 +.IX Item "--globalize-symbols=filename" +Apply \fB\-\-globalize\-symbol\fR option to each symbol listed in the file +\&\fIfilename\fR. \fIfilename\fR 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. +.IP "\fB\-\-weaken\-symbols=\fR\fIfilename\fR" 4 +.IX Item "--weaken-symbols=filename" +Apply \fB\-\-weaken\-symbol\fR option to each symbol listed in the file +\&\fIfilename\fR. \fIfilename\fR 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. +.IP "\fB\-\-alt\-machine\-code=\fR\fIindex\fR" 4 +.IX Item "--alt-machine-code=index" +If the output architecture has alternate machine codes, use the +\&\fIindex\fRth code instead of the default one. This is useful in case +a machine is assigned an official code and the tool-chain adopts the +new code, but other applications still depend on the original code +being used. For \s-1ELF\s0 based architectures if the \fIindex\fR +alternative does not exist then the value is treated as an absolute +number to be stored in the e_machine field of the \s-1ELF\s0 header. +.IP "\fB\-\-writable\-text\fR" 4 +.IX Item "--writable-text" +Mark the output text as writable. This option isn't meaningful for all +object file formats. +.IP "\fB\-\-readonly\-text\fR" 4 +.IX Item "--readonly-text" +Make the output text write protected. This option isn't meaningful for all +object file formats. +.IP "\fB\-\-pure\fR" 4 +.IX Item "--pure" +Mark the output file as demand paged. This option isn't meaningful for all +object file formats. +.IP "\fB\-\-impure\fR" 4 +.IX Item "--impure" +Mark the output file as impure. This option isn't meaningful for all +object file formats. +.IP "\fB\-\-prefix\-symbols=\fR\fIstring\fR" 4 +.IX Item "--prefix-symbols=string" +Prefix all symbols in the output file with \fIstring\fR. +.IP "\fB\-\-prefix\-sections=\fR\fIstring\fR" 4 +.IX Item "--prefix-sections=string" +Prefix all section names in the output file with \fIstring\fR. +.IP "\fB\-\-prefix\-alloc\-sections=\fR\fIstring\fR" 4 +.IX Item "--prefix-alloc-sections=string" +Prefix all the names of all allocated sections in the output file with +\&\fIstring\fR. +.IP "\fB\-\-add\-gnu\-debuglink=\fR\fIpath-to-file\fR" 4 +.IX Item "--add-gnu-debuglink=path-to-file" +Creates a .gnu_debuglink section which contains a reference to \fIpath-to-file\fR +and adds it to the output file. +.IP "\fB\-\-keep\-file\-symbols\fR" 4 +.IX Item "--keep-file-symbols" +When stripping a file, perhaps with \fB\-\-strip\-debug\fR or +\&\fB\-\-strip\-unneeded\fR, retain any symbols specifying source file names, +which would otherwise get stripped. +.IP "\fB\-\-only\-keep\-debug\fR" 4 +.IX Item "--only-keep-debug" +Strip a file, removing contents of any sections that would not be +stripped by \fB\-\-strip\-debug\fR and leaving the debugging sections +intact. In \s-1ELF\s0 files, this preserves all note sections in the output. +.Sp +The intention is that this option will be used in conjunction with +\&\fB\-\-add\-gnu\-debuglink\fR to create a two part executable. One a +stripped binary which will occupy less space in \s-1RAM\s0 and in a +distribution and the second a debugging information file which is only +needed if debugging abilities are required. The suggested procedure +to create these files is as follows: +.RS 4 +.IP "1.<Link the executable as normal. Assuming that is is called>" 4 +.IX Item "1.<Link the executable as normal. Assuming that is is called>" +\&\f(CW\*(C`foo\*(C'\fR then... +.ie n .IP "1.<Run ""objcopy \-\-only\-keep\-debug foo foo.dbg"" to>" 4 +.el .IP "1.<Run \f(CWobjcopy \-\-only\-keep\-debug foo foo.dbg\fR to>" 4 +.IX Item "1.<Run objcopy --only-keep-debug foo foo.dbg to>" +create a file containing the debugging info. +.ie n .IP "1.<Run ""objcopy \-\-strip\-debug foo"" to create a>" 4 +.el .IP "1.<Run \f(CWobjcopy \-\-strip\-debug foo\fR to create a>" 4 +.IX Item "1.<Run objcopy --strip-debug foo to create a>" +stripped executable. +.ie n .IP "1.<Run ""objcopy \-\-add\-gnu\-debuglink=foo.dbg foo"">" 4 +.el .IP "1.<Run \f(CWobjcopy \-\-add\-gnu\-debuglink=foo.dbg foo\fR>" 4 +.IX Item "1.<Run objcopy --add-gnu-debuglink=foo.dbg foo>" +to add a link to the debugging info into the stripped executable. +.RE +.RS 4 +.Sp +Note \- the choice of \f(CW\*(C`.dbg\*(C'\fR as an extension for the debug info +file is arbitrary. Also the \f(CW\*(C`\-\-only\-keep\-debug\*(C'\fR step is +optional. You could instead do this: +.IP "1.<Link the executable as normal.>" 4 +.IX Item "1.<Link the executable as normal.>" +.PD 0 +.ie n .IP "1.<Copy ""foo"" to ""foo.full"">" 4 +.el .IP "1.<Copy \f(CWfoo\fR to \f(CWfoo.full\fR>" 4 +.IX Item "1.<Copy foo to foo.full>" +.ie n .IP "1.<Run ""objcopy \-\-strip\-debug foo"">" 4 +.el .IP "1.<Run \f(CWobjcopy \-\-strip\-debug foo\fR>" 4 +.IX Item "1.<Run objcopy --strip-debug foo>" +.ie n .IP "1.<Run ""objcopy \-\-add\-gnu\-debuglink=foo.full foo"">" 4 +.el .IP "1.<Run \f(CWobjcopy \-\-add\-gnu\-debuglink=foo.full foo\fR>" 4 +.IX Item "1.<Run objcopy --add-gnu-debuglink=foo.full foo>" +.RE +.RS 4 +.PD +.Sp +i.e., the file pointed to by the \fB\-\-add\-gnu\-debuglink\fR can be the +full executable. It does not have to be a file created by the +\&\fB\-\-only\-keep\-debug\fR switch. +.Sp +Note \- this switch is only intended for use on fully linked files. It +does not make sense to use it on object files where the debugging +information may be incomplete. Besides the gnu_debuglink feature +currently only supports the presence of one filename containing +debugging information, not multiple filenames on a one-per-object-file +basis. +.RE +.IP "\fB\-\-extract\-symbol\fR" 4 +.IX Item "--extract-symbol" +Keep the file's section flags and symbols but remove all section data. +Specifically, the option: +.RS 4 +.IP "*<sets the virtual and load addresses of every section to zero;>" 4 +.IX Item "*<sets the virtual and load addresses of every section to zero;>" +.PD 0 +.IP "*<removes the contents of all sections;>" 4 +.IX Item "*<removes the contents of all sections;>" +.IP "*<sets the size of every section to zero; and>" 4 +.IX Item "*<sets the size of every section to zero; and>" +.IP "*<sets the file's start address to zero.>" 4 +.IX Item "*<sets the file's start address to zero.>" +.RE +.RS 4 +.PD +.Sp +This option is used to build a \fI.sym\fR file for a VxWorks kernel. +It can also be a useful way of reducing the size of a \fB\-\-just\-symbols\fR +linker input file. +.RE +.IP "\fB\-V\fR" 4 +.IX Item "-V" +.PD 0 +.IP "\fB\-\-version\fR" 4 +.IX Item "--version" +.PD +Show the version number of \fBobjcopy\fR. +.IP "\fB\-v\fR" 4 +.IX Item "-v" +.PD 0 +.IP "\fB\-\-verbose\fR" 4 +.IX Item "--verbose" +.PD +Verbose output: list all object files modified. In the case of +archives, \fBobjcopy \-V\fR lists all members of the archive. +.IP "\fB\-\-help\fR" 4 +.IX Item "--help" +Show a summary of the options to \fBobjcopy\fR. +.IP "\fB\-\-info\fR" 4 +.IX Item "--info" +Display a list showing all architectures and object formats available. +.IP "\fB@\fR\fIfile\fR" 4 +.IX Item "@file" +Read command-line options from \fIfile\fR. The options read are +inserted in place of the original @\fIfile\fR option. If \fIfile\fR +does not exist, or cannot be read, then the option will be treated +literally, and not removed. +.Sp +Options in \fIfile\fR are separated by whitespace. A whitespace +character may be included in an option by surrounding the entire +option in either single or double quotes. Any character (including a +backslash) may be included by prefixing the character to be included +with a backslash. The \fIfile\fR may itself contain additional +@\fIfile\fR options; any such options will be processed recursively. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIld\fR\|(1), \fIobjdump\fR\|(1), and the Info entries for \fIbinutils\fR. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, +2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 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 \*(L"\s-1GNU\s0 Free Documentation License\*(R". diff --git a/gnu/usr.bin/binutils/objdump/objdump.1 b/gnu/usr.bin/binutils/objdump/objdump.1 new file mode 100644 index 0000000..3e33980 --- /dev/null +++ b/gnu/usr.bin/binutils/objdump/objdump.1 @@ -0,0 +1,636 @@ +.\" $FreeBSD$ +.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "OBJDUMP 1" +.TH OBJDUMP 1 "2010-10-30" "binutils-2.17.50" "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +objdump \- display information from object files. +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +objdump [\fB\-a\fR|\fB\-\-archive\-headers\fR] + [\fB\-b\fR \fIbfdname\fR|\fB\-\-target=\fR\fIbfdname\fR] + [\fB\-C\fR|\fB\-\-demangle\fR[=\fIstyle\fR] ] + [\fB\-d\fR|\fB\-\-disassemble\fR] + [\fB\-D\fR|\fB\-\-disassemble\-all\fR] + [\fB\-z\fR|\fB\-\-disassemble\-zeroes\fR] + [\fB\-EB\fR|\fB\-EL\fR|\fB\-\-endian=\fR{big | little }] + [\fB\-f\fR|\fB\-\-file\-headers\fR] + [\fB\-\-file\-start\-context\fR] + [\fB\-g\fR|\fB\-\-debugging\fR] + [\fB\-e\fR|\fB\-\-debugging\-tags\fR] + [\fB\-h\fR|\fB\-\-section\-headers\fR|\fB\-\-headers\fR] + [\fB\-i\fR|\fB\-\-info\fR] + [\fB\-j\fR \fIsection\fR|\fB\-\-section=\fR\fIsection\fR] + [\fB\-l\fR|\fB\-\-line\-numbers\fR] + [\fB\-S\fR|\fB\-\-source\fR] + [\fB\-m\fR \fImachine\fR|\fB\-\-architecture=\fR\fImachine\fR] + [\fB\-M\fR \fIoptions\fR|\fB\-\-disassembler\-options=\fR\fIoptions\fR] + [\fB\-p\fR|\fB\-\-private\-headers\fR] + [\fB\-r\fR|\fB\-\-reloc\fR] + [\fB\-R\fR|\fB\-\-dynamic\-reloc\fR] + [\fB\-s\fR|\fB\-\-full\-contents\fR] + [\fB\-W\fR|\fB\-\-dwarf\fR] + [\fB\-G\fR|\fB\-\-stabs\fR] + [\fB\-t\fR|\fB\-\-syms\fR] + [\fB\-T\fR|\fB\-\-dynamic\-syms\fR] + [\fB\-x\fR|\fB\-\-all\-headers\fR] + [\fB\-w\fR|\fB\-\-wide\fR] + [\fB\-\-start\-address=\fR\fIaddress\fR] + [\fB\-\-stop\-address=\fR\fIaddress\fR] + [\fB\-\-prefix\-addresses\fR] + [\fB\-\-[no\-]show\-raw\-insn\fR] + [\fB\-\-adjust\-vma=\fR\fIoffset\fR] + [\fB\-\-special\-syms\fR] + [\fB\-V\fR|\fB\-\-version\fR] + [\fB\-H\fR|\fB\-\-help\fR] + \fIobjfile\fR... +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBobjdump\fR displays information about one or more object files. +The options control what particular information to display. This +information is mostly useful to programmers who are working on the +compilation tools, as opposed to programmers who just want their +program to compile and work. +.PP +\&\fIobjfile\fR... are the object files to be examined. When you +specify archives, \fBobjdump\fR shows information on each of the member +object files. +.SH "OPTIONS" +.IX Header "OPTIONS" +The long and short forms of options, shown here as alternatives, are +equivalent. At least one option from the list +\&\fB\-a,\-d,\-D,\-e,\-f,\-g,\-G,\-h,\-H,\-p,\-r,\-R,\-s,\-S,\-t,\-T,\-V,\-x\fR must be given. +.IP "\fB\-a\fR" 4 +.IX Item "-a" +.PD 0 +.IP "\fB\-\-archive\-header\fR" 4 +.IX Item "--archive-header" +.PD +If any of the \fIobjfile\fR files are archives, display the archive +header information (in a format similar to \fBls \-l\fR). Besides the +information you could list with \fBar tv\fR, \fBobjdump \-a\fR shows +the object file format of each archive member. +.IP "\fB\-\-adjust\-vma=\fR\fIoffset\fR" 4 +.IX Item "--adjust-vma=offset" +When dumping information, first add \fIoffset\fR to all the section +addresses. This is useful if the section addresses do not correspond to +the symbol table, which can happen when putting sections at particular +addresses when using a format which can not represent section addresses, +such as a.out. +.IP "\fB\-b\fR \fIbfdname\fR" 4 +.IX Item "-b bfdname" +.PD 0 +.IP "\fB\-\-target=\fR\fIbfdname\fR" 4 +.IX Item "--target=bfdname" +.PD +Specify that the object-code format for the object files is +\&\fIbfdname\fR. This option may not be necessary; \fIobjdump\fR can +automatically recognize many formats. +.Sp +For example, +.Sp +.Vb 1 +\& objdump \-b oasys \-m vax \-h fu.o +.Ve +.Sp +displays summary information from the section headers (\fB\-h\fR) of +\&\fIfu.o\fR, which is explicitly identified (\fB\-m\fR) as a \s-1VAX\s0 object +file in the format produced by Oasys compilers. You can list the +formats available with the \fB\-i\fR option. +.IP "\fB\-C\fR" 4 +.IX Item "-C" +.PD 0 +.IP "\fB\-\-demangle[=\fR\fIstyle\fR\fB]\fR" 4 +.IX Item "--demangle[=style]" +.PD +Decode (\fIdemangle\fR) 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. +.IP "\fB\-g\fR" 4 +.IX Item "-g" +.PD 0 +.IP "\fB\-\-debugging\fR" 4 +.IX Item "--debugging" +.PD +Display debugging information. This attempts to parse debugging +information stored in the file and print it out using a C like syntax. +Only certain types of debugging information have been implemented. +Some other types are supported by \fBreadelf \-w\fR. +.IP "\fB\-e\fR" 4 +.IX Item "-e" +.PD 0 +.IP "\fB\-\-debugging\-tags\fR" 4 +.IX Item "--debugging-tags" +.PD +Like \fB\-g\fR, but the information is generated in a format compatible +with ctags tool. +.IP "\fB\-d\fR" 4 +.IX Item "-d" +.PD 0 +.IP "\fB\-\-disassemble\fR" 4 +.IX Item "--disassemble" +.PD +Display the assembler mnemonics for the machine instructions from +\&\fIobjfile\fR. This option only disassembles those sections which are +expected to contain instructions. +.IP "\fB\-D\fR" 4 +.IX Item "-D" +.PD 0 +.IP "\fB\-\-disassemble\-all\fR" 4 +.IX Item "--disassemble-all" +.PD +Like \fB\-d\fR, but disassemble the contents of all sections, not just +those expected to contain instructions. +.IP "\fB\-\-prefix\-addresses\fR" 4 +.IX Item "--prefix-addresses" +When disassembling, print the complete address on each line. This is +the older disassembly format. +.IP "\fB\-EB\fR" 4 +.IX Item "-EB" +.PD 0 +.IP "\fB\-EL\fR" 4 +.IX Item "-EL" +.IP "\fB\-\-endian={big|little}\fR" 4 +.IX Item "--endian={big|little}" +.PD +Specify the endianness of the object files. This only affects +disassembly. This can be useful when disassembling a file format which +does not describe endianness information, such as S\-records. +.IP "\fB\-f\fR" 4 +.IX Item "-f" +.PD 0 +.IP "\fB\-\-file\-headers\fR" 4 +.IX Item "--file-headers" +.PD +Display summary information from the overall header of +each of the \fIobjfile\fR files. +.IP "\fB\-\-file\-start\-context\fR" 4 +.IX Item "--file-start-context" +Specify that when displaying interlisted source code/disassembly +(assumes \fB\-S\fR) from a file that has not yet been displayed, extend the +context to the start of the file. +.IP "\fB\-h\fR" 4 +.IX Item "-h" +.PD 0 +.IP "\fB\-\-section\-headers\fR" 4 +.IX Item "--section-headers" +.IP "\fB\-\-headers\fR" 4 +.IX Item "--headers" +.PD +Display summary information from the section headers of the +object file. +.Sp +File segments may be relocated to nonstandard addresses, for example by +using the \fB\-Ttext\fR, \fB\-Tdata\fR, or \fB\-Tbss\fR options to +\&\fBld\fR. However, some object file formats, such as a.out, do not +store the starting address of the file segments. In those situations, +although \fBld\fR relocates the sections correctly, using \fBobjdump +\&\-h\fR to list the file section headers cannot show the correct addresses. +Instead, it shows the usual addresses, which are implicit for the +target. +.IP "\fB\-H\fR" 4 +.IX Item "-H" +.PD 0 +.IP "\fB\-\-help\fR" 4 +.IX Item "--help" +.PD +Print a summary of the options to \fBobjdump\fR and exit. +.IP "\fB\-i\fR" 4 +.IX Item "-i" +.PD 0 +.IP "\fB\-\-info\fR" 4 +.IX Item "--info" +.PD +Display a list showing all architectures and object formats available +for specification with \fB\-b\fR or \fB\-m\fR. +.IP "\fB\-j\fR \fIname\fR" 4 +.IX Item "-j name" +.PD 0 +.IP "\fB\-\-section=\fR\fIname\fR" 4 +.IX Item "--section=name" +.PD +Display information only for section \fIname\fR. +.IP "\fB\-l\fR" 4 +.IX Item "-l" +.PD 0 +.IP "\fB\-\-line\-numbers\fR" 4 +.IX Item "--line-numbers" +.PD +Label the display (using debugging information) with the filename and +source line numbers corresponding to the object code or relocs shown. +Only useful with \fB\-d\fR, \fB\-D\fR, or \fB\-r\fR. +.IP "\fB\-m\fR \fImachine\fR" 4 +.IX Item "-m machine" +.PD 0 +.IP "\fB\-\-architecture=\fR\fImachine\fR" 4 +.IX Item "--architecture=machine" +.PD +Specify the architecture to use when disassembling object files. This +can be useful when disassembling object files which do not describe +architecture information, such as S\-records. You can list the available +architectures with the \fB\-i\fR option. +.IP "\fB\-M\fR \fIoptions\fR" 4 +.IX Item "-M options" +.PD 0 +.IP "\fB\-\-disassembler\-options=\fR\fIoptions\fR" 4 +.IX Item "--disassembler-options=options" +.PD +Pass target specific information to the disassembler. Only supported on +some targets. If it is necessary to specify more than one +disassembler option then multiple \fB\-M\fR options can be used or +can be placed together into a comma separated list. +.Sp +If the target is an \s-1ARM\s0 architecture then this switch can be used to +select which register name set is used during disassembler. Specifying +\&\fB\-M reg-names-std\fR (the default) will select the register names as +used in \s-1ARM\s0's instruction set documentation, but with register 13 called +\&'sp', register 14 called 'lr' and register 15 called 'pc'. Specifying +\&\fB\-M reg-names-apcs\fR will select the name set used by the \s-1ARM\s0 +Procedure Call Standard, whilst specifying \fB\-M reg-names-raw\fR will +just use \fBr\fR followed by the register number. +.Sp +There are also two variants on the \s-1APCS\s0 register naming scheme enabled +by \fB\-M reg-names-atpcs\fR and \fB\-M reg-names-special-atpcs\fR which +use the ARM/Thumb Procedure Call Standard naming conventions. (Either +with the normal register names or the special register names). +.Sp +This option can also be used for \s-1ARM\s0 architectures to force the +disassembler to interpret all instructions as Thumb instructions by +using the switch \fB\-\-disassembler\-options=force\-thumb\fR. This can be +useful when attempting to disassemble thumb code produced by other +compilers. +.Sp +For the x86, some of the options duplicate functions of the \fB\-m\fR +switch, but allow finer grained control. Multiple selections from the +following may be specified as a comma separated string. +\&\fBx86\-64\fR, \fBi386\fR and \fBi8086\fR select disassembly for +the given architecture. \fBintel\fR and \fBatt\fR select between +intel syntax mode and \s-1AT&T\s0 syntax mode. \fBaddr64\fR, \fBaddr32\fR, +\&\fBaddr16\fR, \fBdata32\fR and \fBdata16\fR specify the default +address size and operand size. These four options will be overridden if +\&\fBx86\-64\fR, \fBi386\fR or \fBi8086\fR appear later in the +option string. Lastly, \fBsuffix\fR, when in \s-1AT&T\s0 mode, +instructs the disassembler to print a mnemonic suffix even when the +suffix could be inferred by the operands. +.Sp +For \s-1PPC\s0, \fBbooke\fR, \fBbooke32\fR and \fBbooke64\fR select +disassembly of BookE instructions. \fB32\fR and \fB64\fR select +PowerPC and PowerPC64 disassembly, respectively. \fBe300\fR selects +disassembly for the e300 family. \fB440\fR selects disassembly for +the PowerPC 440. +.Sp +For \s-1MIPS\s0, this option controls the printing of instruction mnemonic +names and register names in disassembled instructions. Multiple +selections from the following may be specified as a comma separated +string, and invalid options are ignored: +.RS 4 +.ie n .IP """no\-aliases""" 4 +.el .IP "\f(CWno\-aliases\fR" 4 +.IX Item "no-aliases" +Print the 'raw' instruction mnemonic instead of some pseudo +instruction mnemonic. I.e., print 'daddu' or 'or' instead of 'move', +\&'sll' instead of 'nop', etc. +.ie n .IP """gpr\-names=\f(CIABI\f(CW""" 4 +.el .IP "\f(CWgpr\-names=\f(CIABI\f(CW\fR" 4 +.IX Item "gpr-names=ABI" +Print \s-1GPR\s0 (general-purpose register) names as appropriate +for the specified \s-1ABI\s0. By default, \s-1GPR\s0 names are selected according to +the \s-1ABI\s0 of the binary being disassembled. +.ie n .IP """fpr\-names=\f(CIABI\f(CW""" 4 +.el .IP "\f(CWfpr\-names=\f(CIABI\f(CW\fR" 4 +.IX Item "fpr-names=ABI" +Print \s-1FPR\s0 (floating-point register) names as +appropriate for the specified \s-1ABI\s0. By default, \s-1FPR\s0 numbers are printed +rather than names. +.ie n .IP """cp0\-names=\f(CIARCH\f(CW""" 4 +.el .IP "\f(CWcp0\-names=\f(CIARCH\f(CW\fR" 4 +.IX Item "cp0-names=ARCH" +Print \s-1CP0\s0 (system control coprocessor; coprocessor 0) register names +as appropriate for the \s-1CPU\s0 or architecture specified by +\&\fI\s-1ARCH\s0\fR. By default, \s-1CP0\s0 register names are selected according to +the architecture and \s-1CPU\s0 of the binary being disassembled. +.ie n .IP """hwr\-names=\f(CIARCH\f(CW""" 4 +.el .IP "\f(CWhwr\-names=\f(CIARCH\f(CW\fR" 4 +.IX Item "hwr-names=ARCH" +Print \s-1HWR\s0 (hardware register, used by the \f(CW\*(C`rdhwr\*(C'\fR instruction) names +as appropriate for the \s-1CPU\s0 or architecture specified by +\&\fI\s-1ARCH\s0\fR. By default, \s-1HWR\s0 names are selected according to +the architecture and \s-1CPU\s0 of the binary being disassembled. +.ie n .IP """reg\-names=\f(CIABI\f(CW""" 4 +.el .IP "\f(CWreg\-names=\f(CIABI\f(CW\fR" 4 +.IX Item "reg-names=ABI" +Print \s-1GPR\s0 and \s-1FPR\s0 names as appropriate for the selected \s-1ABI\s0. +.ie n .IP """reg\-names=\f(CIARCH\f(CW""" 4 +.el .IP "\f(CWreg\-names=\f(CIARCH\f(CW\fR" 4 +.IX Item "reg-names=ARCH" +Print CPU-specific register names (\s-1CP0\s0 register and \s-1HWR\s0 names) +as appropriate for the selected \s-1CPU\s0 or architecture. +.RE +.RS 4 +.Sp +For any of the options listed above, \fI\s-1ABI\s0\fR or +\&\fI\s-1ARCH\s0\fR may be specified as \fBnumeric\fR to have numbers printed +rather than names, for the selected types of registers. +You can list the available values of \fI\s-1ABI\s0\fR and \fI\s-1ARCH\s0\fR using +the \fB\-\-help\fR option. +.Sp +For \s-1VAX\s0, you can specify function entry addresses with \fB\-M +entry:0xf00ba\fR. You can use this multiple times to properly +disassemble \s-1VAX\s0 binary files that don't contain symbol tables (like +\&\s-1ROM\s0 dumps). In these cases, the function entry mask would otherwise +be decoded as \s-1VAX\s0 instructions, which would probably lead the rest +of the function being wrongly disassembled. +.RE +.IP "\fB\-p\fR" 4 +.IX Item "-p" +.PD 0 +.IP "\fB\-\-private\-headers\fR" 4 +.IX Item "--private-headers" +.PD +Print information that is specific to the object file format. The exact +information printed depends upon the object file format. For some +object file formats, no additional information is printed. +.IP "\fB\-r\fR" 4 +.IX Item "-r" +.PD 0 +.IP "\fB\-\-reloc\fR" 4 +.IX Item "--reloc" +.PD +Print the relocation entries of the file. If used with \fB\-d\fR or +\&\fB\-D\fR, the relocations are printed interspersed with the +disassembly. +.IP "\fB\-R\fR" 4 +.IX Item "-R" +.PD 0 +.IP "\fB\-\-dynamic\-reloc\fR" 4 +.IX Item "--dynamic-reloc" +.PD +Print the dynamic relocation entries of the file. This is only +meaningful for dynamic objects, such as certain types of shared +libraries. +.IP "\fB\-s\fR" 4 +.IX Item "-s" +.PD 0 +.IP "\fB\-\-full\-contents\fR" 4 +.IX Item "--full-contents" +.PD +Display the full contents of any sections requested. By default all +non-empty sections are displayed. +.IP "\fB\-S\fR" 4 +.IX Item "-S" +.PD 0 +.IP "\fB\-\-source\fR" 4 +.IX Item "--source" +.PD +Display source code intermixed with disassembly, if possible. Implies +\&\fB\-d\fR. +.IP "\fB\-\-show\-raw\-insn\fR" 4 +.IX Item "--show-raw-insn" +When disassembling instructions, print the instruction in hex as well as +in symbolic form. This is the default except when +\&\fB\-\-prefix\-addresses\fR is used. +.IP "\fB\-\-no\-show\-raw\-insn\fR" 4 +.IX Item "--no-show-raw-insn" +When disassembling instructions, do not print the instruction bytes. +This is the default when \fB\-\-prefix\-addresses\fR is used. +.IP "\fB\-W\fR" 4 +.IX Item "-W" +.PD 0 +.IP "\fB\-\-dwarf\fR" 4 +.IX Item "--dwarf" +.PD +Displays the contents of the \s-1DWARF\s0 debug sections in the file, if any +are present. +.IP "\fB\-G\fR" 4 +.IX Item "-G" +.PD 0 +.IP "\fB\-\-stabs\fR" 4 +.IX Item "--stabs" +.PD +Display the full contents of any sections requested. Display the +contents of the .stab and .stab.index and .stab.excl sections from an +\&\s-1ELF\s0 file. This is only useful on systems (such as Solaris 2.0) in which +\&\f(CW\*(C`.stab\*(C'\fR debugging symbol-table entries are carried in an \s-1ELF\s0 +section. In most other file formats, debugging symbol-table entries are +interleaved with linkage symbols, and are visible in the \fB\-\-syms\fR +output. +.IP "\fB\-\-start\-address=\fR\fIaddress\fR" 4 +.IX Item "--start-address=address" +Start displaying data at the specified address. This affects the output +of the \fB\-d\fR, \fB\-r\fR and \fB\-s\fR options. +.IP "\fB\-\-stop\-address=\fR\fIaddress\fR" 4 +.IX Item "--stop-address=address" +Stop displaying data at the specified address. This affects the output +of the \fB\-d\fR, \fB\-r\fR and \fB\-s\fR options. +.IP "\fB\-t\fR" 4 +.IX Item "-t" +.PD 0 +.IP "\fB\-\-syms\fR" 4 +.IX Item "--syms" +.PD +Print the symbol table entries of the file. +This is similar to the information provided by the \fBnm\fR program. +.IP "\fB\-T\fR" 4 +.IX Item "-T" +.PD 0 +.IP "\fB\-\-dynamic\-syms\fR" 4 +.IX Item "--dynamic-syms" +.PD +Print the dynamic symbol table entries of the file. This is only +meaningful for dynamic objects, such as certain types of shared +libraries. This is similar to the information provided by the \fBnm\fR +program when given the \fB\-D\fR (\fB\-\-dynamic\fR) option. +.IP "\fB\-\-special\-syms\fR" 4 +.IX Item "--special-syms" +When displaying symbols include those which the target considers to be +special in some way and which would not normally be of interest to the +user. +.IP "\fB\-V\fR" 4 +.IX Item "-V" +.PD 0 +.IP "\fB\-\-version\fR" 4 +.IX Item "--version" +.PD +Print the version number of \fBobjdump\fR and exit. +.IP "\fB\-x\fR" 4 +.IX Item "-x" +.PD 0 +.IP "\fB\-\-all\-headers\fR" 4 +.IX Item "--all-headers" +.PD +Display all available header information, including the symbol table and +relocation entries. Using \fB\-x\fR is equivalent to specifying all of +\&\fB\-a \-f \-h \-p \-r \-t\fR. +.IP "\fB\-w\fR" 4 +.IX Item "-w" +.PD 0 +.IP "\fB\-\-wide\fR" 4 +.IX Item "--wide" +.PD +Format some lines for output devices that have more than 80 columns. +Also do not truncate symbol names when they are displayed. +.IP "\fB\-z\fR" 4 +.IX Item "-z" +.PD 0 +.IP "\fB\-\-disassemble\-zeroes\fR" 4 +.IX Item "--disassemble-zeroes" +.PD +Normally the disassembly output will skip blocks of zeroes. This +option directs the disassembler to disassemble those blocks, just like +any other data. +.IP "\fB@\fR\fIfile\fR" 4 +.IX Item "@file" +Read command-line options from \fIfile\fR. The options read are +inserted in place of the original @\fIfile\fR option. If \fIfile\fR +does not exist, or cannot be read, then the option will be treated +literally, and not removed. +.Sp +Options in \fIfile\fR are separated by whitespace. A whitespace +character may be included in an option by surrounding the entire +option in either single or double quotes. Any character (including a +backslash) may be included by prefixing the character to be included +with a backslash. The \fIfile\fR may itself contain additional +@\fIfile\fR options; any such options will be processed recursively. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fInm\fR\|(1), \fIreadelf\fR\|(1), and the Info entries for \fIbinutils\fR. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, +2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 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 \*(L"\s-1GNU\s0 Free Documentation License\*(R". diff --git a/gnu/usr.bin/binutils/ranlib/ranlib.1 b/gnu/usr.bin/binutils/ranlib/ranlib.1 new file mode 100644 index 0000000..88a10e6 --- /dev/null +++ b/gnu/usr.bin/binutils/ranlib/ranlib.1 @@ -0,0 +1,189 @@ +.\" $FreeBSD$ +.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "RANLIB 1" +.TH RANLIB 1 "2010-10-30" "binutils-2.17.50" "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +ranlib \- generate index to archive. +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +ranlib [\fB\-vV\fR] \fIarchive\fR +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBranlib\fR generates an index to the contents of an archive and +stores it in the archive. The index lists each symbol defined by a +member of an archive that is a relocatable object file. +.PP +You may use \fBnm \-s\fR or \fBnm \-\-print\-armap\fR to list this index. +.PP +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. +.PP +The \s-1GNU\s0 \fBranlib\fR program is another form of \s-1GNU\s0 \fBar\fR; running +\&\fBranlib\fR is completely equivalent to executing \fBar \-s\fR. +.SH "OPTIONS" +.IX Header "OPTIONS" +.IP "\fB\-v\fR" 4 +.IX Item "-v" +.PD 0 +.IP "\fB\-V\fR" 4 +.IX Item "-V" +.IP "\fB\-\-version\fR" 4 +.IX Item "--version" +.PD +Show the version number of \fBranlib\fR. +.IP "\fB@\fR\fIfile\fR" 4 +.IX Item "@file" +Read command-line options from \fIfile\fR. The options read are +inserted in place of the original @\fIfile\fR option. If \fIfile\fR +does not exist, or cannot be read, then the option will be treated +literally, and not removed. +.Sp +Options in \fIfile\fR are separated by whitespace. A whitespace +character may be included in an option by surrounding the entire +option in either single or double quotes. Any character (including a +backslash) may be included by prefixing the character to be included +with a backslash. The \fIfile\fR may itself contain additional +@\fIfile\fR options; any such options will be processed recursively. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIar\fR\|(1), \fInm\fR\|(1), and the Info entries for \fIbinutils\fR. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, +2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 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 \*(L"\s-1GNU\s0 Free Documentation License\*(R". diff --git a/gnu/usr.bin/binutils/readelf/readelf.1 b/gnu/usr.bin/binutils/readelf/readelf.1 new file mode 100644 index 0000000..e246d2c --- /dev/null +++ b/gnu/usr.bin/binutils/readelf/readelf.1 @@ -0,0 +1,377 @@ +.\" $FreeBSD$ +.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "READELF 1" +.TH READELF 1 "2010-10-30" "binutils-2.17.50" "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +readelf \- Displays information about ELF files. +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +readelf [\fB\-a\fR|\fB\-\-all\fR] + [\fB\-h\fR|\fB\-\-file\-header\fR] + [\fB\-l\fR|\fB\-\-program\-headers\fR|\fB\-\-segments\fR] + [\fB\-S\fR|\fB\-\-section\-headers\fR|\fB\-\-sections\fR] + [\fB\-g\fR|\fB\-\-section\-groups\fR] + [\fB\-t\fR|\fB\-\-section\-details\fR] + [\fB\-e\fR|\fB\-\-headers\fR] + [\fB\-s\fR|\fB\-\-syms\fR|\fB\-\-symbols\fR] + [\fB\-n\fR|\fB\-\-notes\fR] + [\fB\-r\fR|\fB\-\-relocs\fR] + [\fB\-u\fR|\fB\-\-unwind\fR] + [\fB\-d\fR|\fB\-\-dynamic\fR] + [\fB\-V\fR|\fB\-\-version\-info\fR] + [\fB\-A\fR|\fB\-\-arch\-specific\fR] + [\fB\-D\fR|\fB\-\-use\-dynamic\fR] + [\fB\-x\fR <number or name>|\fB\-\-hex\-dump=\fR<number or name>] + [\fB\-w[liaprmfFsoR]\fR| + \fB\-\-debug\-dump\fR[=line,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames\-interp,=str,=loc,=Ranges]] + [\fB\-I\fR|\fB\-histogram\fR] + [\fB\-v\fR|\fB\-\-version\fR] + [\fB\-W\fR|\fB\-\-wide\fR] + [\fB\-H\fR|\fB\-\-help\fR] + \fIelffile\fR... +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBreadelf\fR displays information about one or more \s-1ELF\s0 format object +files. The options control what particular information to display. +.PP +\&\fIelffile\fR... are the object files to be examined. 32\-bit and +64\-bit \s-1ELF\s0 files are supported, as are archives containing \s-1ELF\s0 files. +.PP +This program performs a similar function to \fBobjdump\fR but it +goes into more detail and it exists independently of the \s-1BFD\s0 +library, so if there is a bug in \s-1BFD\s0 then readelf will not be +affected. +.SH "OPTIONS" +.IX Header "OPTIONS" +The long and short forms of options, shown here as alternatives, are +equivalent. At least one option besides \fB\-v\fR or \fB\-H\fR must be +given. +.IP "\fB\-a\fR" 4 +.IX Item "-a" +.PD 0 +.IP "\fB\-\-all\fR" 4 +.IX Item "--all" +.PD +Equivalent to specifying \fB\-\-file\-header\fR, +\&\fB\-\-program\-headers\fR, \fB\-\-sections\fR, \fB\-\-symbols\fR, +\&\fB\-\-relocs\fR, \fB\-\-dynamic\fR, \fB\-\-notes\fR and +\&\fB\-\-version\-info\fR. +.IP "\fB\-h\fR" 4 +.IX Item "-h" +.PD 0 +.IP "\fB\-\-file\-header\fR" 4 +.IX Item "--file-header" +.PD +Displays the information contained in the \s-1ELF\s0 header at the start of the +file. +.IP "\fB\-l\fR" 4 +.IX Item "-l" +.PD 0 +.IP "\fB\-\-program\-headers\fR" 4 +.IX Item "--program-headers" +.IP "\fB\-\-segments\fR" 4 +.IX Item "--segments" +.PD +Displays the information contained in the file's segment headers, if it +has any. +.IP "\fB\-S\fR" 4 +.IX Item "-S" +.PD 0 +.IP "\fB\-\-sections\fR" 4 +.IX Item "--sections" +.IP "\fB\-\-section\-headers\fR" 4 +.IX Item "--section-headers" +.PD +Displays the information contained in the file's section headers, if it +has any. +.IP "\fB\-g\fR" 4 +.IX Item "-g" +.PD 0 +.IP "\fB\-\-section\-groups\fR" 4 +.IX Item "--section-groups" +.PD +Displays the information contained in the file's section groups, if it +has any. +.IP "\fB\-t\fR" 4 +.IX Item "-t" +.PD 0 +.IP "\fB\-\-section\-details\fR" 4 +.IX Item "--section-details" +.PD +Displays the detailed section information. Implies \fB\-S\fR. +.IP "\fB\-s\fR" 4 +.IX Item "-s" +.PD 0 +.IP "\fB\-\-symbols\fR" 4 +.IX Item "--symbols" +.IP "\fB\-\-syms\fR" 4 +.IX Item "--syms" +.PD +Displays the entries in symbol table section of the file, if it has one. +.IP "\fB\-e\fR" 4 +.IX Item "-e" +.PD 0 +.IP "\fB\-\-headers\fR" 4 +.IX Item "--headers" +.PD +Display all the headers in the file. Equivalent to \fB\-h \-l \-S\fR. +.IP "\fB\-n\fR" 4 +.IX Item "-n" +.PD 0 +.IP "\fB\-\-notes\fR" 4 +.IX Item "--notes" +.PD +Displays the contents of the \s-1NOTE\s0 segments and/or sections, if any. +.IP "\fB\-r\fR" 4 +.IX Item "-r" +.PD 0 +.IP "\fB\-\-relocs\fR" 4 +.IX Item "--relocs" +.PD +Displays the contents of the file's relocation section, if it has one. +.IP "\fB\-u\fR" 4 +.IX Item "-u" +.PD 0 +.IP "\fB\-\-unwind\fR" 4 +.IX Item "--unwind" +.PD +Displays the contents of the file's unwind section, if it has one. Only +the unwind sections for \s-1IA64\s0 \s-1ELF\s0 files are currently supported. +.IP "\fB\-d\fR" 4 +.IX Item "-d" +.PD 0 +.IP "\fB\-\-dynamic\fR" 4 +.IX Item "--dynamic" +.PD +Displays the contents of the file's dynamic section, if it has one. +.IP "\fB\-V\fR" 4 +.IX Item "-V" +.PD 0 +.IP "\fB\-\-version\-info\fR" 4 +.IX Item "--version-info" +.PD +Displays the contents of the version sections in the file, it they +exist. +.IP "\fB\-A\fR" 4 +.IX Item "-A" +.PD 0 +.IP "\fB\-\-arch\-specific\fR" 4 +.IX Item "--arch-specific" +.PD +Displays architecture-specific information in the file, if there +is any. +.IP "\fB\-D\fR" 4 +.IX Item "-D" +.PD 0 +.IP "\fB\-\-use\-dynamic\fR" 4 +.IX Item "--use-dynamic" +.PD +When displaying symbols, this option makes \fBreadelf\fR use the +symbol table in the file's dynamic section, rather than the one in the +symbols section. +.IP "\fB\-x <number or name>\fR" 4 +.IX Item "-x <number or name>" +.PD 0 +.IP "\fB\-\-hex\-dump=<number or name>\fR" 4 +.IX Item "--hex-dump=<number or name>" +.PD +Displays the contents of the indicated section as a hexadecimal dump. +A number identifies a particular section by index in the section table; +any other string identifies all sections with that name in the object file. +.IP "\fB\-w[liaprmfFsoR]\fR" 4 +.IX Item "-w[liaprmfFsoR]" +.PD 0 +.IP "\fB\-\-debug\-dump[=line,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames\-interp,=str,=loc,=Ranges]\fR" 4 +.IX Item "--debug-dump[=line,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges]" +.PD +Displays the contents of the debug sections in the file, if any are +present. If one of the optional letters or words follows the switch +then only data found in those specific sections will be dumped. +.IP "\fB\-I\fR" 4 +.IX Item "-I" +.PD 0 +.IP "\fB\-\-histogram\fR" 4 +.IX Item "--histogram" +.PD +Display a histogram of bucket list lengths when displaying the contents +of the symbol tables. +.IP "\fB\-v\fR" 4 +.IX Item "-v" +.PD 0 +.IP "\fB\-\-version\fR" 4 +.IX Item "--version" +.PD +Display the version number of readelf. +.IP "\fB\-W\fR" 4 +.IX Item "-W" +.PD 0 +.IP "\fB\-\-wide\fR" 4 +.IX Item "--wide" +.PD +Don't break output lines to fit into 80 columns. By default +\&\fBreadelf\fR breaks section header and segment listing lines for +64\-bit \s-1ELF\s0 files, so that they fit into 80 columns. This option causes +\&\fBreadelf\fR to print each section header resp. each segment one a +single line, which is far more readable on terminals wider than 80 columns. +.IP "\fB\-H\fR" 4 +.IX Item "-H" +.PD 0 +.IP "\fB\-\-help\fR" 4 +.IX Item "--help" +.PD +Display the command line options understood by \fBreadelf\fR. +.IP "\fB@\fR\fIfile\fR" 4 +.IX Item "@file" +Read command-line options from \fIfile\fR. The options read are +inserted in place of the original @\fIfile\fR option. If \fIfile\fR +does not exist, or cannot be read, then the option will be treated +literally, and not removed. +.Sp +Options in \fIfile\fR are separated by whitespace. A whitespace +character may be included in an option by surrounding the entire +option in either single or double quotes. Any character (including a +backslash) may be included by prefixing the character to be included +with a backslash. The \fIfile\fR may itself contain additional +@\fIfile\fR options; any such options will be processed recursively. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIobjdump\fR\|(1), and the Info entries for \fIbinutils\fR. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, +2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 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 \*(L"\s-1GNU\s0 Free Documentation License\*(R". diff --git a/gnu/usr.bin/binutils/size/size.1 b/gnu/usr.bin/binutils/size/size.1 new file mode 100644 index 0000000..3f90967 --- /dev/null +++ b/gnu/usr.bin/binutils/size/size.1 @@ -0,0 +1,263 @@ +.\" $FreeBSD$ +.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "SIZE 1" +.TH SIZE 1 "2010-10-30" "binutils-2.17.50" "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +size \- list section sizes and total size. +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +size [\fB\-A\fR|\fB\-B\fR|\fB\-\-format=\fR\fIcompatibility\fR] + [\fB\-\-help\fR] + [\fB\-d\fR|\fB\-o\fR|\fB\-x\fR|\fB\-\-radix=\fR\fInumber\fR] + [\fB\-t\fR|\fB\-\-totals\fR] + [\fB\-\-target=\fR\fIbfdname\fR] [\fB\-V\fR|\fB\-\-version\fR] + [\fIobjfile\fR...] +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \s-1GNU\s0 \fBsize\fR utility lists the section sizes\-\-\-and the total +size\-\-\-for each of the object or archive files \fIobjfile\fR in its +argument list. By default, one line of output is generated for each +object file or each module in an archive. +.PP +\&\fIobjfile\fR... are the object files to be examined. +If none are specified, the file \f(CW\*(C`a.out\*(C'\fR will be used. +.SH "OPTIONS" +.IX Header "OPTIONS" +The command line options have the following meanings: +.IP "\fB\-A\fR" 4 +.IX Item "-A" +.PD 0 +.IP "\fB\-B\fR" 4 +.IX Item "-B" +.IP "\fB\-\-format=\fR\fIcompatibility\fR" 4 +.IX Item "--format=compatibility" +.PD +Using one of these options, you can choose whether the output from \s-1GNU\s0 +\&\fBsize\fR resembles output from System V \fBsize\fR (using \fB\-A\fR, +or \fB\-\-format=sysv\fR), or Berkeley \fBsize\fR (using \fB\-B\fR, or +\&\fB\-\-format=berkeley\fR). The default is the one-line format similar to +Berkeley's. +.Sp +Here is an example of the Berkeley (default) format of output from +\&\fBsize\fR: +.Sp +.Vb 4 +\& $ size \-\-format=Berkeley ranlib size +\& text data bss dec hex filename +\& 294880 81920 11592 388392 5ed28 ranlib +\& 294880 81920 11888 388688 5ee50 size +.Ve +.Sp +This is the same data, but displayed closer to System V conventions: +.Sp +.Vb 7 +\& $ size \-\-format=SysV ranlib size +\& ranlib : +\& section size addr +\& .text 294880 8192 +\& .data 81920 303104 +\& .bss 11592 385024 +\& Total 388392 +\& +\& +\& size : +\& section size addr +\& .text 294880 8192 +\& .data 81920 303104 +\& .bss 11888 385024 +\& Total 388688 +.Ve +.IP "\fB\-\-help\fR" 4 +.IX Item "--help" +Show a summary of acceptable arguments and options. +.IP "\fB\-d\fR" 4 +.IX Item "-d" +.PD 0 +.IP "\fB\-o\fR" 4 +.IX Item "-o" +.IP "\fB\-x\fR" 4 +.IX Item "-x" +.IP "\fB\-\-radix=\fR\fInumber\fR" 4 +.IX Item "--radix=number" +.PD +Using one of these options, you can control whether the size of each +section is given in decimal (\fB\-d\fR, or \fB\-\-radix=10\fR); octal +(\fB\-o\fR, or \fB\-\-radix=8\fR); or hexadecimal (\fB\-x\fR, or +\&\fB\-\-radix=16\fR). In \fB\-\-radix=\fR\fInumber\fR, only the three +values (8, 10, 16) are supported. The total size is always given in two +radices; decimal and hexadecimal for \fB\-d\fR or \fB\-x\fR output, or +octal and hexadecimal if you're using \fB\-o\fR. +.IP "\fB\-t\fR" 4 +.IX Item "-t" +.PD 0 +.IP "\fB\-\-totals\fR" 4 +.IX Item "--totals" +.PD +Show totals of all objects listed (Berkeley format listing mode only). +.IP "\fB\-\-target=\fR\fIbfdname\fR" 4 +.IX Item "--target=bfdname" +Specify that the object-code format for \fIobjfile\fR is +\&\fIbfdname\fR. This option may not be necessary; \fBsize\fR can +automatically recognize many formats. +.IP "\fB\-V\fR" 4 +.IX Item "-V" +.PD 0 +.IP "\fB\-\-version\fR" 4 +.IX Item "--version" +.PD +Display the version number of \fBsize\fR. +.IP "\fB@\fR\fIfile\fR" 4 +.IX Item "@file" +Read command-line options from \fIfile\fR. The options read are +inserted in place of the original @\fIfile\fR option. If \fIfile\fR +does not exist, or cannot be read, then the option will be treated +literally, and not removed. +.Sp +Options in \fIfile\fR are separated by whitespace. A whitespace +character may be included in an option by surrounding the entire +option in either single or double quotes. Any character (including a +backslash) may be included by prefixing the character to be included +with a backslash. The \fIfile\fR may itself contain additional +@\fIfile\fR options; any such options will be processed recursively. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIar\fR\|(1), \fIobjdump\fR\|(1), \fIreadelf\fR\|(1), and the Info entries for \fIbinutils\fR. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, +2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 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 \*(L"\s-1GNU\s0 Free Documentation License\*(R". diff --git a/gnu/usr.bin/binutils/strings/strings.1 b/gnu/usr.bin/binutils/strings/strings.1 new file mode 100644 index 0000000..075e3a5 --- /dev/null +++ b/gnu/usr.bin/binutils/strings/strings.1 @@ -0,0 +1,254 @@ +.\" $FreeBSD$ +.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "STRINGS 1" +.TH STRINGS 1 "2010-10-30" "binutils-2.17.50" "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +strings \- print the strings of printable characters in files. +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +strings [\fB\-afov\fR] [\fB\-\fR\fImin-len\fR] + [\fB\-n\fR \fImin-len\fR] [\fB\-\-bytes=\fR\fImin-len\fR] + [\fB\-t\fR \fIradix\fR] [\fB\-\-radix=\fR\fIradix\fR] + [\fB\-e\fR \fIencoding\fR] [\fB\-\-encoding=\fR\fIencoding\fR] + [\fB\-\fR] [\fB\-\-all\fR] [\fB\-\-print\-file\-name\fR] + [\fB\-T\fR \fIbfdname\fR] [\fB\-\-target=\fR\fIbfdname\fR] + [\fB\-\-help\fR] [\fB\-\-version\fR] \fIfile\fR... +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +For each \fIfile\fR given, \s-1GNU\s0 \fBstrings\fR prints the printable +character sequences that are at least 4 characters long (or the number +given with the options below) and are followed by an unprintable +character. By default, it only prints the strings from the initialized +and loaded sections of object files; for other types of files, it prints +the strings from the whole file. +.PP +\&\fBstrings\fR is mainly useful for determining the contents of non-text +files. +.SH "OPTIONS" +.IX Header "OPTIONS" +.IP "\fB\-a\fR" 4 +.IX Item "-a" +.PD 0 +.IP "\fB\-\-all\fR" 4 +.IX Item "--all" +.IP "\fB\-\fR" 4 +.IX Item "-" +.PD +Do not scan only the initialized and loaded sections of object files; +scan the whole files. +.IP "\fB\-f\fR" 4 +.IX Item "-f" +.PD 0 +.IP "\fB\-\-print\-file\-name\fR" 4 +.IX Item "--print-file-name" +.PD +Print the name of the file before each string. +.IP "\fB\-\-help\fR" 4 +.IX Item "--help" +Print a summary of the program usage on the standard output and exit. +.IP "\fB\-\fR\fImin-len\fR" 4 +.IX Item "-min-len" +.PD 0 +.IP "\fB\-n\fR \fImin-len\fR" 4 +.IX Item "-n min-len" +.IP "\fB\-\-bytes=\fR\fImin-len\fR" 4 +.IX Item "--bytes=min-len" +.PD +Print sequences of characters that are at least \fImin-len\fR characters +long, instead of the default 4. +.IP "\fB\-o\fR" 4 +.IX Item "-o" +Like \fB\-t o\fR. Some other versions of \fBstrings\fR have \fB\-o\fR +act like \fB\-t d\fR instead. Since we can not be compatible with both +ways, we simply chose one. +.IP "\fB\-t\fR \fIradix\fR" 4 +.IX Item "-t radix" +.PD 0 +.IP "\fB\-\-radix=\fR\fIradix\fR" 4 +.IX Item "--radix=radix" +.PD +Print the offset within the file before each string. The single +character argument specifies the radix of the offset\-\-\-\fBo\fR for +octal, \fBx\fR for hexadecimal, or \fBd\fR for decimal. +.IP "\fB\-e\fR \fIencoding\fR" 4 +.IX Item "-e encoding" +.PD 0 +.IP "\fB\-\-encoding=\fR\fIencoding\fR" 4 +.IX Item "--encoding=encoding" +.PD +Select the character encoding of the strings that are to be found. +Possible values for \fIencoding\fR are: \fBs\fR = single\-7\-bit\-byte +characters (\s-1ASCII\s0, \s-1ISO\s0 8859, etc., default), \fBS\fR = +single\-8\-bit\-byte characters, \fBb\fR = 16\-bit bigendian, \fBl\fR = +16\-bit littleendian, \fBB\fR = 32\-bit bigendian, \fBL\fR = 32\-bit +littleendian. Useful for finding wide character strings. +.IP "\fB\-T\fR \fIbfdname\fR" 4 +.IX Item "-T bfdname" +.PD 0 +.IP "\fB\-\-target=\fR\fIbfdname\fR" 4 +.IX Item "--target=bfdname" +.PD +Specify an object code format other than your system's default format. +.IP "\fB\-v\fR" 4 +.IX Item "-v" +.PD 0 +.IP "\fB\-\-version\fR" 4 +.IX Item "--version" +.PD +Print the program version number on the standard output and exit. +.IP "\fB@\fR\fIfile\fR" 4 +.IX Item "@file" +Read command-line options from \fIfile\fR. The options read are +inserted in place of the original @\fIfile\fR option. If \fIfile\fR +does not exist, or cannot be read, then the option will be treated +literally, and not removed. +.Sp +Options in \fIfile\fR are separated by whitespace. A whitespace +character may be included in an option by surrounding the entire +option in either single or double quotes. Any character (including a +backslash) may be included by prefixing the character to be included +with a backslash. The \fIfile\fR may itself contain additional +@\fIfile\fR options; any such options will be processed recursively. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIar\fR\|(1), \fInm\fR\|(1), \fIobjdump\fR\|(1), \fIranlib\fR\|(1), \fIreadelf\fR\|(1) +and the Info entries for \fIbinutils\fR. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, +2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 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 \*(L"\s-1GNU\s0 Free Documentation License\*(R". diff --git a/gnu/usr.bin/binutils/strip/strip.1 b/gnu/usr.bin/binutils/strip/strip.1 new file mode 100644 index 0000000..5eb714d --- /dev/null +++ b/gnu/usr.bin/binutils/strip/strip.1 @@ -0,0 +1,392 @@ +.\" $FreeBSD$ +.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "STRIP 1" +.TH STRIP 1 "2010-10-30" "binutils-2.17.50" "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +strip \- Discard symbols from object files. +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +strip [\fB\-F\fR \fIbfdname\fR |\fB\-\-target=\fR\fIbfdname\fR] + [\fB\-I\fR \fIbfdname\fR |\fB\-\-input\-target=\fR\fIbfdname\fR] + [\fB\-O\fR \fIbfdname\fR |\fB\-\-output\-target=\fR\fIbfdname\fR] + [\fB\-s\fR|\fB\-\-strip\-all\fR] + [\fB\-S\fR|\fB\-g\fR|\fB\-d\fR|\fB\-\-strip\-debug\fR] + [\fB\-K\fR \fIsymbolname\fR |\fB\-\-keep\-symbol=\fR\fIsymbolname\fR] + [\fB\-N\fR \fIsymbolname\fR |\fB\-\-strip\-symbol=\fR\fIsymbolname\fR] + [\fB\-w\fR|\fB\-\-wildcard\fR] + [\fB\-x\fR|\fB\-\-discard\-all\fR] [\fB\-X\fR |\fB\-\-discard\-locals\fR] + [\fB\-R\fR \fIsectionname\fR |\fB\-\-remove\-section=\fR\fIsectionname\fR] + [\fB\-o\fR \fIfile\fR] [\fB\-p\fR|\fB\-\-preserve\-dates\fR] + [\fB\-\-keep\-file\-symbols\fR] + [\fB\-\-only\-keep\-debug\fR] + [\fB\-v\fR |\fB\-\-verbose\fR] [\fB\-V\fR|\fB\-\-version\fR] + [\fB\-\-help\fR] [\fB\-\-info\fR] + \fIobjfile\fR... +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\s-1GNU\s0 \fBstrip\fR discards all symbols from object files +\&\fIobjfile\fR. The list of object files may include archives. +At least one object file must be given. +.PP +\&\fBstrip\fR modifies the files named in its argument, +rather than writing modified copies under different names. +.SH "OPTIONS" +.IX Header "OPTIONS" +.IP "\fB\-F\fR \fIbfdname\fR" 4 +.IX Item "-F bfdname" +.PD 0 +.IP "\fB\-\-target=\fR\fIbfdname\fR" 4 +.IX Item "--target=bfdname" +.PD +Treat the original \fIobjfile\fR as a file with the object +code format \fIbfdname\fR, and rewrite it in the same format. +.IP "\fB\-\-help\fR" 4 +.IX Item "--help" +Show a summary of the options to \fBstrip\fR and exit. +.IP "\fB\-\-info\fR" 4 +.IX Item "--info" +Display a list showing all architectures and object formats available. +.IP "\fB\-I\fR \fIbfdname\fR" 4 +.IX Item "-I bfdname" +.PD 0 +.IP "\fB\-\-input\-target=\fR\fIbfdname\fR" 4 +.IX Item "--input-target=bfdname" +.PD +Treat the original \fIobjfile\fR as a file with the object +code format \fIbfdname\fR. +.IP "\fB\-O\fR \fIbfdname\fR" 4 +.IX Item "-O bfdname" +.PD 0 +.IP "\fB\-\-output\-target=\fR\fIbfdname\fR" 4 +.IX Item "--output-target=bfdname" +.PD +Replace \fIobjfile\fR with a file in the output format \fIbfdname\fR. +.IP "\fB\-R\fR \fIsectionname\fR" 4 +.IX Item "-R sectionname" +.PD 0 +.IP "\fB\-\-remove\-section=\fR\fIsectionname\fR" 4 +.IX Item "--remove-section=sectionname" +.PD +Remove any section named \fIsectionname\fR from the output file. This +option may be given more than once. Note that using this option +inappropriately may make the output file unusable. +.IP "\fB\-s\fR" 4 +.IX Item "-s" +.PD 0 +.IP "\fB\-\-strip\-all\fR" 4 +.IX Item "--strip-all" +.PD +Remove all symbols. +.IP "\fB\-g\fR" 4 +.IX Item "-g" +.PD 0 +.IP "\fB\-S\fR" 4 +.IX Item "-S" +.IP "\fB\-d\fR" 4 +.IX Item "-d" +.IP "\fB\-\-strip\-debug\fR" 4 +.IX Item "--strip-debug" +.PD +Remove debugging symbols only. +.IP "\fB\-\-strip\-unneeded\fR" 4 +.IX Item "--strip-unneeded" +Remove all symbols that are not needed for relocation processing. +.IP "\fB\-K\fR \fIsymbolname\fR" 4 +.IX Item "-K symbolname" +.PD 0 +.IP "\fB\-\-keep\-symbol=\fR\fIsymbolname\fR" 4 +.IX Item "--keep-symbol=symbolname" +.PD +When stripping symbols, keep symbol \fIsymbolname\fR even if it would +normally be stripped. This option may be given more than once. +.IP "\fB\-N\fR \fIsymbolname\fR" 4 +.IX Item "-N symbolname" +.PD 0 +.IP "\fB\-\-strip\-symbol=\fR\fIsymbolname\fR" 4 +.IX Item "--strip-symbol=symbolname" +.PD +Remove symbol \fIsymbolname\fR from the source file. This option may be +given more than once, and may be combined with strip options other than +\&\fB\-K\fR. +.IP "\fB\-o\fR \fIfile\fR" 4 +.IX Item "-o file" +Put the stripped output in \fIfile\fR, rather than replacing the +existing file. When this argument is used, only one \fIobjfile\fR +argument may be specified. +.IP "\fB\-p\fR" 4 +.IX Item "-p" +.PD 0 +.IP "\fB\-\-preserve\-dates\fR" 4 +.IX Item "--preserve-dates" +.PD +Preserve the access and modification dates of the file. +.IP "\fB\-w\fR" 4 +.IX Item "-w" +.PD 0 +.IP "\fB\-\-wildcard\fR" 4 +.IX Item "--wildcard" +.PD +Permit regular expressions in \fIsymbolname\fRs used in other command +line options. The question mark (?), asterisk (*), backslash (\e) and +square brackets ([]) operators can be used anywhere in the symbol +name. If the first character of the symbol name is the exclamation +point (!) then the sense of the switch is reversed for that symbol. +For example: +.Sp +.Vb 1 +\& \-w \-K !foo \-K fo* +.Ve +.Sp +would cause strip to only keep symbols that start with the letters +\&\*(L"fo\*(R", but to discard the symbol \*(L"foo\*(R". +.IP "\fB\-x\fR" 4 +.IX Item "-x" +.PD 0 +.IP "\fB\-\-discard\-all\fR" 4 +.IX Item "--discard-all" +.PD +Remove non-global symbols. +.IP "\fB\-X\fR" 4 +.IX Item "-X" +.PD 0 +.IP "\fB\-\-discard\-locals\fR" 4 +.IX Item "--discard-locals" +.PD +Remove compiler-generated local symbols. +(These usually start with \fBL\fR or \fB.\fR.) +.IP "\fB\-\-keep\-file\-symbols\fR" 4 +.IX Item "--keep-file-symbols" +When stripping a file, perhaps with \fB\-\-strip\-debug\fR or +\&\fB\-\-strip\-unneeded\fR, retain any symbols specifying source file names, +which would otherwise get stripped. +.IP "\fB\-\-only\-keep\-debug\fR" 4 +.IX Item "--only-keep-debug" +Strip a file, removing contents of any sections that would not be +stripped by \fB\-\-strip\-debug\fR and leaving the debugging sections +intact. In \s-1ELF\s0 files, this preserves all note sections in the output. +.Sp +The intention is that this option will be used in conjunction with +\&\fB\-\-add\-gnu\-debuglink\fR to create a two part executable. One a +stripped binary which will occupy less space in \s-1RAM\s0 and in a +distribution and the second a debugging information file which is only +needed if debugging abilities are required. The suggested procedure +to create these files is as follows: +.RS 4 +.IP "1.<Link the executable as normal. Assuming that is is called>" 4 +.IX Item "1.<Link the executable as normal. Assuming that is is called>" +\&\f(CW\*(C`foo\*(C'\fR then... +.ie n .IP "1.<Run ""objcopy \-\-only\-keep\-debug foo foo.dbg"" to>" 4 +.el .IP "1.<Run \f(CWobjcopy \-\-only\-keep\-debug foo foo.dbg\fR to>" 4 +.IX Item "1.<Run objcopy --only-keep-debug foo foo.dbg to>" +create a file containing the debugging info. +.ie n .IP "1.<Run ""objcopy \-\-strip\-debug foo"" to create a>" 4 +.el .IP "1.<Run \f(CWobjcopy \-\-strip\-debug foo\fR to create a>" 4 +.IX Item "1.<Run objcopy --strip-debug foo to create a>" +stripped executable. +.ie n .IP "1.<Run ""objcopy \-\-add\-gnu\-debuglink=foo.dbg foo"">" 4 +.el .IP "1.<Run \f(CWobjcopy \-\-add\-gnu\-debuglink=foo.dbg foo\fR>" 4 +.IX Item "1.<Run objcopy --add-gnu-debuglink=foo.dbg foo>" +to add a link to the debugging info into the stripped executable. +.RE +.RS 4 +.Sp +Note \- the choice of \f(CW\*(C`.dbg\*(C'\fR as an extension for the debug info +file is arbitrary. Also the \f(CW\*(C`\-\-only\-keep\-debug\*(C'\fR step is +optional. You could instead do this: +.IP "1.<Link the executable as normal.>" 4 +.IX Item "1.<Link the executable as normal.>" +.PD 0 +.ie n .IP "1.<Copy ""foo"" to ""foo.full"">" 4 +.el .IP "1.<Copy \f(CWfoo\fR to \f(CWfoo.full\fR>" 4 +.IX Item "1.<Copy foo to foo.full>" +.ie n .IP "1.<Run ""strip \-\-strip\-debug foo"">" 4 +.el .IP "1.<Run \f(CWstrip \-\-strip\-debug foo\fR>" 4 +.IX Item "1.<Run strip --strip-debug foo>" +.ie n .IP "1.<Run ""objcopy \-\-add\-gnu\-debuglink=foo.full foo"">" 4 +.el .IP "1.<Run \f(CWobjcopy \-\-add\-gnu\-debuglink=foo.full foo\fR>" 4 +.IX Item "1.<Run objcopy --add-gnu-debuglink=foo.full foo>" +.RE +.RS 4 +.PD +.Sp +ie the file pointed to by the \fB\-\-add\-gnu\-debuglink\fR can be the +full executable. It does not have to be a file created by the +\&\fB\-\-only\-keep\-debug\fR switch. +.Sp +Note \- this switch is only intended for use on fully linked files. It +does not make sense to use it on object files where the debugging +information may be incomplete. Besides the gnu_debuglink feature +currently only supports the presence of one filename containing +debugging information, not multiple filenames on a one-per-object-file +basis. +.RE +.IP "\fB\-V\fR" 4 +.IX Item "-V" +.PD 0 +.IP "\fB\-\-version\fR" 4 +.IX Item "--version" +.PD +Show the version number for \fBstrip\fR. +.IP "\fB\-v\fR" 4 +.IX Item "-v" +.PD 0 +.IP "\fB\-\-verbose\fR" 4 +.IX Item "--verbose" +.PD +Verbose output: list all object files modified. In the case of +archives, \fBstrip \-v\fR lists all members of the archive. +.IP "\fB@\fR\fIfile\fR" 4 +.IX Item "@file" +Read command-line options from \fIfile\fR. The options read are +inserted in place of the original @\fIfile\fR option. If \fIfile\fR +does not exist, or cannot be read, then the option will be treated +literally, and not removed. +.Sp +Options in \fIfile\fR are separated by whitespace. A whitespace +character may be included in an option by surrounding the entire +option in either single or double quotes. Any character (including a +backslash) may be included by prefixing the character to be included +with a backslash. The \fIfile\fR may itself contain additional +@\fIfile\fR options; any such options will be processed recursively. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +the Info entries for \fIbinutils\fR. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, +2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 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 \*(L"\s-1GNU\s0 Free Documentation License\*(R". |
