diff options
author | bapt <bapt@FreeBSD.org> | 2015-03-02 17:20:34 +0000 |
---|---|---|
committer | bapt <bapt@FreeBSD.org> | 2015-03-02 17:20:34 +0000 |
commit | 16e0d32606b992822b1daf6dece064edf6517305 (patch) | |
tree | d0ee3793b33a0368f1e5e21167fefa7c8b23b8e7 | |
parent | 4f48dc950ba2d6423d4f4c83899f03525d151b77 (diff) | |
download | FreeBSD-src-16e0d32606b992822b1daf6dece064edf6517305.zip FreeBSD-src-16e0d32606b992822b1daf6dece064edf6517305.tar.gz |
Generate manpage out of the texinfo files using texi2mdoc
-rw-r--r-- | contrib/binutils/binutils/doc/binutils.7 | 4917 | ||||
-rw-r--r-- | contrib/binutils/gas/doc/as.7 | 8368 | ||||
-rw-r--r-- | contrib/binutils/ld/ld.7 | 7819 | ||||
-rw-r--r-- | contrib/binutils/ld/ldint.7 | 1277 |
4 files changed, 22381 insertions, 0 deletions
diff --git a/contrib/binutils/binutils/doc/binutils.7 b/contrib/binutils/binutils/doc/binutils.7 new file mode 100644 index 0000000..2c4c0e1 --- /dev/null +++ b/contrib/binutils/binutils/doc/binutils.7 @@ -0,0 +1,4917 @@ +.Dd 2015-03-02 +.Dt BINUTILS 7 +.Os +.Sh NAME +.Nm binutils +.Nd GNU Binary Utilities +.Sh Introduction +This brief manual contains documentation for the GNU binary utilities version "2.17.50 +[FreeBSD] 2007-07-03": +.Pp +This document is distributed under the terms of the GNU Free Documentation +License. A copy of the license is included in the section entitled "GNU Free +Documentation License". +.Pp +.Sh ar +.Bd -literal -offset indent +ar [-]p[mod [relpos] [count]] archive [member...] +ar -M [ <mri-script ] +.Ed +.Pp +The GNU +.Xr ar +program creates, modifies, and extracts from archives. An +.Em archive +is a single file holding a collection of other files in a structure that makes +it possible to retrieve the original individual files (called +.Em members +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 +GNU +.Xr ar +can maintain archives whose members have names of any length; however, depending +on how +.Xr ar +is configured on your system, a limit on member-name length may be imposed +for compatibility with archive formats maintained with other tools. If it +exists, the limit is often 15 characters (typical of formats related to a.out) +or 16 characters (typical of formats related to coff). +.Pp +.Xr ar +is considered a binary utility because archives of this sort are most often +used as +.Em libraries +holding commonly needed subroutines. +.Pp +.Xr ar +creates an index to the symbols defined in relocatable object modules in the +archive when you specify the modifier +.Li s . +Once created, this index is updated in the archive whenever +.Xr ar +makes a change to its contents (save for the +.Li q +update operation). An archive with such an index speeds up linking to the +library, and allows routines in the library to call each other without regard +to their placement in the archive. +.Pp +You may use +.Li nm -s +or +.Li nm --print-armap +to list this index table. If an archive lacks the table, another form of +.Xr ar +called +.Xr ranlib +can be used to add just the table. +.Pp +GNU +.Xr ar +is designed to be compatible with two different facilities. You can control +its activity using command-line options, like the different varieties of +.Xr ar +on Unix systems; or, if you specify the single command-line option +.Op -M , +you can control it with a script supplied via standard input, like the MRI +\(lqlibrarian\(rq program. +.Pp +.Ss Controlling Xr ar on the Command Line +.Bd -literal -offset indent +ar [-X32_64] [-]p[mod [relpos] [count]] archive [member...] +.Ed +.Pp +When you use +.Xr ar +in the Unix style, +.Xr ar +insists on at least two arguments to execute: one keyletter specifying the +.Em operation +(optionally accompanied by other keyletters specifying +.Em modifiers ) , +and the archive name to act on. +.Pp +Most operations can also accept further +.Va member +arguments, specifying particular files to operate on. +.Pp +GNU +.Xr ar +allows you to mix the operation code +.Va p +and modifier flags +.Va mod +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 +.Va p +keyletter specifies what operation to execute; it may be any of the following, +but you must specify only one of them: +.Pp +.Bl -tag -width Ds +.It d +.Em Delete +modules from the archive. Specify the names of modules to be deleted as +.Va member +\&...; the archive is untouched if you specify no files to delete. +.Pp +If you specify the +.Li v +modifier, +.Xr ar +lists each module as it is deleted. +.Pp +.It m +Use this operation to +.Em move +members in an archive. +.Pp +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. +.Pp +If no modifiers are used with +.Li m , +any members you name in the +.Va member +arguments are moved to the +.Em end +of the archive; you can use the +.Li a , +.Li b , +or +.Li i +modifiers to move them to a specified place instead. +.Pp +.It p +.Em Print +the specified members of the archive, to the standard output file. If the +.Li v +modifier is specified, show the member name before copying its contents to +standard output. +.Pp +If you specify no +.Va member +arguments, all the files in the archive are printed. +.Pp +.It q +.Em Quick append ; +Historically, add the files +.Va member +\&...to the end of +.Va archive , +without checking for replacement. +.Pp +The modifiers +.Li a , +.Li b , +and +.Li i +do +.Em not +affect this operation; new members are always placed at the end of the archive. +.Pp +The modifier +.Li v +makes +.Xr ar +list each file as it is appended. +.Pp +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 +.Li ar s +or +.Xr ranlib +explicitly to update the symbol table index. +.Pp +However, too many different systems assume quick append rebuilds the index, +so GNU +.Xr ar +implements +.Li q +as a synonym for +.Li r . +.Pp +.It r +Insert the files +.Va member +\&...into +.Va archive +(with +.Em replacement ) . +This operation differs from +.Li q +in that any previously existing members are deleted if their names match those +being added. +.Pp +If one of the files named in +.Va member +\&...does not exist, +.Xr ar +displays an error message, and leaves undisturbed any existing members of +the archive matching that name. +.Pp +By default, new members are added at the end of the file; but you may use +one of the modifiers +.Li a , +.Li b , +or +.Li i +to request placement relative to some existing member. +.Pp +The modifier +.Li v +used with this operation elicits a line of output for each file inserted, +along with one of the letters +.Li a +or +.Li r +to indicate whether the file was appended (no old member deleted) or replaced. +.Pp +.It t +Display a +.Em table +listing the contents of +.Va archive , +or those of the files listed in +.Va member +\&...that are present in the archive. Normally only the member name is shown; if +you also want to see the modes (permissions), timestamp, owner, group, and +size, you can request that by also specifying the +.Li v +modifier. +.Pp +If you do not specify a +.Va member , +all files in the archive are listed. +.Pp +If there is more than one file with the same name (say, +.Li fie ) +in an archive (say +.Li b.a ) , +.Li ar t b.a fie +lists only the first instance; to see them all, you must ask for a complete +listing---in our example, +.Li ar t b.a . +.Pp +.It x +.Em Extract +members (named +.Va member ) +from the archive. You can use the +.Li v +modifier with this operation, to request that +.Xr ar +list each name as it extracts it. +.Pp +If you do not specify a +.Va member , +all files in the archive are extracted. +.Pp +.El +A number of modifiers ( +.Va mod ) +may immediately follow the +.Va p +keyletter, to specify variations on an operation's behavior: +.Pp +.Bl -tag -width Ds +.It a +Add new files +.Em after +an existing member of the archive. If you use the modifier +.Li a , +the name of an existing archive member must be present as the +.Va relpos +argument, before the +.Va archive +specification. +.Pp +.It b +Add new files +.Em before +an existing member of the archive. If you use the modifier +.Li b , +the name of an existing archive member must be present as the +.Va relpos +argument, before the +.Va archive +specification. (same as +.Li i ) . +.Pp +.It c +.Em Create +the archive. The specified +.Va archive +is always created if it did not exist, when you request an update. But a warning +is issued unless you specify in advance that you expect to create it, by using +this modifier. +.Pp +.It f +Truncate names in the archive. GNU +.Xr ar +will normally permit file names of any length. This will cause it to create +archives which are not compatible with the native +.Xr ar +program on some systems. If this is a concern, the +.Li f +modifier may be used to truncate file names when putting them in the archive. +.Pp +.It i +Insert new files +.Em before +an existing member of the archive. If you use the modifier +.Li i , +the name of an existing archive member must be present as the +.Va relpos +argument, before the +.Va archive +specification. (same as +.Li b ) . +.Pp +.It l +This modifier is accepted but not used. +.Pp +.It N +Uses the +.Va count +parameter. This is used if there are multiple entries in the archive with +the same name. Extract or delete instance +.Va count +of the given name from the archive. +.Pp +.It o +Preserve the +.Em original +dates of members when extracting them. If you do not specify this modifier, +files extracted from the archive are stamped with the time of extraction. +.Pp +.It P +Use the full path name when matching names in the archive. GNU +.Xr ar +can not create an archive with a full path name (such archives are not POSIX +complaint), but other archive creators can. This option will cause GNU +.Xr ar +to match file names using a complete path name, which can be convenient when +extracting a single file from an archive created by another tool. +.Pp +.It 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 +.Li ar s +on an archive is equivalent to running +.Li ranlib +on it. +.Pp +.It S +Do not generate an archive symbol table. This can speed up building a large +library in several steps. The resulting archive can not be used with the linker. +In order to build a symbol table, you must omit the +.Li S +modifier on the last execution of +.Li ar , +or you must run +.Li ranlib +on the archive. +.Pp +.It u +Normally, +.Li ar r +\&...inserts all files listed into the archive. If you would like to insert +.Em only +those of the files you list that are newer than existing members of the same +names, use this modifier. The +.Li u +modifier is allowed only for the operation +.Li r +(replace). In particular, the combination +.Li qu +is not allowed, since checking the timestamps would lose any speed advantage +from the operation +.Li q . +.Pp +.It v +This modifier requests the +.Em verbose +version of an operation. Many operations display additional information, such +as filenames processed, when the modifier +.Li v +is appended. +.Pp +.It V +This modifier shows the version number of +.Xr ar . +.El +.Pp +.Xr ar +ignores an initial option spelt +.Li -X32_64 , +for compatibility with AIX. The behaviour produced by this option is the default +for GNU +.Xr ar . +.Xr ar +does not support any of the other +.Li -X +options; in particular, it does not support +.Op -X32 +which is the default for AIX +.Xr ar . +.Pp +.Ss Controlling Xr ar with a Script +.Bd -literal -offset indent +ar -M [ <script ] +.Ed +.Pp +If you use the single command-line option +.Li -M +with +.Xr ar , +you can control its operation with a rudimentary command language. This form +of +.Xr ar +operates interactively if standard input is coming directly from a terminal. +During interactive use, +.Xr ar +prompts for input (the prompt is +.Li AR > ) , +and continues executing even after errors. If you redirect standard input +to a script file, no prompts are issued, and +.Xr ar +abandons execution (with a nonzero exit code) on any error. +.Pp +The +.Xr ar +command language is +.Em not +designed to be equivalent to the command-line options; in fact, it provides +somewhat less control over archives. The only purpose of the command language +is to ease the transition to GNU +.Xr ar +for developers who already have scripts written for the MRI \(lqlibrarian\(rq program. +.Pp +The syntax for the +.Xr ar +command language is straightforward: +.Bl -bullet +.It +commands are recognized in upper or lower case; for example, +.Li LIST +is the same as +.Li list . +In the following descriptions, commands are shown in upper case for clarity. +.Pp +.It +a single command may appear on each line; it is the first word on the line. +.Pp +.It +empty lines are allowed, and have no effect. +.Pp +.It +comments are allowed; text after either of the characters +.Li * +or +.Li ; +is ignored. +.Pp +.It +Whenever you use a list of names as part of the argument to an +.Xr ar +command, you can separate the individual names with either commas or blanks. +Commas are shown in the explanations below, for clarity. +.Pp +.It +.Li + +is used as a line continuation character; if +.Li + +appears at the end of a line, the text on the following line is considered +part of the current command. +.El +.Pp +Here are the commands you can use in +.Xr ar +scripts, or when using +.Xr ar +interactively. Three of them have special significance: +.Pp +.Li OPEN +or +.Li CREATE +specify a +.Em current archive , +which is a temporary file required for most of the other commands. +.Pp +.Li SAVE +commits the changes so far specified by the script. Prior to +.Li SAVE , +commands affect only the temporary copy of the current archive. +.Pp +.Bl -tag -width Ds +.It ADDLIB Va archive +.It ADDLIB Va archive ( Va module, Va module, ... Va module) +Add all the contents of +.Va archive +(or, if specified, each named +.Va module +from +.Va archive ) +to the current archive. +.Pp +Requires prior use of +.Li OPEN +or +.Li CREATE . +.Pp +.It ADDMOD Va member, Va member, ... Va member +Add each named +.Va member +as a module in the current archive. +.Pp +Requires prior use of +.Li OPEN +or +.Li CREATE . +.Pp +.It CLEAR +Discard the contents of the current archive, canceling the effect of any operations +since the last +.Li SAVE . +May be executed (with no effect) even if no current archive is specified. +.Pp +.It CREATE Va archive +Creates an archive, and makes it the current archive (required for many other +commands). The new archive is created with a temporary name; it is not actually +saved as +.Va archive +until you use +.Li SAVE . +You can overwrite existing archives; similarly, the contents of any existing +file named +.Va archive +will not be destroyed until +.Li SAVE . +.Pp +.It DELETE Va module, Va module, ... Va module +Delete each listed +.Va module +from the current archive; equivalent to +.Li ar -d Va archive Va module ... Va module . +.Pp +Requires prior use of +.Li OPEN +or +.Li CREATE . +.Pp +.It DIRECTORY Va archive ( Va module, ... Va module) +.It DIRECTORY Va archive ( Va module, ... Va module) Va outputfile +List each named +.Va module +present in +.Va archive . +The separate command +.Li VERBOSE +specifies the form of the output: when verbose output is off, output is like +that of +.Li ar -t Va archive Va module... . +When verbose output is on, the listing is like +.Li ar -tv Va archive Va module... . +.Pp +Output normally goes to the standard output stream; however, if you specify +.Va outputfile +as a final argument, +.Xr ar +directs the output to that file. +.Pp +.It END +Exit from +.Xr ar , +with a +.Li 0 +exit code to indicate successful completion. This command does not save the +output file; if you have changed the current archive since the last +.Li SAVE +command, those changes are lost. +.Pp +.It EXTRACT Va module, Va module, ... Va module +Extract each named +.Va module +from the current archive, writing them into the current directory as separate +files. Equivalent to +.Li ar -x Va archive Va module... . +.Pp +Requires prior use of +.Li OPEN +or +.Li CREATE . +.Pp +.It LIST +Display full contents of the current archive, in \(lqverbose\(rq style regardless +of the state of +.Li VERBOSE . +The effect is like +.Li ar tv Va archive . +(This single command is a GNU +.Xr ar +enhancement, rather than present for MRI compatibility.) +.Pp +Requires prior use of +.Li OPEN +or +.Li CREATE . +.Pp +.It OPEN Va archive +Opens an existing archive for use as the current archive (required for many +other commands). Any changes as the result of subsequent commands will not +actually affect +.Va archive +until you next use +.Li SAVE . +.Pp +.It REPLACE Va module, Va module, ... Va module +In the current archive, replace each existing +.Va module +(named in the +.Li REPLACE +arguments) from files in the current working directory. To execute this command +without errors, both the file, and the module in the current archive, must +exist. +.Pp +Requires prior use of +.Li OPEN +or +.Li CREATE . +.Pp +.It VERBOSE +Toggle an internal flag governing the output from +.Li DIRECTORY . +When the flag is on, +.Li DIRECTORY +output matches output from +.Li ar -tv +\&...\&. +.Pp +.It SAVE +Commit your changes to the current archive, and actually save it as a file +with the name specified in the last +.Li CREATE +or +.Li OPEN +command. +.Pp +Requires prior use of +.Li OPEN +or +.Li CREATE . +.Pp +.El +.Sh nm +.Bd -literal -offset indent +nm [-a|--debug-syms] [-g|--extern-only] + [-B] [-C|--demangle[=style]] [-D|--dynamic] + [-S|--print-size] [-s|--print-armap] + [-A|-o|--print-file-name][--special-syms] + [-n|-v|--numeric-sort] [-p|--no-sort] + [-r|--reverse-sort] [--size-sort] [-u|--undefined-only] + [-t radix|--radix=radix] [-P|--portability] + [--target=bfdname] [-fformat|--format=format] + [--defined-only] [-l|--line-numbers] [--no-demangle] + [-V|--version] [-X 32_64] [--help] [objfile...] +.Ed +.Pp +GNU +.Xr nm +lists the symbols from object files +.Va objfile +\&...\&. If no object files are listed as arguments, +.Xr nm +assumes the file +.Pa a.out . +.Pp +For each symbol, +.Xr nm +shows: +.Pp +.Bl -bullet +.It +The symbol value, in the radix selected by options (see below), or hexadecimal +by default. +.Pp +.It +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). +.Pp +.Bl -tag -width Ds +.It A +The symbol's value is absolute, and will not be changed by further linking. +.Pp +.It B +The symbol is in the uninitialized data section (known as BSS). +.Pp +.It C +The symbol is common. Common symbols are uninitialized data. When linking, +multiple common symbols may appear with the same name. If the symbol is defined +anywhere, the common symbols are treated as undefined references. For more +details on common symbols, see the discussion of --warn-common in Options,,Linker +options,ld.info,The GNU linker. +.Pp +.It D +The symbol is in the initialized data section. +.Pp +.It 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. +.Pp +.It I +The symbol is an indirect reference to another symbol. This is a GNU extension +to the a.out object file format which is rarely used. +.Pp +.It N +The symbol is a debugging symbol. +.Pp +.It R +The symbol is in a read only data section. +.Pp +.It S +The symbol is in an uninitialized data section for small objects. +.Pp +.It T +The symbol is in the text (code) section. +.Pp +.It U +The symbol is undefined. +.Pp +.It 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. +.Pp +.It 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. +.Pp +.It - +The symbol is a stabs symbol in an a.out object file. In this case, the next +values printed are the stabs other field, the stabs desc field, and the stab +type. Stabs symbols are used to hold debugging information. For more information, +see Top,Stabs,Stabs Overview,stabs.info, The \(lqstabs\(rq debug format. +.Pp +.It ? +The symbol type is unknown, or object file format specific. +.El +.Pp +.It +The symbol name. +.El +.Pp +The long and short forms of options, shown here as alternatives, are equivalent. +.Pp +.Bl -tag -width Ds +.It -A +.It -o +.It --print-file-name +Precede each symbol by the name of the input file (or archive member) in which +it was found, rather than identifying the input file once only, before all +of its symbols. +.Pp +.It -a +.It --debug-syms +Display all symbols, even debugger-only symbols; normally these are not listed. +.Pp +.It -B +The same as +.Op --format=bsd +(for compatibility with the MIPS +.Xr nm ) . +.Pp +.It -C +.It --demangle[= Va style] +Decode ( +.Em demangle ) +low-level symbol names into user-level names. Besides removing any initial +underscore prepended by the system, this makes C++ function names readable. +Different compilers have different mangling styles. The optional demangling +style argument can be used to choose an appropriate demangling style for your +compiler.See Section +.Dq c++filt , +for more information on demangling. +.Pp +.It --no-demangle +Do not demangle low-level symbol names. This is the default. +.Pp +.It -D +.It --dynamic +Display the dynamic symbols rather than the normal symbols. This is only meaningful +for dynamic objects, such as certain types of shared libraries. +.Pp +.It -f Va format +.It --format= Va format +Use the output format +.Va format , +which can be +.Li bsd , +.Li sysv , +or +.Li posix . +The default is +.Li bsd . +Only the first character of +.Va format +is significant; it can be either upper or lower case. +.Pp +.It -g +.It --extern-only +Display only external symbols. +.Pp +.It -l +.It --line-numbers +For each symbol, use debugging information to try to find a filename and line +number. For a defined symbol, look for the line number of the address of the +symbol. For an undefined symbol, look for the line number of a relocation +entry which refers to the symbol. If line number information can be found, +print it after the other symbol information. +.Pp +.It -n +.It -v +.It --numeric-sort +Sort symbols numerically by their addresses, rather than alphabetically by +their names. +.Pp +.It -p +.It --no-sort +Do not bother to sort the symbols in any order; print them in the order encountered. +.Pp +.It -P +.It --portability +Use the POSIX.2 standard output format instead of the default format. Equivalent +to +.Li -f posix . +.Pp +.It -S +.It --print-size +Print size, not the value, of defined symbols for the +.Li bsd +output format. +.Pp +.It -s +.It --print-armap +When listing symbols from archive members, include the index: a mapping (stored +in the archive by +.Xr ar +or +.Xr ranlib ) +of which modules contain definitions for which names. +.Pp +.It -r +.It --reverse-sort +Reverse the order of the sort (whether numeric or alphabetic); let the last +come first. +.Pp +.It --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 +.Li bsd +output format is used the size of the symbol is printed, rather than the value, +and +.Li -S +must be used in order both size and value to be printed. +.Pp +.It --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 +ARM targets this option would skip the mapping symbols used to mark transitions +between ARM code, THUMB code and data. +.Pp +.It -t Va radix +.It --radix= Va radix +Use +.Va radix +as the radix for printing the symbol values. It must be +.Li d +for decimal, +.Li o +for octal, or +.Li x +for hexadecimal. +.Pp +.It --target= Va bfdname +Specify an object code format other than your system's default format.See Section +.Dq Target Selection , +for more information. +.Pp +.It -u +.It --undefined-only +Display only undefined symbols (those external to each object file). +.Pp +.It --defined-only +Display only defined symbols for each object file. +.Pp +.It -V +.It --version +Show the version number of +.Xr nm +and exit. +.Pp +.It -X +This option is ignored for compatibility with the AIX version of +.Xr nm . +It takes one parameter which must be the string +.Op 32_64 . +The default mode of AIX +.Xr nm +corresponds to +.Op -X 32 , +which is not supported by GNU +.Xr nm . +.Pp +.It --help +Show a summary of the options to +.Xr nm +and exit. +.El +.Pp +.Sh objcopy +.Bd -literal -offset indent +objcopy [-F bfdname|--target=bfdname] + [-I bfdname|--input-target=bfdname] + [-O bfdname|--output-target=bfdname] + [-B bfdarch|--binary-architecture=bfdarch] + [-S|--strip-all] + [-g|--strip-debug] + [-K symbolname|--keep-symbol=symbolname] + [-N symbolname|--strip-symbol=symbolname] + [--strip-unneeded-symbol=symbolname] + [-G symbolname|--keep-global-symbol=symbolname] + [--localize-hidden] + [-L symbolname|--localize-symbol=symbolname] + [--globalize-symbol=symbolname] + [-W symbolname|--weaken-symbol=symbolname] + [-w|--wildcard] + [-x|--discard-all] + [-X|--discard-locals] + [-b byte|--byte=byte] + [-i interleave|--interleave=interleave] + [-j sectionname|--only-section=sectionname] + [-R sectionname|--remove-section=sectionname] + [-p|--preserve-dates] + [--debugging] + [--gap-fill=val] + [--pad-to=address] + [--set-start=val] + [--adjust-start=incr] + [--change-addresses=incr] + [--change-section-address section{=,+,-}val] + [--change-section-lma section{=,+,-}val] + [--change-section-vma section{=,+,-}val] + [--change-warnings] [--no-change-warnings] + [--set-section-flags section=flags] + [--add-section sectionname=filename] + [--rename-section oldname=newname[,flags]] + [--change-leading-char] [--remove-leading-char] + [--reverse-bytes=num] + [--srec-len=ival] [--srec-forceS3] + [--redefine-sym old=new] + [--redefine-syms=filename] + [--weaken] + [--keep-symbols=filename] + [--strip-symbols=filename] + [--strip-unneeded-symbols=filename] + [--keep-global-symbols=filename] + [--localize-symbols=filename] + [--globalize-symbols=filename] + [--weaken-symbols=filename] + [--alt-machine-code=index] + [--prefix-symbols=string] + [--prefix-sections=string] + [--prefix-alloc-sections=string] + [--add-GNU-debuglink=path-to-file] + [--keep-file-symbols] + [--only-keep-debug] + [--extract-symbol] + [--writable-text] + [--readonly-text] + [--pure] + [--impure] + [-v|--verbose] + [-V|--version] + [--help] [--info] + infile [outfile] +.Ed +.Pp +The GNU +.Xr objcopy +utility copies the contents of an object file to another. +.Xr objcopy +uses the GNU bfd Library to read and write the object files. It can write +the destination object file in a format different from that of the source +object file. The exact behavior of +.Xr objcopy +is controlled by command-line options. Note that +.Xr objcopy +should be able to copy a fully linked file between any two formats. However, +copying a relocatable object file between any two formats may not work as +expected. +.Pp +.Xr objcopy +creates temporary files to do its translations and deletes them afterward. +.Xr objcopy +uses bfd to do all its translation work; it has access to all the formats +described in bfd and thus is able to recognize most formats without being +told explicitly.See Section +.Dq BFD . +.Pp +.Xr objcopy +can be used to generate S-records by using an output target of +.Li srec +(e.g., use +.Li -O srec ) . +.Pp +.Xr objcopy +can be used to generate a raw binary file by using an output target of +.Li binary +(e.g., use +.Op -O binary ) . +When +.Xr objcopy +generates a raw binary file, it will essentially produce a memory dump of +the contents of the input object file. All symbols and relocation information +will be discarded. The memory dump will start at the load address of the lowest +section copied into the output file. +.Pp +When generating an S-record or a raw binary file, it may be helpful to use +.Op -S +to remove sections containing debugging information. In some cases +.Op -R +will be useful to remove sections which contain information that is not needed +by the binary file. +.Pp +Note--- +.Xr objcopy +is not able to change the endianness of its input files. If the input format +has an endianness (some formats do not), +.Xr objcopy +can only copy the inputs into file formats that have the same endianness or +which have no endianness (e.g., +.Li srec ) . +(However, see the +.Op --reverse-bytes +option.) +.Pp +.Bl -tag -width Ds +.It Va infile +.It Va outfile +The input and output files, respectively. If you do not specify +.Va outfile , +.Xr objcopy +creates a temporary file and destructively renames the result with the name +of +.Va infile . +.Pp +.It -I Va bfdname +.It --input-target= Va bfdname +Consider the source file's object format to be +.Va bfdname , +rather than attempting to deduce it.See Section +.Dq Target Selection , +for more information. +.Pp +.It -O Va bfdname +.It --output-target= Va bfdname +Write the output file using the object format +.Va bfdname . +See Section.Dq Target Selection , +for more information. +.Pp +.It -F Va bfdname +.It --target= Va bfdname +Use +.Va bfdname +as the object format for both the input and the output file; i.e., simply +transfer data from source to destination with no translation.See Section +.Dq Target Selection , +for more information. +.Pp +.It -B Va bfdarch +.It --binary-architecture= Va bfdarch +Useful when transforming a raw binary input file into an object file. In this +case the output architecture can be set to +.Va bfdarch . +This option will be ignored if the input file has a known +.Va bfdarch . +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_ +.Va objfile +_start, _binary_ +.Va objfile +_end and _binary_ +.Va objfile +_size. e.g. you can transform a picture file into an object file and then +access it in your code using these symbols. +.Pp +.It -j Va sectionname +.It --only-section= Va sectionname +Copy only the named section from the input file to the output file. This option +may be given more than once. Note that using this option inappropriately may +make the output file unusable. +.Pp +.It -R Va sectionname +.It --remove-section= Va sectionname +Remove any section named +.Va sectionname +from the output file. This option may be given more than once. Note that using +this option inappropriately may make the output file unusable. +.Pp +.It -S +.It --strip-all +Do not copy relocation and symbol information from the source file. +.Pp +.It -g +.It --strip-debug +Do not copy debugging symbols or sections from the source file. +.Pp +.It --strip-unneeded +Strip all symbols that are not needed for relocation processing. +.Pp +.It -K Va symbolname +.It --keep-symbol= Va symbolname +When stripping symbols, keep symbol +.Va symbolname +even if it would normally be stripped. This option may be given more than +once. +.Pp +.It -N Va symbolname +.It --strip-symbol= Va symbolname +Do not copy symbol +.Va symbolname +from the source file. This option may be given more than once. +.Pp +.It --strip-unneeded-symbol= Va symbolname +Do not copy symbol +.Va symbolname +from the source file unless it is needed by a relocation. This option may +be given more than once. +.Pp +.It -G Va symbolname +.It --keep-global-symbol= Va symbolname +Keep only symbol +.Va symbolname +global. Make all other symbols local to the file, so that they are not visible +externally. This option may be given more than once. +.Pp +.It --localize-hidden +In an ELF object, mark all symbols that have hidden or internal visibility +as local. This option applies on top of symbol-specific localization options +such as +.Op -L . +.Pp +.It -L Va symbolname +.It --localize-symbol= Va symbolname +Make symbol +.Va symbolname +local to the file, so that it is not visible externally. This option may be +given more than once. +.Pp +.It -W Va symbolname +.It --weaken-symbol= Va symbolname +Make symbol +.Va symbolname +weak. This option may be given more than once. +.Pp +.It --globalize-symbol= Va symbolname +Give symbol +.Va symbolname +global scoping so that it is visible outside of the file in which it is defined. +This option may be given more than once. +.Pp +.It -w +.It --wildcard +Permit regular expressions in +.Va symbolname +s 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: +.Pp +.Bd -literal -offset indent + -w -W !foo -W fo* +.Ed +.Pp +would cause objcopy to weaken all symbols that start with \(lqfo\(rq except for the +symbol \(lqfoo\(rq. +.Pp +.It -x +.It --discard-all +Do not copy non-global symbols from the source file. +.Pp +.It -X +.It --discard-locals +Do not copy compiler-generated local symbols. (These usually start with +.Li L +or +.Li . . ) +.Pp +.It -b Va byte +.It --byte= Va byte +Keep only every +.Va byte +th byte of the input file (header data is not affected). +.Va byte +can be in the range from 0 to +.Va interleave +-1, where +.Va interleave +is given by the +.Op -i +or +.Op --interleave +option, or the default of 4. This option is useful for creating files to program +rom. It is typically used with an +.Li srec +output target. +.Pp +.It -i Va interleave +.It --interleave= Va interleave +Only copy one out of every +.Va interleave +bytes. Select which byte to copy with the +.Op -b +or +.Op --byte +option. The default is 4. +.Xr objcopy +ignores this option if you do not specify either +.Op -b +or +.Op --byte . +.Pp +.It -p +.It --preserve-dates +Set the access and modification dates of the output file to be the same as +those of the input file. +.Pp +.It --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. +.Pp +.It --gap-fill Va val +Fill gaps between sections with +.Va val . +This operation applies to the +.Em load address +(LMA) of the sections. It is done by increasing the size of the section with +the lower address, and filling in the extra space created with +.Va val . +.Pp +.It --pad-to Va address +Pad the output file up to the load address +.Va address . +This is done by increasing the size of the last section. The extra space is +filled in with the value specified by +.Op --gap-fill +(default zero). +.Pp +.It --set-start Va val +Set the start address of the new file to +.Va val . +Not all object file formats support setting the start address. +.Pp +.It --change-start Va incr +.It --adjust-start Va incr +Change the start address by adding +.Va incr . +Not all object file formats support setting the start address. +.Pp +.It --change-addresses Va incr +.It --adjust-vma Va incr +Change the VMA and LMA addresses of all sections, as well as the start address, +by adding +.Va incr . +Some object file formats do not permit section addresses to be changed arbitrarily. +Note that this does not relocate the sections; if the program expects sections +to be loaded at a certain address, and this option is used to change the sections +such that they are loaded at a different address, the program may fail. +.Pp +.It --change-section-address Va section{=,+,-} Va val +.It --adjust-section-vma Va section{=,+,-} Va val +Set or change both the VMA address and the LMA address of the named +.Va section . +If +.Li = +is used, the section address is set to +.Va val . +Otherwise, +.Va val +is added to or subtracted from the section address. See the comments under +.Op --change-addresses , +above. If +.Va section +does not exist in the input file, a warning will be issued, unless +.Op --no-change-warnings +is used. +.Pp +.It --change-section-lma Va section{=,+,-} Va val +Set or change the LMA address of the named +.Va section . +The LMA address is the address where the section will be loaded into memory +at program load time. Normally this is the same as the VMA address, which +is the address of the section at program run time, but on some systems, especially +those where a program is held in ROM, the two can be different. If +.Li = +is used, the section address is set to +.Va val . +Otherwise, +.Va val +is added to or subtracted from the section address. See the comments under +.Op --change-addresses , +above. If +.Va section +does not exist in the input file, a warning will be issued, unless +.Op --no-change-warnings +is used. +.Pp +.It --change-section-vma Va section{=,+,-} Va val +Set or change the VMA address of the named +.Va section . +The VMA address is the address where the section will be located once the +program has started executing. Normally this is the same as the LMA address, +which is the address where the section will be loaded into memory, but on +some systems, especially those where a program is held in ROM, the two can +be different. If +.Li = +is used, the section address is set to +.Va val . +Otherwise, +.Va val +is added to or subtracted from the section address. See the comments under +.Op --change-addresses , +above. If +.Va section +does not exist in the input file, a warning will be issued, unless +.Op --no-change-warnings +is used. +.Pp +.It --change-warnings +.It --adjust-warnings +If +.Op --change-section-address +or +.Op --change-section-lma +or +.Op --change-section-vma +is used, and the named section does not exist, issue a warning. This is the +default. +.Pp +.It --no-change-warnings +.It --no-adjust-warnings +Do not issue a warning if +.Op --change-section-address +or +.Op --adjust-section-lma +or +.Op --adjust-section-vma +is used, even if the named section does not exist. +.Pp +.It --set-section-flags Va section= Va flags +Set the flags for the named section. The +.Va flags +argument is a comma separated string of flag names. The recognized names are +.Li alloc , +.Li contents , +.Li load , +.Li noload , +.Li readonly , +.Li code , +.Li data , +.Li rom , +.Li share , +and +.Li debug . +You can set the +.Li contents +flag for a section which does not have contents, but it is not meaningful +to clear the +.Li contents +flag of a section which does have contents--just remove the section instead. +Not all flags are meaningful for all object file formats. +.Pp +.It --add-section Va sectionname= Va filename +Add a new section named +.Va sectionname +while copying the file. The contents of the new section are taken from the +file +.Va filename . +The size of the section will be the size of the file. This option only works +on file formats which can support sections with arbitrary names. +.Pp +.It --rename-section Va oldname= Va newname[, Va flags] +Rename a section from +.Va oldname +to +.Va newname , +optionally changing the section's flags to +.Va flags +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. +.Pp +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: +.Pp +.Bd -literal -offset indent + 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> +.Ed +.Pp +.It --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 +.Xr objcopy +to change the leading character of every symbol when it converts between object +file formats. If the object file formats use the same leading character, this +option has no effect. Otherwise, it will add a character, or remove a character, +or change a character, as appropriate. +.Pp +.It --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 +.Op --change-leading-char +because it always changes the symbol name when appropriate, regardless of +the object file format of the output file. +.Pp +.It --reverse-bytes= Va 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. +.Pp +This option is used typically in generating ROM 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 +CPU byte order. Depending on the programming model, the endianness of the +ROM may need to be modified. +.Pp +Consider a simple file with a section containing the following eight bytes: +.Li 12345678 . +.Pp +Using +.Li --reverse-bytes=2 +for the above example, the bytes in the output file would be ordered +.Li 21436587 . +.Pp +Using +.Li --reverse-bytes=4 +for the above example, the bytes in the output file would be ordered +.Li 43218765 . +.Pp +By using +.Li --reverse-bytes=2 +for the above example, followed by +.Li --reverse-bytes=4 +on the output file, the bytes in the second output file would be ordered +.Li 34127856 . +.Pp +.It --srec-len= Va ival +Meaningful only for srec output. Set the maximum length of the Srecords being +produced to +.Va ival . +This length covers both address, data and crc fields. +.Pp +.It --srec-forceS3 +Meaningful only for srec output. Avoid generation of S1/S2 records, creating +S3-only record format. +.Pp +.It --redefine-sym Va old= Va new +Change the name of a symbol +.Va old , +to +.Va new . +This can be useful when one is trying link two things together for which you +have no source, and there are name collisions. +.Pp +.It --redefine-syms= Va filename +Apply +.Op --redefine-sym +to each symbol pair " +.Va old +.Va new " +listed in the file +.Va filename . +.Va filename +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. +.Pp +.It --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 +.Op -R +option to the linker. This option is only effective when using an object file +format which supports weak symbols. +.Pp +.It --keep-symbols= Va filename +Apply +.Op --keep-symbol +option to each symbol listed in the file +.Va filename . +.Va filename +is simply a flat file, with one symbol name per line. Line comments may be +introduced by the hash character. This option may be given more than once. +.Pp +.It --strip-symbols= Va filename +Apply +.Op --strip-symbol +option to each symbol listed in the file +.Va filename . +.Va filename +is simply a flat file, with one symbol name per line. Line comments may be +introduced by the hash character. This option may be given more than once. +.Pp +.It --strip-unneeded-symbols= Va filename +Apply +.Op --strip-unneeded-symbol +option to each symbol listed in the file +.Va filename . +.Va filename +is simply a flat file, with one symbol name per line. Line comments may be +introduced by the hash character. This option may be given more than once. +.Pp +.It --keep-global-symbols= Va filename +Apply +.Op --keep-global-symbol +option to each symbol listed in the file +.Va filename . +.Va filename +is simply a flat file, with one symbol name per line. Line comments may be +introduced by the hash character. This option may be given more than once. +.Pp +.It --localize-symbols= Va filename +Apply +.Op --localize-symbol +option to each symbol listed in the file +.Va filename . +.Va filename +is simply a flat file, with one symbol name per line. Line comments may be +introduced by the hash character. This option may be given more than once. +.Pp +.It --globalize-symbols= Va filename +Apply +.Op --globalize-symbol +option to each symbol listed in the file +.Va filename . +.Va filename +is simply a flat file, with one symbol name per line. Line comments may be +introduced by the hash character. This option may be given more than once. +.Pp +.It --weaken-symbols= Va filename +Apply +.Op --weaken-symbol +option to each symbol listed in the file +.Va filename . +.Va filename +is simply a flat file, with one symbol name per line. Line comments may be +introduced by the hash character. This option may be given more than once. +.Pp +.It --alt-machine-code= Va index +If the output architecture has alternate machine codes, use the +.Va index +th 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 ELF based architectures +if the +.Va index +alternative does not exist then the value is treated as an absolute number +to be stored in the e_machine field of the ELF header. +.Pp +.It --writable-text +Mark the output text as writable. This option isn't meaningful for all object +file formats. +.Pp +.It --readonly-text +Make the output text write protected. This option isn't meaningful for all +object file formats. +.Pp +.It --pure +Mark the output file as demand paged. This option isn't meaningful for all +object file formats. +.Pp +.It --impure +Mark the output file as impure. This option isn't meaningful for all object +file formats. +.Pp +.It --prefix-symbols= Va string +Prefix all symbols in the output file with +.Va string . +.Pp +.It --prefix-sections= Va string +Prefix all section names in the output file with +.Va string . +.Pp +.It --prefix-alloc-sections= Va string +Prefix all the names of all allocated sections in the output file with +.Va string . +.Pp +.It --add-GNU-debuglink= Va path-to-file +Creates a .GNU_debuglink section which contains a reference to +.Va path-to-file +and adds it to the output file. +.Pp +.It --keep-file-symbols +When stripping a file, perhaps with +.Op --strip-debug +or +.Op --strip-unneeded , +retain any symbols specifying source file names, which would otherwise get +stripped. +.Pp +.It --only-keep-debug +Strip a file, removing contents of any sections that would not be stripped +by +.Op --strip-debug +and leaving the debugging sections intact. In ELF files, this preserves all +note sections in the output. +.Pp +The intention is that this option will be used in conjunction with +.Op --add-GNU-debuglink +to create a two part executable. One a stripped binary which will occupy less +space in RAM 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: +.Pp +.Bl -enum +.It +Link the executable as normal. Assuming that is is called +.Li foo +then... +.It +Run +.Li objcopy --only-keep-debug foo foo.dbg +to +create a file containing the debugging info. +.It +Run +.Li objcopy --strip-debug foo +to create a +stripped executable. +.It +Run +.Li objcopy --add-GNU-debuglink=foo.dbg foo +to add a link to the debugging info into the stripped executable. +.El +.Pp +Note - the choice of +.Li .dbg +as an extension for the debug info file is arbitrary. Also the +.Li --only-keep-debug +step is optional. You could instead do this: +.Pp +.Bl -enum +.It +Link the executable as normal. +.It +Copy +.Li foo +to +.Li foo.full +.It +Run +.Li objcopy --strip-debug foo +.It +Run +.Li objcopy --add-GNU-debuglink=foo.full foo +.El +.Pp +i.e., the file pointed to by the +.Op --add-GNU-debuglink +can be the full executable. It does not have to be a file created by the +.Op --only-keep-debug +switch. +.Pp +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. +.Pp +.It --extract-symbol +Keep the file's section flags and symbols but remove all section data. Specifically, +the option: +.Pp +.Bl -bullet +.It +sets the virtual and load addresses of every section to zero; +.It +removes the contents of all sections; +.It +sets the size of every section to zero; and +.It +sets the file's start address to zero. +.El +.Pp +This option is used to build a +.Pa .sym +file for a VxWorks kernel. It can also be a useful way of reducing the size +of a +.Op --just-symbols +linker input file. +.Pp +.It -V +.It --version +Show the version number of +.Xr objcopy . +.Pp +.It -v +.It --verbose +Verbose output: list all object files modified. In the case of archives, +.Li objcopy -V +lists all members of the archive. +.Pp +.It --help +Show a summary of the options to +.Xr objcopy . +.Pp +.It --info +Display a list showing all architectures and object formats available. +.El +.Pp +.Sh objdump +.Bd -literal -offset indent +objdump [-a|--archive-headers] + [-b bfdname|--target=bfdname] + [-C|--demangle[=style] ] + [-d|--disassemble] + [-D|--disassemble-all] + [-z|--disassemble-zeroes] + [-EB|-EL|--endian={big | little }] + [-f|--file-headers] + [--file-start-context] + [-g|--debugging] + [-e|--debugging-tags] + [-h|--section-headers|--headers] + [-i|--info] + [-j section|--section=section] + [-l|--line-numbers] + [-S|--source] + [-m machine|--architecture=machine] + [-M options|--disassembler-options=options] + [-p|--private-headers] + [-r|--reloc] + [-R|--dynamic-reloc] + [-s|--full-contents] + [-W|--dwarf] + [-G|--stabs] + [-t|--syms] + [-T|--dynamic-syms] + [-x|--all-headers] + [-w|--wide] + [--start-address=address] + [--stop-address=address] + [--prefix-addresses] + [--[no-]show-raw-insn] + [--adjust-vma=offset] + [--special-syms] + [-V|--version] + [-H|--help] + objfile... +.Ed +.Pp +.Xr objdump +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 +.Va objfile +\&...are the object files to be examined. When you specify archives, +.Xr objdump +shows information on each of the member object files. +.Pp +The long and short forms of options, shown here as alternatives, are equivalent. +At least one option from the list +.Op -a,-d,-D,-e,-f,-g,-G,-h,-H,-p,-r,-R,-s,-S,-t,-T,-V,-x +must be given. +.Pp +.Bl -tag -width Ds +.It -a +.It --archive-header +If any of the +.Va objfile +files are archives, display the archive header information (in a format similar +to +.Li ls -l ) . +Besides the information you could list with +.Li ar tv , +.Li objdump -a +shows the object file format of each archive member. +.Pp +.It --adjust-vma= Va offset +When dumping information, first add +.Va offset +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. +.Pp +.It -b Va bfdname +.It --target= Va bfdname +Specify that the object-code format for the object files is +.Va bfdname . +This option may not be necessary; +.Va objdump +can automatically recognize many formats. +.Pp +For example, +.Bd -literal -offset indent +objdump -b oasys -m vax -h fu.o +.Ed +displays summary information from the section headers ( +.Op -h ) +of +.Pa fu.o , +which is explicitly identified ( +.Op -m ) +as a VAX object file in the format produced by Oasys compilers. You can list +the formats available with the +.Op -i +option.See Section +.Dq Target Selection , +for more information. +.Pp +.It -C +.It --demangle[= Va style] +Decode ( +.Em demangle ) +low-level symbol names into user-level names. Besides removing any initial +underscore prepended by the system, this makes C++ function names readable. +Different compilers have different mangling styles. The optional demangling +style argument can be used to choose an appropriate demangling style for your +compiler.See Section +.Dq c++filt , +for more information on demangling. +.Pp +.It -g +.It --debugging +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 +.Xr readelf -w . +See Section.Dq readelf . +.Pp +.It -e +.It --debugging-tags +Like +.Op -g , +but the information is generated in a format compatible with ctags tool. +.Pp +.It -d +.It --disassemble +Display the assembler mnemonics for the machine instructions from +.Va objfile . +This option only disassembles those sections which are expected to contain +instructions. +.Pp +.It -D +.It --disassemble-all +Like +.Op -d , +but disassemble the contents of all sections, not just those expected to contain +instructions. +.Pp +.It --prefix-addresses +When disassembling, print the complete address on each line. This is the older +disassembly format. +.Pp +.It -EB +.It -EL +.It --endian={big|little} +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. +.Pp +.It -f +.It --file-headers +Display summary information from the overall header of each of the +.Va objfile +files. +.Pp +.It --file-start-context +Specify that when displaying interlisted source code/disassembly (assumes +.Op -S ) +from a file that has not yet been displayed, extend the context to the start +of the file. +.Pp +.It -h +.It --section-headers +.It --headers +Display summary information from the section headers of the object file. +.Pp +File segments may be relocated to nonstandard addresses, for example by using +the +.Op -Ttext , +.Op -Tdata , +or +.Op -Tbss +options to +.Xr ld . +However, some object file formats, such as a.out, do not store the starting +address of the file segments. In those situations, although +.Xr ld +relocates the sections correctly, using +.Li objdump -h +to list the file section headers cannot show the correct addresses. Instead, +it shows the usual addresses, which are implicit for the target. +.Pp +.It -H +.It --help +Print a summary of the options to +.Xr objdump +and exit. +.Pp +.It -i +.It --info +Display a list showing all architectures and object formats available for +specification with +.Op -b +or +.Op -m . +.Pp +.It -j Va name +.It --section= Va name +Display information only for section +.Va name . +.Pp +.It -l +.It --line-numbers +Label the display (using debugging information) with the filename and source +line numbers corresponding to the object code or relocs shown. Only useful +with +.Op -d , +.Op -D , +or +.Op -r . +.Pp +.It -m Va machine +.It --architecture= Va machine +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 +.Op -i +option. +.Pp +.It -M Va options +.It --disassembler-options= Va options +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 +.Op -M +options can be used or can be placed together into a comma separated list. +.Pp +If the target is an ARM architecture then this switch can be used to select +which register name set is used during disassembler. Specifying +.Op -M reg-names-std +(the default) will select the register names as used in ARM's instruction +set documentation, but with register 13 called 'sp', register 14 called 'lr' +and register 15 called 'pc'. Specifying +.Op -M reg-names-apcs +will select the name set used by the ARM Procedure Call Standard, whilst specifying +.Op -M reg-names-raw +will just use +.Li r +followed by the register number. +.Pp +There are also two variants on the APCS register naming scheme enabled by +.Op -M reg-names-atpcs +and +.Op -M reg-names-special-atpcs +which use the ARM/Thumb Procedure Call Standard naming conventions. (Either +with the normal register names or the special register names). +.Pp +This option can also be used for ARM architectures to force the disassembler +to interpret all instructions as Thumb instructions by using the switch +.Op --disassembler-options=force-thumb . +This can be useful when attempting to disassemble thumb code produced by other +compilers. +.Pp +For the x86, some of the options duplicate functions of the +.Op -m +switch, but allow finer grained control. Multiple selections from the following +may be specified as a comma separated string. +.Op x86-64 , +.Op i386 +and +.Op i8086 +select disassembly for the given architecture. +.Op intel +and +.Op att +select between intel syntax mode and AT&T syntax mode. +.Op addr64 , +.Op addr32 , +.Op addr16 , +.Op data32 +and +.Op data16 +specify the default address size and operand size. These four options will +be overridden if +.Op x86-64 , +.Op i386 +or +.Op i8086 +appear later in the option string. Lastly, +.Op suffix , +when in AT&T mode, instructs the disassembler to print a mnemonic suffix even +when the suffix could be inferred by the operands. +.Pp +For PPC, +.Op booke , +.Op booke32 +and +.Op booke64 +select disassembly of BookE instructions. +.Op 32 +and +.Op 64 +select PowerPC and PowerPC64 disassembly, respectively. +.Op e300 +selects disassembly for the e300 family. +.Op 440 +selects disassembly for the PowerPC 440. +.Pp +For MIPS, 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: +.Pp +.Bl -tag -width Ds +.It 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. +.Pp +.It gpr-names= Va ABI +Print GPR (general-purpose register) names as appropriate for the specified +ABI. By default, GPR names are selected according to the ABI of the binary +being disassembled. +.Pp +.It fpr-names= Va ABI +Print FPR (floating-point register) names as appropriate for the specified +ABI. By default, FPR numbers are printed rather than names. +.Pp +.It cp0-names= Va ARCH +Print CP0 (system control coprocessor; coprocessor 0) register names as appropriate +for the CPU or architecture specified by +.Va ARCH . +By default, CP0 register names are selected according to the architecture +and CPU of the binary being disassembled. +.Pp +.It hwr-names= Va ARCH +Print HWR (hardware register, used by the +.Li rdhwr +instruction) names as appropriate for the CPU or architecture specified by +.Va ARCH . +By default, HWR names are selected according to the architecture and CPU of +the binary being disassembled. +.Pp +.It reg-names= Va ABI +Print GPR and FPR names as appropriate for the selected ABI. +.Pp +.It reg-names= Va ARCH +Print CPU-specific register names (CP0 register and HWR names) as appropriate +for the selected CPU or architecture. +.El +.Pp +For any of the options listed above, +.Va ABI +or +.Va ARCH +may be specified as +.Li numeric +to have numbers printed rather than names, for the selected types of registers. +You can list the available values of +.Va ABI +and +.Va ARCH +using the +.Op --help +option. +.Pp +For VAX, you can specify function entry addresses with +.Op -M entry:0xf00ba . +You can use this multiple times to properly disassemble VAX binary files that +don't contain symbol tables (like ROM dumps). In these cases, the function +entry mask would otherwise be decoded as VAX instructions, which would probably +lead the rest of the function being wrongly disassembled. +.Pp +.It -p +.It --private-headers +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. +.Pp +.It -r +.It --reloc +Print the relocation entries of the file. If used with +.Op -d +or +.Op -D , +the relocations are printed interspersed with the disassembly. +.Pp +.It -R +.It --dynamic-reloc +Print the dynamic relocation entries of the file. This is only meaningful +for dynamic objects, such as certain types of shared libraries. +.Pp +.It -s +.It --full-contents +Display the full contents of any sections requested. By default all non-empty +sections are displayed. +.Pp +.It -S +.It --source +Display source code intermixed with disassembly, if possible. Implies +.Op -d . +.Pp +.It --show-raw-insn +When disassembling instructions, print the instruction in hex as well as in +symbolic form. This is the default except when +.Op --prefix-addresses +is used. +.Pp +.It --no-show-raw-insn +When disassembling instructions, do not print the instruction bytes. This +is the default when +.Op --prefix-addresses +is used. +.Pp +.It -W +.It --dwarf +Displays the contents of the DWARF debug sections in the file, if any are +present. +.Pp +.It -G +.It --stabs +Display the full contents of any sections requested. Display the contents +of the .stab and .stab.index and .stab.excl sections from an ELF file. This +is only useful on systems (such as Solaris 2.0) in which +.Li .stab +debugging symbol-table entries are carried in an ELF section. In most other +file formats, debugging symbol-table entries are interleaved with linkage +symbols, and are visible in the +.Op --syms +output. For more information on stabs symbols, see Top,Stabs,Stabs Overview,stabs.info, +The \(lqstabs\(rq debug format. +.Pp +.It --start-address= Va address +Start displaying data at the specified address. This affects the output of +the +.Op -d , +.Op -r +and +.Op -s +options. +.Pp +.It --stop-address= Va address +Stop displaying data at the specified address. This affects the output of +the +.Op -d , +.Op -r +and +.Op -s +options. +.Pp +.It -t +.It --syms +Print the symbol table entries of the file. This is similar to the information +provided by the +.Li nm +program. +.Pp +.It -T +.It --dynamic-syms +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 +.Li nm +program when given the +.Op -D +( +.Op --dynamic ) +option. +.Pp +.It --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. +.Pp +.It -V +.It --version +Print the version number of +.Xr objdump +and exit. +.Pp +.It -x +.It --all-headers +Display all available header information, including the symbol table and relocation +entries. Using +.Op -x +is equivalent to specifying all of +.Op -a -f -h -p -r -t . +.Pp +.It -w +.It --wide +Format some lines for output devices that have more than 80 columns. Also +do not truncate symbol names when they are displayed. +.Pp +.It -z +.It --disassemble-zeroes +Normally the disassembly output will skip blocks of zeroes. This option directs +the disassembler to disassemble those blocks, just like any other data. +.El +.Pp +.Sh ranlib +.Bd -literal -offset indent +ranlib [-vV] archive +.Ed +.Pp +.Xr ranlib +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 +.Li nm -s +or +.Li nm --print-armap +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 GNU +.Xr ranlib +program is another form of GNU +.Xr ar ; +running +.Xr ranlib +is completely equivalent to executing +.Li ar -s . +See Section.Dq ar . +.Pp +.Bl -tag -width Ds +.It -v +.It -V +.It --version +Show the version number of +.Xr ranlib . +.El +.Pp +.Sh size +.Bd -literal -offset indent +size [-A|-B|--format=compatibility] + [--help] + [-d|-o|-x|--radix=number] + [-t|--totals] + [--target=bfdname] [-V|--version] + [objfile...] +.Ed +.Pp +The GNU +.Xr size +utility lists the section sizes---and the total size---for each of the object +or archive files +.Va objfile +in its argument list. By default, one line of output is generated for each +object file or each module in an archive. +.Pp +.Va objfile +\&...are the object files to be examined. If none are specified, the file +.Li a.out +will be used. +.Pp +The command line options have the following meanings: +.Pp +.Bl -tag -width Ds +.It -A +.It -B +.It --format= Va compatibility +Using one of these options, you can choose whether the output from GNU +.Xr size +resembles output from System V +.Xr size +(using +.Op -A , +or +.Op --format=sysv ) , +or Berkeley +.Xr size +(using +.Op -B , +or +.Op --format=berkeley ) . +The default is the one-line format similar to Berkeley's. +.Pp +Here is an example of the Berkeley (default) format of output from +.Xr size : +.Bd -literal -offset indent +$ size --format=Berkeley ranlib size +text data bss dec hex filename +294880 81920 11592 388392 5ed28 ranlib +294880 81920 11888 388688 5ee50 size +.Ed +.Pp +This is the same data, but displayed closer to System V conventions: +.Pp +.Bd -literal -offset indent +$ 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 +.Ed +.Pp +.It --help +Show a summary of acceptable arguments and options. +.Pp +.It -d +.It -o +.It -x +.It --radix= Va number +Using one of these options, you can control whether the size of each section +is given in decimal ( +.Op -d , +or +.Op --radix=10 ) ; +octal ( +.Op -o , +or +.Op --radix=8 ) ; +or hexadecimal ( +.Op -x , +or +.Op --radix=16 ) . +In +.Op --radix= Va number , +only the three values (8, 10, 16) are supported. The total size is always +given in two radices; decimal and hexadecimal for +.Op -d +or +.Op -x +output, or octal and hexadecimal if you're using +.Op -o . +.Pp +.It -t +.It --totals +Show totals of all objects listed (Berkeley format listing mode only). +.Pp +.It --target= Va bfdname +Specify that the object-code format for +.Va objfile +is +.Va bfdname . +This option may not be necessary; +.Xr size +can automatically recognize many formats.See Section +.Dq Target Selection , +for more information. +.Pp +.It -V +.It --version +Display the version number of +.Xr size . +.El +.Pp +.Sh strings +.Bd -literal -offset indent +strings [-afov] [-min-len] + [-n min-len] [--bytes=min-len] + [-t radix] [--radix=radix] + [-e encoding] [--encoding=encoding] + [-] [--all] [--print-file-name] + [-T bfdname] [--target=bfdname] + [--help] [--version] file... +.Ed +.Pp +For each +.Va file +given, GNU +.Xr strings +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 +.Xr strings +is mainly useful for determining the contents of non-text files. +.Pp +.Bl -tag -width Ds +.It -a +.It --all +.It - +Do not scan only the initialized and loaded sections of object files; scan +the whole files. +.Pp +.It -f +.It --print-file-name +Print the name of the file before each string. +.Pp +.It --help +Print a summary of the program usage on the standard output and exit. +.Pp +.It - Va min-len +.It -n Va min-len +.It --bytes= Va min-len +Print sequences of characters that are at least +.Va min-len +characters long, instead of the default 4. +.Pp +.It -o +Like +.Li -t o . +Some other versions of +.Xr strings +have +.Op -o +act like +.Li -t d +instead. Since we can not be compatible with both ways, we simply chose one. +.Pp +.It -t Va radix +.It --radix= Va radix +Print the offset within the file before each string. The single character +argument specifies the radix of the offset--- +.Li o +for octal, +.Li x +for hexadecimal, or +.Li d +for decimal. +.Pp +.It -e Va encoding +.It --encoding= Va encoding +Select the character encoding of the strings that are to be found. Possible +values for +.Va encoding +are: +.Li s += single-7-bit-byte characters (ASCII, ISO 8859, etc., default), +.Li S += single-8-bit-byte characters, +.Li b += 16-bit bigendian, +.Li l += 16-bit littleendian, +.Li B += 32-bit bigendian, +.Li L += 32-bit littleendian. Useful for finding wide character strings. +.Pp +.It -T Va bfdname +.It --target= Va bfdname +Specify an object code format other than your system's default format.See Section +.Dq Target Selection , +for more information. +.Pp +.It -v +.It --version +Print the program version number on the standard output and exit. +.El +.Pp +.Sh strip +.Bd -literal -offset indent +strip [-F bfdname |--target=bfdname] + [-I bfdname |--input-target=bfdname] + [-O bfdname |--output-target=bfdname] + [-s|--strip-all] + [-S|-g|-d|--strip-debug] + [-K symbolname |--keep-symbol=symbolname] + [-N symbolname |--strip-symbol=symbolname] + [-w|--wildcard] + [-x|--discard-all] [-X |--discard-locals] + [-R sectionname |--remove-section=sectionname] + [-o file] [-p|--preserve-dates] + [--keep-file-symbols] + [--only-keep-debug] + [-v |--verbose] [-V|--version] + [--help] [--info] + objfile... +.Ed +.Pp +GNU +.Xr strip +discards all symbols from object files +.Va objfile . +The list of object files may include archives. At least one object file must +be given. +.Pp +.Xr strip +modifies the files named in its argument, rather than writing modified copies +under different names. +.Pp +.Bl -tag -width Ds +.It -F Va bfdname +.It --target= Va bfdname +Treat the original +.Va objfile +as a file with the object code format +.Va bfdname , +and rewrite it in the same format.See Section +.Dq Target Selection , +for more information. +.Pp +.It --help +Show a summary of the options to +.Xr strip +and exit. +.Pp +.It --info +Display a list showing all architectures and object formats available. +.Pp +.It -I Va bfdname +.It --input-target= Va bfdname +Treat the original +.Va objfile +as a file with the object code format +.Va bfdname . +See Section.Dq Target Selection , +for more information. +.Pp +.It -O Va bfdname +.It --output-target= Va bfdname +Replace +.Va objfile +with a file in the output format +.Va bfdname . +See Section.Dq Target Selection , +for more information. +.Pp +.It -R Va sectionname +.It --remove-section= Va sectionname +Remove any section named +.Va sectionname +from the output file. This option may be given more than once. Note that using +this option inappropriately may make the output file unusable. +.Pp +.It -s +.It --strip-all +Remove all symbols. +.Pp +.It -g +.It -S +.It -d +.It --strip-debug +Remove debugging symbols only. +.Pp +.It --strip-unneeded +Remove all symbols that are not needed for relocation processing. +.Pp +.It -K Va symbolname +.It --keep-symbol= Va symbolname +When stripping symbols, keep symbol +.Va symbolname +even if it would normally be stripped. This option may be given more than +once. +.Pp +.It -N Va symbolname +.It --strip-symbol= Va symbolname +Remove symbol +.Va symbolname +from the source file. This option may be given more than once, and may be +combined with strip options other than +.Op -K . +.Pp +.It -o Va file +Put the stripped output in +.Va file , +rather than replacing the existing file. When this argument is used, only +one +.Va objfile +argument may be specified. +.Pp +.It -p +.It --preserve-dates +Preserve the access and modification dates of the file. +.Pp +.It -w +.It --wildcard +Permit regular expressions in +.Va symbolname +s 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: +.Pp +.Bd -literal -offset indent + -w -K !foo -K fo* +.Ed +.Pp +would cause strip to only keep symbols that start with the letters \(lqfo\(rq, but +to discard the symbol \(lqfoo\(rq. +.Pp +.It -x +.It --discard-all +Remove non-global symbols. +.Pp +.It -X +.It --discard-locals +Remove compiler-generated local symbols. (These usually start with +.Li L +or +.Li . . ) +.Pp +.It --keep-file-symbols +When stripping a file, perhaps with +.Op --strip-debug +or +.Op --strip-unneeded , +retain any symbols specifying source file names, which would otherwise get +stripped. +.Pp +.It --only-keep-debug +Strip a file, removing contents of any sections that would not be stripped +by +.Op --strip-debug +and leaving the debugging sections intact. In ELF files, this preserves all +note sections in the output. +.Pp +The intention is that this option will be used in conjunction with +.Op --add-GNU-debuglink +to create a two part executable. One a stripped binary which will occupy less +space in RAM 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: +.Pp +.Bl -enum +.It +Link the executable as normal. Assuming that is is called +.Li foo +then... +.It +Run +.Li objcopy --only-keep-debug foo foo.dbg +to +create a file containing the debugging info. +.It +Run +.Li objcopy --strip-debug foo +to create a +stripped executable. +.It +Run +.Li objcopy --add-GNU-debuglink=foo.dbg foo +to add a link to the debugging info into the stripped executable. +.El +.Pp +Note - the choice of +.Li .dbg +as an extension for the debug info file is arbitrary. Also the +.Li --only-keep-debug +step is optional. You could instead do this: +.Pp +.Bl -enum +.It +Link the executable as normal. +.It +Copy +.Li foo +to +.Li foo.full +.It +Run +.Li strip --strip-debug foo +.It +Run +.Li objcopy --add-GNU-debuglink=foo.full foo +.El +.Pp +ie the file pointed to by the +.Op --add-GNU-debuglink +can be the full executable. It does not have to be a file created by the +.Op --only-keep-debug +switch. +.Pp +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. +.Pp +.It -V +.It --version +Show the version number for +.Xr strip . +.Pp +.It -v +.It --verbose +Verbose output: list all object files modified. In the case of archives, +.Li strip -v +lists all members of the archive. +.El +.Pp +.Sh c++filt +.Bd -literal -offset indent +c++filt [-_|--strip-underscores] + [-n|--no-strip-underscores] + [-p|--no-params] + [-t|--types] + [-i|--no-verbose] + [-s format|--format=format] + [--help] [--version] [symbol...] +.Ed +.Pp +The C++ and Java languages provide function overloading, which means that +you can write many functions with the same name, providing that each function +takes parameters of different types. In order to be able to distinguish these +similarly named functions C++ and Java encode them into a low-level assembler +name which uniquely identifies each different version. This process is known +as +.Em mangling . +The +.Xr c++filt +program does the inverse mapping: it decodes ( +.Em demangles ) +low-level names into user-level names so that they can be read. +.Pp +Every alphanumeric word (consisting of letters, digits, underscores, dollars, +or periods) seen in the input is a potential mangled name. If the name decodes +into a C++ name, the C++ name replaces the low-level name in the output, otherwise +the original word is output. In this way you can pass an entire assembler +source file, containing mangled names, through +.Xr c++filt +and see the same source file containing demangled names. +.Pp +You can also use +.Xr c++filt +to decipher individual symbols by passing them on the command line: +.Pp +.Bd -literal -offset indent +c++filt symbol +.Ed +.Pp +If no +.Va symbol +arguments are given, +.Xr c++filt +reads symbol names from the standard input instead. All the results are printed +on the standard output. The difference between reading names from the command +line versus reading names from the standard input is that command line arguments +are expected to be just mangled names and no checking is performed to separate +them from surrounding text. Thus for example: +.Pp +.Bd -literal -offset indent +c++filt -n _Z1fv +.Ed +.Pp +will work and demangle the name to \(lqf()\(rq whereas: +.Pp +.Bd -literal -offset indent +c++filt -n _Z1fv, +.Ed +.Pp +will not work. (Note the extra comma at the end of the mangled name which +makes it invalid). This command however will work: +.Pp +.Bd -literal -offset indent +echo _Z1fv, | c++filt -n +.Ed +.Pp +and will display \(lqf(),\(rq ie the demangled name followed by a trailing comma. +This behaviour is because when the names are read from the standard input +it is expected that they might be part of an assembler source file where there +might be extra, extraneous characters trailing after a mangled name. eg: +.Pp +.Bd -literal -offset indent + .type _Z1fv, @function +.Ed +.Pp +.Bl -tag -width Ds +.It -_ +.It --strip-underscores +On some systems, both the C and C++ compilers put an underscore in front of +every name. For example, the C name +.Li foo +gets the low-level name +.Li _foo . +This option removes the initial underscore. Whether +.Xr c++filt +removes the underscore by default is target dependent. +.Pp +.It -j +.It --java +Prints demangled names using Java syntax. The default is to use C++ syntax. +.Pp +.It -n +.It --no-strip-underscores +Do not remove the initial underscore. +.Pp +.It -p +.It --no-params +When demangling the name of a function, do not display the types of the function's +parameters. +.Pp +.It -t +.It --types +Attempt to demangle types as well as function names. This is disabled by default +since mangled types are normally only used internally in the compiler, and +they can be confused with non-mangled names. eg a function called \(lqa\(rq treated +as a mangled type name would be demangled to \(lqsigned char\(rq. +.Pp +.It -i +.It --no-verbose +Do not include implementation details (if any) in the demangled output. +.Pp +.It -s Va format +.It --format= Va format +.Xr c++filt +can decode various methods of mangling, used by different compilers. The argument +to this option selects which method it uses: +.Pp +.Bl -tag -width Ds +.It auto +Automatic selection based on executable (the default method) +.It GNU +the one used by the GNU C++ compiler (g++) +.It lucid +the one used by the Lucid compiler (lcc) +.It arm +the one specified by the C++ Annotated Reference Manual +.It hp +the one used by the HP compiler (aCC) +.It edg +the one used by the EDG compiler +.It GNU-v3 +the one used by the GNU C++ compiler (g++) with the V3 ABI. +.It java +the one used by the GNU Java compiler (gcj) +.It gnat +the one used by the GNU Ada compiler (GNAT). +.El +.Pp +.It --help +Print a summary of the options to +.Xr c++filt +and exit. +.Pp +.It --version +Print the version number of +.Xr c++filt +and exit. +.El +.Pp +.Qo +.Em Warning: +.Xr c++filt +is a new utility, and the details of its user interface are subject to change +in future releases. In particular, a command-line option may be required in +the future to decode a name passed as an argument on the command line; in +other words, +.Pp +.Bd -literal -offset indent +c++filt symbol +.Ed +.Pp +may in a future release become +.Pp +.Bd -literal -offset indent +c++filt option symbol +.Ed +.Qc +.Pp +.Sh addr2line +.Bd -literal -offset indent +addr2line [-b bfdname|--target=bfdname] + [-C|--demangle[=style]] + [-e filename|--exe=filename] + [-f|--functions] [-s|--basename] + [-i|--inlines] + [-j|--section=name] + [-H|--help] [-V|--version] + [addr addr ...] +.Ed +.Pp +.Xr addr2line +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 +.Op -e +option. The default is the file +.Pa a.out . +The section in the relocatable object to use is specified with the +.Op -j +option. +.Pp +.Xr addr2line +has two modes of operation. +.Pp +In the first, hexadecimal addresses are specified on the command line, and +.Xr addr2line +displays the file name and line number for each address. +.Pp +In the second, +.Xr addr2line +reads hexadecimal addresses from standard input, and prints the file name +and line number for each address on standard output. In this mode, +.Xr addr2line +may be used in a pipe to convert dynamically chosen addresses. +.Pp +The format of the output is +.Li FILENAME:LINENO . +The file name and line number for each address is printed on a separate line. +If the +.Xr -f +option is used, then each +.Li FILENAME:LINENO +line is preceded by a +.Li FUNCTIONNAME +line which is the name of the function containing the address. +.Pp +If the file name or function name can not be determined, +.Xr addr2line +will print two question marks in their place. If the line number can not be +determined, +.Xr addr2line +will print 0. +.Pp +The long and short forms of options, shown here as alternatives, are equivalent. +.Pp +.Bl -tag -width Ds +.It -b Va bfdname +.It --target= Va bfdname +Specify that the object-code format for the object files is +.Va bfdname . +.Pp +.It -C +.It --demangle[= Va style] +Decode ( +.Em demangle ) +low-level symbol names into user-level names. Besides removing any initial +underscore prepended by the system, this makes C++ function names readable. +Different compilers have different mangling styles. The optional demangling +style argument can be used to choose an appropriate demangling style for your +compiler.See Section +.Dq c++filt , +for more information on demangling. +.Pp +.It -e Va filename +.It --exe= Va filename +Specify the name of the executable for which addresses should be translated. +The default file is +.Pa a.out . +.Pp +.It -f +.It --functions +Display function names as well as file and line number information. +.Pp +.It -s +.It --basenames +Display only the base of each file name. +.Pp +.It -i +.It --inlines +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 +.Li main +inlines +.Li callee1 +which inlines +.Li callee2 , +and address is from +.Li callee2 , +the source information for +.Li callee1 +and +.Li main +will also be printed. +.Pp +.It -j +.It --section +Read offsets relative to the specified section instead of absolute addresses. +.El +.Pp +.Sh nlmconv +.Xr nlmconv +converts a relocatable object file into a NetWare Loadable Module. +.Pp +.Qo +.Em Warning: +.Xr nlmconv +is not always built as part of the binary utilities, since it is only useful +for NLM targets. +.Qc +.Pp +.Bd -literal -offset indent +nlmconv [-I bfdname|--input-target=bfdname] + [-O bfdname|--output-target=bfdname] + [-T headerfile|--header-file=headerfile] + [-d|--debug] [-l linker|--linker=linker] + [-h|--help] [-V|--version] + infile outfile +.Ed +.Pp +.Xr nlmconv +converts the relocatable +.Li i386 +object file +.Va infile +into the NetWare Loadable Module +.Va outfile , +optionally reading +.Va headerfile +for NLM header information. For instructions on writing the NLM command file +language used in header files, see the +.Li linkers +section, +.Li NLMLINK +in particular, of the +.Em NLM Development and Tools Overview , +which is part of the NLM Software Developer's Kit (\(lqNLM SDK\(rq), available from +Novell, Inc. +.Xr nlmconv +uses the GNU Binary File Descriptor library to read +.Va infile ; +see BFD,,BFD,ld.info,Using LD, for more information. +.Pp +.Xr nlmconv +can perform a link step. In other words, you can list more than one object +file for input if you list them in the definitions file (rather than simply +specifying one input file on the command line). In this case, +.Xr nlmconv +calls the linker for you. +.Pp +.Bl -tag -width Ds +.It -I Va bfdname +.It --input-target= Va bfdname +Object format of the input file. +.Xr nlmconv +can usually determine the format of a given file (so no default is necessary).See Section +.Dq Target Selection , +for more information. +.Pp +.It -O Va bfdname +.It --output-target= Va bfdname +Object format of the output file. +.Xr nlmconv +infers the output format based on the input format, e.g. for a +.Li i386 +input file the output format is +.Li nlm32-i386 . +See Section.Dq Target Selection , +for more information. +.Pp +.It -T Va headerfile +.It --header-file= Va headerfile +Reads +.Va headerfile +for NLM header information. For instructions on writing the NLM command file +language used in header files, see see the +.Li linkers +section, of the +.Em NLM Development and Tools Overview , +which is part of the NLM Software Developer's Kit, available from Novell, +Inc. +.Pp +.It -d +.It --debug +Displays (on standard error) the linker command line used by +.Xr nlmconv . +.Pp +.It -l Va linker +.It --linker= Va linker +Use +.Va linker +for any linking. +.Va linker +can be an absolute or a relative pathname. +.Pp +.It -h +.It --help +Prints a usage summary. +.Pp +.It -V +.It --version +Prints the version number for +.Xr nlmconv . +.El +.Pp +.Sh windmc +.Xr windmc +may be used to generator Windows message resources. +.Pp +.Qo +.Em Warning: +.Xr windmc +is not always built as part of the binary utilities, since it is only useful +for Windows targets. +.Qc +.Pp +.Bd -literal -offset indent +windmc [options] input-file +.Ed +.Pp +.Xr windmc +reads message definitions from an input file (.mc) and translate them into +a set of output files. The output files may be of four kinds: +.Pp +.Bl -tag -width Ds +.It h +A C header file containing the message definitions. +.Pp +.It rc +A resource file compilable by the +.Xr windres +tool. +.Pp +.It bin +One or more binary files containing the resource data for a specific message +language. +.Pp +.It dbg +A C include file that maps message id's to their symbolic name. +.El +.Pp +The exact description of these different formats is available in documentation +from Microsoft. +.Pp +When +.Xr windmc +converts from the +.Li mc +format to the +.Li bin +format, +.Li rc , +.Li h , +and optional +.Li dbg +it is acting like the Windows Message Compiler. +.Pp +.Bl -tag -width Ds +.It -a +.It --ascii_in +Specifies that the input file specified is ANSI. This is the default behaviour. +.Pp +.It -A +.It --ascii_out +Specifies that messages in the output +.Li bin +files should be in ANSI format. +.Pp +.It -b +.It --binprefix +Specifies that +.Li bin +filenames should have to be prefixed by the basename of the source file. +.Pp +.It -c +.It --customflag +Sets the customer bit in all message id's. +.Pp +.It -C Va codepage +.It --codepage_in Va codepage +Sets the default codepage to be used to convert input file to UTF16. The default +is ocdepage 1252. +.Pp +.It -d +.It --decimal_values +Outputs the constants in the header file in decimal. Default is using hexadecimal +output. +.Pp +.It -e Va ext +.It --extension Va ext +The extension for the header file. The default is .h extension. +.Pp +.It -F Va target +.It --target Va target +Specify the BFD format to use for a bin file as output. This is a BFD target +name; you can use the +.Op --help +option to see a list of supported targets. Normally +.Xr windmc +will use the default format, which is the first one listed by the +.Op --help +option. Target Selection. +.Pp +.It -h Va path +.It --headerdir Va path +The target directory of the generated header file. The default is the current +directory. +.Pp +.It -H +.It --help +Displays a list of command line options and then exits. +.Pp +.It -m Va characters +.It --maxlength Va characters +Instructs +.Xr windmc +to generate a warning if the length of any message exceeds the number specified. +.Pp +.It -n +.It --nullterminate +Terminate message text in +.Li bin +files by zero. By default they are terminated by CR/LF. +.Pp +.It -o +.It --hresult_use +Not yet implemented. Instructs +.Li windmc +to generate an OLE2 header file, using HRESULT definitions. Status codes are +used if the flag is not specified. +.Pp +.It -O Va codepage +.It --codepage_out Va codepage +Sets the default codepage to be used to output text files. The default is +ocdepage 1252. +.Pp +.It -r Va path +.It --rcdir Va path +The target directory for the generated +.Li rc +script and the generated +.Li bin +files that the resource compiler script includes. The default is the current +directory. +.Pp +.It -u +.It --unicode_in +Specifies that the input file is UTF16. +.Pp +.It -U +.It --unicode_out +Specifies that messages in the output +.Li bin +file should be in UTF16 format. This is the default behaviour. +.Pp +.It -v +.It --verbose +Enable verbose mode. This tells you what the preprocessor is if you didn't +specify one. +.Pp +.It -V +.It --version +Prints the version number for +.Xr windres . +.Pp +.It -x Va path +.It --xdgb Va path +The path of the +.Li dbg +C include file that maps message id's to the symbolic name. No such file is +generated without specifying the switch. +.El +.Pp +.Sh windres +.Xr windres +may be used to manipulate Windows resources. +.Pp +.Qo +.Em Warning: +.Xr windres +is not always built as part of the binary utilities, since it is only useful +for Windows targets. +.Qc +.Pp +.Bd -literal -offset indent +windres [options] [input-file] [output-file] +.Ed +.Pp +.Xr windres +reads resources from an input file and copies them into an output file. Either +file may be in one of three formats: +.Pp +.Bl -tag -width Ds +.It rc +A text format read by the Resource Compiler. +.Pp +.It res +A binary format generated by the Resource Compiler. +.Pp +.It coff +A COFF object or executable. +.El +.Pp +The exact description of these different formats is available in documentation +from Microsoft. +.Pp +When +.Xr windres +converts from the +.Li rc +format to the +.Li res +format, it is acting like the Windows Resource Compiler. When +.Xr windres +converts from the +.Li res +format to the +.Li coff +format, it is acting like the Windows +.Li CVTRES +program. +.Pp +When +.Xr windres +generates an +.Li rc +file, the output is similar but not identical to the format expected for the +input. When an input +.Li rc +file refers to an external filename, an output +.Li rc +file will instead include the file contents. +.Pp +If the input or output format is not specified, +.Xr windres +will guess based on the file name, or, for the input file, the file contents. +A file with an extension of +.Pa .rc +will be treated as an +.Li rc +file, a file with an extension of +.Pa .res +will be treated as a +.Li res +file, and a file with an extension of +.Pa .o +or +.Pa .exe +will be treated as a +.Li coff +file. +.Pp +If no output file is specified, +.Xr windres +will print the resources in +.Li rc +format to standard output. +.Pp +The normal use is for you to write an +.Li rc +file, use +.Xr windres +to convert it to a COFF object file, and then link the COFF file into your +application. This will make the resources described in the +.Li rc +file available to Windows. +.Pp +.Bl -tag -width Ds +.It -i Va filename +.It --input Va filename +The name of the input file. If this option is not used, then +.Xr windres +will use the first non-option argument as the input file name. If there are +no non-option arguments, then +.Xr windres +will read from standard input. +.Xr windres +can not read a COFF file from standard input. +.Pp +.It -o Va filename +.It --output Va filename +The name of the output file. If this option is not used, then +.Xr windres +will use the first non-option argument, after any used for the input file +name, as the output file name. If there is no non-option argument, then +.Xr windres +will write to standard output. +.Xr windres +can not write a COFF file to standard output. Note, for compatibility with +.Xr rc +the option +.Op -fo +is also accepted, but its use is not recommended. +.Pp +.It -J Va format +.It --input-format Va format +The input format to read. +.Va format +may be +.Li res , +.Li rc , +or +.Li coff . +If no input format is specified, +.Xr windres +will guess, as described above. +.Pp +.It -O Va format +.It --output-format Va format +The output format to generate. +.Va format +may be +.Li res , +.Li rc , +or +.Li coff . +If no output format is specified, +.Xr windres +will guess, as described above. +.Pp +.It -F Va target +.It --target Va target +Specify the BFD format to use for a COFF file as input or output. This is +a BFD target name; you can use the +.Op --help +option to see a list of supported targets. Normally +.Xr windres +will use the default format, which is the first one listed by the +.Op --help +option. Target Selection. +.Pp +.It --preprocessor Va program +When +.Xr windres +reads an +.Li rc +file, it runs it through the C preprocessor first. This option may be used +to specify the preprocessor to use, including any leading arguments. The default +preprocessor argument is +.Li gcc -E -xc-header -DRC_INVOKED . +.Pp +.It -I Va directory +.It --include-dir Va directory +Specify an include directory to use when reading an +.Li rc +file. +.Xr windres +will pass this to the preprocessor as an +.Op -I +option. +.Xr windres +will also search this directory when looking for files named in the +.Li rc +file. If the argument passed to this command matches any of the supported +.Va formats +(as described in the +.Op -J +option), it will issue a deprecation warning, and behave just like the +.Op -J +option. New programs should not use this behaviour. If a directory happens +to match a +.Va format , +simple prefix it with +.Li ./ +to disable the backward compatibility. +.Pp +.It -D Va target +.It --define Va sym[= Va val] +Specify a +.Op -D +option to pass to the preprocessor when reading an +.Li rc +file. +.Pp +.It -U Va target +.It --undefine Va sym +Specify a +.Op -U +option to pass to the preprocessor when reading an +.Li rc +file. +.Pp +.It -r +Ignored for compatibility with rc. +.Pp +.It -v +Enable verbose mode. This tells you what the preprocessor is if you didn't +specify one. +.Pp +.It -c Va val +.It --codepage Va val +Specify the default codepage to use when reading an +.Li rc +file. +.Va val +should be a hexadecimal prefixed by +.Li 0x +or decimal codepage code. The valid range is from zero up to 0xffff, but the +validity of the codepage is host and configuration dependent. +.Pp +.It -l Va val +.It --language Va val +Specify the default language to use when reading an +.Li rc +file. +.Va val +should be a hexadecimal language code. The low eight bits are the language, +and the high eight bits are the sublanguage. +.Pp +.It --use-temp-file +Use a temporary file to instead of using popen to read the output of the preprocessor. +Use this option if the popen implementation is buggy on the host (eg., certain +non-English language versions of Windows 95 and Windows 98 are known to have +buggy popen where the output will instead go the console). +.Pp +.It --no-use-temp-file +Use popen, not a temporary file, to read the output of the preprocessor. This +is the default behaviour. +.Pp +.It -h +.It --help +Prints a usage summary. +.Pp +.It -V +.It --version +Prints the version number for +.Xr windres . +.Pp +.It --yydebug +If +.Xr windres +is compiled with +.Li YYDEBUG +defined as +.Li 1 , +this will turn on parser debugging. +.El +.Pp +.Sh dlltool +.Xr dlltool +is used to create the files needed to create dynamic link libraries (DLLs) +on systems which understand PE format image files such as Windows. A DLL contains +an export table which contains information that the runtime loader needs to +resolve references from a referencing program. +.Pp +The export table is generated by this program by reading in a +.Pa .def +file or scanning the +.Pa .a +and +.Pa .o +files which will be in the DLL. A +.Pa .o +file can contain information in special +.Li .drectve +sections with export information. +.Pp +.Qo +.Em Note: +.Xr dlltool +is not always built as part of the binary utilities, since it is only useful +for those targets which support DLLs. +.Qc +.Pp +.Bd -literal -offset indent +dlltool [-d|--input-def def-file-name] + [-b|--base-file base-file-name] + [-e|--output-exp exports-file-name] + [-z|--output-def def-file-name] + [-l|--output-lib library-file-name] + [--export-all-symbols] [--no-export-all-symbols] + [--exclude-symbols list] + [--no-default-excludes] + [-S|--as path-to-assembler] [-f|--as-flags options] + [-D|--dllname name] [-m|--machine machine] + [-a|--add-indirect] + [-U|--add-underscore] [--add-stdcall-underscore] + [-k|--kill-at] [-A|--add-stdcall-alias] + [-p|--ext-prefix-alias prefix] + [-x|--no-idata4] [-c|--no-idata5] [-i|--interwork] + [-n|--nodelete] [-t|--temp-prefix prefix] + [-v|--verbose] + [-h|--help] [-V|--version] + [object-file ...] +.Ed +.Pp +.Xr dlltool +reads its inputs, which can come from the +.Op -d +and +.Op -b +options as well as object files specified on the command line. It then processes +these inputs and if the +.Op -e +option has been specified it creates a exports file. If the +.Op -l +option has been specified it creates a library file and if the +.Op -z +option has been specified it creates a def file. Any or all of the +.Op -e , +.Op -l +and +.Op -z +options can be present in one invocation of dlltool. +.Pp +When creating a DLL, along with the source for the DLL, it is necessary to +have three other files. +.Xr dlltool +can help with the creation of these files. +.Pp +The first file is a +.Pa .def +file which specifies which functions are exported from the DLL, which functions +the DLL imports, and so on. This is a text file and can be created by hand, +or +.Xr dlltool +can be used to create it using the +.Op -z +option. In this case +.Xr dlltool +will scan the object files specified on its command line looking for those +functions which have been specially marked as being exported and put entries +for them in the +.Pa .def +file it creates. +.Pp +In order to mark a function as being exported from a DLL, it needs to have +an +.Op -export:<name_of_function> +entry in the +.Li .drectve +section of the object file. This can be done in C by using the asm() operator: +.Pp +.Bd -literal -offset indent + asm (".section .drectve"); + asm (".ascii \e"-export:my_func\e""); + + int my_func (void) { ... } +.Ed +.Pp +The second file needed for DLL creation is an exports file. This file is linked +with the object files that make up the body of the DLL and it handles the +interface between the DLL and the outside world. This is a binary file and +it can be created by giving the +.Op -e +option to +.Xr dlltool +when it is creating or reading in a +.Pa .def +file. +.Pp +The third file needed for DLL creation is the library file that programs will +link with in order to access the functions in the DLL. This file can be created +by giving the +.Op -l +option to dlltool when it is creating or reading in a +.Pa .def +file. +.Pp +.Xr dlltool +builds the library file by hand, but it builds the exports file by creating +temporary files containing assembler statements and then assembling these. +The +.Op -S +command line option can be used to specify the path to the assembler that +dlltool will use, and the +.Op -f +option can be used to pass specific flags to that assembler. The +.Op -n +can be used to prevent dlltool from deleting these temporary assembler files +when it is done, and if +.Op -n +is specified twice then this will prevent dlltool from deleting the temporary +object files it used to build the library. +.Pp +Here is an example of creating a DLL from a source file +.Li dll.c +and also creating a program (from an object file called +.Li program.o ) +that uses that DLL: +.Pp +.Bd -literal -offset indent + gcc -c dll.c + dlltool -e exports.o -l dll.lib dll.o + gcc dll.o exports.o -o dll.dll + gcc program.o dll.lib -o program +.Ed +.Pp +The command line options have the following meanings: +.Pp +.Bl -tag -width Ds +.It -d Va filename +.It --input-def Va filename +Specifies the name of a +.Pa .def +file to be read in and processed. +.Pp +.It -b Va filename +.It --base-file Va filename +Specifies the name of a base file to be read in and processed. The contents +of this file will be added to the relocation section in the exports file generated +by dlltool. +.Pp +.It -e Va filename +.It --output-exp Va filename +Specifies the name of the export file to be created by dlltool. +.Pp +.It -z Va filename +.It --output-def Va filename +Specifies the name of the +.Pa .def +file to be created by dlltool. +.Pp +.It -l Va filename +.It --output-lib Va filename +Specifies the name of the library file to be created by dlltool. +.Pp +.It --export-all-symbols +Treat all global and weak defined symbols found in the input object files +as symbols to be exported. There is a small list of symbols which are not +exported by default; see the +.Op --no-default-excludes +option. You may add to the list of symbols to not export by using the +.Op --exclude-symbols +option. +.Pp +.It --no-export-all-symbols +Only export symbols explicitly listed in an input +.Pa .def +file or in +.Li .drectve +sections in the input object files. This is the default behaviour. The +.Li .drectve +sections are created by +.Li dllexport +attributes in the source code. +.Pp +.It --exclude-symbols Va list +Do not export the symbols in +.Va list . +This is a list of symbol names separated by comma or colon characters. The +symbol names should not contain a leading underscore. This is only meaningful +when +.Op --export-all-symbols +is used. +.Pp +.It --no-default-excludes +When +.Op --export-all-symbols +is used, it will by default avoid exporting certain special symbols. The current +list of symbols to avoid exporting is +.Li DllMain@12 , +.Li DllEntryPoint@0 , +.Li impure_ptr . +You may use the +.Op --no-default-excludes +option to go ahead and export these special symbols. This is only meaningful +when +.Op --export-all-symbols +is used. +.Pp +.It -S Va path +.It --as Va path +Specifies the path, including the filename, of the assembler to be used to +create the exports file. +.Pp +.It -f Va options +.It --as-flags Va options +Specifies any specific command line options to be passed to the assembler +when building the exports file. This option will work even if the +.Op -S +option is not used. This option only takes one argument, and if it occurs +more than once on the command line, then later occurrences will override earlier +occurrences. So if it is necessary to pass multiple options to the assembler +they should be enclosed in double quotes. +.Pp +.It -D Va name +.It --dll-name Va name +Specifies the name to be stored in the +.Pa .def +file as the name of the DLL when the +.Op -e +option is used. If this option is not present, then the filename given to +the +.Op -e +option will be used as the name of the DLL. +.Pp +.It -m Va machine +.It -machine Va machine +Specifies the type of machine for which the library file should be built. +.Xr dlltool +has a built in default type, depending upon how it was created, but this option +can be used to override that. This is normally only useful when creating DLLs +for an ARM processor, when the contents of the DLL are actually encode using +Thumb instructions. +.Pp +.It -a +.It --add-indirect +Specifies that when +.Xr dlltool +is creating the exports file it should add a section which allows the exported +functions to be referenced without using the import library. Whatever the +hell that means! +.Pp +.It -U +.It --add-underscore +Specifies that when +.Xr dlltool +is creating the exports file it should prepend an underscore to the names +of +.Em all +exported symbols. +.Pp +.It --add-stdcall-underscore +Specifies that when +.Xr dlltool +is creating the exports file it should prepend an underscore to the names +of exported +.Em stdcall +functions. Variable names and non-stdcall function names are not modified. +This option is useful when creating GNU-compatible import libs for third party +DLLs that were built with MS-Windows tools. +.Pp +.It -k +.It --kill-at +Specifies that when +.Xr dlltool +is creating the exports file it should not append the string +.Li @ <number> . +These numbers are called ordinal numbers and they represent another way of +accessing the function in a DLL, other than by name. +.Pp +.It -A +.It --add-stdcall-alias +Specifies that when +.Xr dlltool +is creating the exports file it should add aliases for stdcall symbols without +.Li @ <number> +in addition to the symbols with +.Li @ <number> . +.Pp +.It -p +.It --ext-prefix-alias Va prefix +Causes +.Xr dlltool +to create external aliases for all DLL imports with the specified prefix. +The aliases are created for both external and import symbols with no leading +underscore. +.Pp +.It -x +.It --no-idata4 +Specifies that when +.Xr dlltool +is creating the exports and library files it should omit the +.Li .idata4 +section. This is for compatibility with certain operating systems. +.Pp +.It -c +.It --no-idata5 +Specifies that when +.Xr dlltool +is creating the exports and library files it should omit the +.Li .idata5 +section. This is for compatibility with certain operating systems. +.Pp +.It -i +.It --interwork +Specifies that +.Xr dlltool +should mark the objects in the library file and exports file that it produces +as supporting interworking between ARM and Thumb code. +.Pp +.It -n +.It --nodelete +Makes +.Xr dlltool +preserve the temporary assembler files it used to create the exports file. +If this option is repeated then dlltool will also preserve the temporary object +files it uses to create the library file. +.Pp +.It -t Va prefix +.It --temp-prefix Va prefix +Makes +.Xr dlltool +use +.Va prefix +when constructing the names of temporary assembler and object files. By default, +the temp file prefix is generated from the pid. +.Pp +.It -v +.It --verbose +Make dlltool describe what it is doing. +.Pp +.It -h +.It --help +Displays a list of command line options and then exits. +.Pp +.It -V +.It --version +Displays dlltool's version number and then exits. +.Pp +.El +.Ss The format of the Xr dlltool Pa .def file +A +.Pa .def +file contains any number of the following commands: +.Pp +.Bl -tag -width Ds +.It Li NAME Va name Li [ , Va base Li ] +The result is going to be named +.Va name +.Li .exe . +.Pp +.It Li LIBRARY Va name Li [ , Va base Li ] +The result is going to be named +.Va name +.Li .dll . +.Pp +.It Li EXPORTS ( ( ( Va name1 Li [ = Va name2 Li ] ) | ( Va name1 Li = Va module-name Li . Va external-name Li ) ) +.It Li [ Va integer Li ] [ NONAME ] [ CONSTANT ] [ DATA ] [ PRIVATE ] ) * +Declares +.Va name1 +as an exported symbol from the DLL, with optional ordinal number +.Va integer , +or declares +.Va name1 +as an alias (forward) of the function +.Va external-name +in the DLL +.Va module-name . +.Pp +.It Li IMPORTS ( ( Va internal-name Li = Va module-name Li . Va integer Li ) | [ Va internal-name Li = ] Va module-name Li . Va external-name Li ) ) * +Declares that +.Va external-name +or the exported function whose ordinal number is +.Va integer +is to be imported from the file +.Va module-name . +If +.Va internal-name +is specified then this is the name that the imported function will be referred +to in the body of the DLL. +.Pp +.It Li DESCRIPTION Va string +Puts +.Va string +into the output +.Pa .exp +file in the +.Li .rdata +section. +.Pp +.It Li STACKSIZE Va number-reserve Li [, Va number-commit Li ] +.It Li HEAPSIZE Va number-reserve Li [, Va number-commit Li ] +Generates +.Li --stack +or +.Li --heap +.Va number-reserve +, +.Va number-commit +in the output +.Li .drectve +section. The linker will see this and act upon it. +.Pp +.It Li CODE Va attr Li + +.It Li DATA Va attr Li + +.It Li SECTIONS ( Va section-name Va attr Li + ) * +Generates +.Li --attr +.Va section-name +.Va attr +in the output +.Li .drectve +section, where +.Va attr +is one of +.Li READ , +.Li WRITE , +.Li EXECUTE +or +.Li SHARED . +The linker will see this and act upon it. +.Pp +.El +.Sh readelf +.Bd -literal -offset indent +readelf [-a|--all] + [-h|--file-header] + [-l|--program-headers|--segments] + [-S|--section-headers|--sections] + [-g|--section-groups] + [-t|--section-details] + [-e|--headers] + [-s|--syms|--symbols] + [-n|--notes] + [-r|--relocs] + [-u|--unwind] + [-d|--dynamic] + [-V|--version-info] + [-A|--arch-specific] + [-D|--use-dynamic] + [-x <number or name>|--hex-dump=<number or name>] + [-w[liaprmfFsoR]| + --debug-dump[=line,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges]] + [-I|-histogram] + [-v|--version] + [-W|--wide] + [-H|--help] + elffile... +.Ed +.Pp +.Xr readelf +displays information about one or more ELF format object files. The options +control what particular information to display. +.Pp +.Va elffile +\&...are the object files to be examined. 32-bit and 64-bit ELF files are supported, +as are archives containing ELF files. +.Pp +This program performs a similar function to +.Xr objdump +but it goes into more detail and it exists independently of the bfd library, +so if there is a bug in bfd then readelf will not be affected. +.Pp +The long and short forms of options, shown here as alternatives, are equivalent. +At least one option besides +.Li -v +or +.Li -H +must be given. +.Pp +.Bl -tag -width Ds +.It -a +.It --all +Equivalent to specifying +.Op --file-header , +.Op --program-headers , +.Op --sections , +.Op --symbols , +.Op --relocs , +.Op --dynamic , +.Op --notes +and +.Op --version-info . +.Pp +.It -h +.It --file-header +Displays the information contained in the ELF header at the start of the file. +.Pp +.It -l +.It --program-headers +.It --segments +Displays the information contained in the file's segment headers, if it has +any. +.Pp +.It -S +.It --sections +.It --section-headers +Displays the information contained in the file's section headers, if it has +any. +.Pp +.It -g +.It --section-groups +Displays the information contained in the file's section groups, if it has +any. +.Pp +.It -t +.It --section-details +Displays the detailed section information. Implies +.Op -S . +.Pp +.It -s +.It --symbols +.It --syms +Displays the entries in symbol table section of the file, if it has one. +.Pp +.It -e +.It --headers +Display all the headers in the file. Equivalent to +.Op -h -l -S . +.Pp +.It -n +.It --notes +Displays the contents of the NOTE segments and/or sections, if any. +.Pp +.It -r +.It --relocs +Displays the contents of the file's relocation section, if it has one. +.Pp +.It -u +.It --unwind +Displays the contents of the file's unwind section, if it has one. Only the +unwind sections for IA64 ELF files are currently supported. +.Pp +.It -d +.It --dynamic +Displays the contents of the file's dynamic section, if it has one. +.Pp +.It -V +.It --version-info +Displays the contents of the version sections in the file, it they exist. +.Pp +.It -A +.It --arch-specific +Displays architecture-specific information in the file, if there is any. +.Pp +.It -D +.It --use-dynamic +When displaying symbols, this option makes +.Xr readelf +use the symbol table in the file's dynamic section, rather than the one in +the symbols section. +.Pp +.It -x <number or name> +.It --hex-dump=<number or name> +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. +.Pp +.It -w[liaprmfFsoR] +.It --debug-dump[=line,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges] +Displays the contents of the debug sections in the file, if any are present. +If one of the optional letters or words follows the switch then only data +found in those specific sections will be dumped. +.Pp +.It -I +.It --histogram +Display a histogram of bucket list lengths when displaying the contents of +the symbol tables. +.Pp +.It -v +.It --version +Display the version number of readelf. +.Pp +.It -W +.It --wide +Don't break output lines to fit into 80 columns. By default +.Xr readelf +breaks section header and segment listing lines for 64-bit ELF files, so that +they fit into 80 columns. This option causes +.Xr readelf +to print each section header resp. each segment one a single line, which is +far more readable on terminals wider than 80 columns. +.Pp +.It -H +.It --help +Display the command line options understood by +.Xr readelf . +.Pp +.El +.Sh Common Options +The following command-line options are supported by all of the programs described +in this manual. +.Pp +.Bl -tag -width Ds +.It @ Va file +Read command-line options from +.Va file . +The options read are inserted in place of the original @ +.Va file +option. If +.Va file +does not exist, or cannot be read, then the option will be treated literally, +and not removed. +.Pp +Options in +.Va file +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 +.Va file +may itself contain additional @ +.Va file +options; any such options will be processed recursively. +.Pp +.It --help +Display the command-line options supported by the program. +.Pp +.It --version +Display the version number of the program. +.Pp +.El +.Sh Selecting the Target System +You can specify two aspects of the target system to the GNU binary file utilities, +each in several ways: +.Pp +.Bl -bullet +.It +the target +.Pp +.It +the architecture +.El +.Pp +In the following summaries, the lists of ways to specify values are in order +of decreasing precedence. The ways listed first override those listed later. +.Pp +The commands to list valid values only list the values for which the programs +you are running were configured. If they were configured with +.Op --enable-targets=all , +the commands list most of the available values, but a few are left out; not +all targets can be configured in at once because some of them can only be +configured +.Em native +(on hosts with the same type as the target system). +.Pp +.Ss Target Selection +A +.Em target +is an object file format. A given target may be supported for multiple architectures +(see Section +.Dq Architecture Selection ) . +A target selection may also have variations for different operating systems +or architectures. +.Pp +The command to list valid target values is +.Li objdump -i +(the first column of output contains the relevant information). +.Pp +Some sample values are: +.Li a.out-hp300bsd , +.Li ecoff-littlemips , +.Li a.out-sunos-big . +.Pp +You can also specify a target using a configuration triplet. This is the same +sort of name that is passed to +.Pa configure +to specify a target. When you use a configuration triplet as an argument, +it must be fully canonicalized. You can see the canonical version of a triplet +by running the shell script +.Pa config.sub +which is included with the sources. +.Pp +Some sample configuration triplets are: +.Li m68k-hp-bsd , +.Li mips-dec-ultrix , +.Li sparc-sun-sunos . +.Pp +.Em Xr objdump Target +.Pp +Ways to specify: +.Pp +.Bl -enum +.It +command line option: +.Op -b +or +.Op --target +.Pp +.It +environment variable +.Li GNUTARGET +.Pp +.It +deduced from the input file +.El +.Pp +.Em Xr objcopy and Xr strip Input Target +.Pp +Ways to specify: +.Pp +.Bl -enum +.It +command line options: +.Op -I +or +.Op --input-target , +or +.Op -F +or +.Op --target +.Pp +.It +environment variable +.Li GNUTARGET +.Pp +.It +deduced from the input file +.El +.Pp +.Em Xr objcopy and Xr strip Output Target +.Pp +Ways to specify: +.Pp +.Bl -enum +.It +command line options: +.Op -O +or +.Op --output-target , +or +.Op -F +or +.Op --target +.Pp +.It +the input target (see \(lq +.Xr objcopy +and +.Xr strip +Input Target\(rq above) +.Pp +.It +environment variable +.Li GNUTARGET +.Pp +.It +deduced from the input file +.El +.Pp +.Em Xr nm, Xr size, and Xr strings Target +.Pp +Ways to specify: +.Pp +.Bl -enum +.It +command line option: +.Op --target +.Pp +.It +environment variable +.Li GNUTARGET +.Pp +.It +deduced from the input file +.El +.Pp +.Ss Architecture Selection +An +.Em architecture +is a type of cpu on which an object file is to run. Its name may contain a +colon, separating the name of the processor family from the name of the particular +cpu. +.Pp +The command to list valid architecture values is +.Li objdump -i +(the second column contains the relevant information). +.Pp +Sample values: +.Li m68k:68020 , +.Li mips:3000 , +.Li sparc . +.Pp +.Em Xr objdump Architecture +.Pp +Ways to specify: +.Pp +.Bl -enum +.It +command line option: +.Op -m +or +.Op --architecture +.Pp +.It +deduced from the input file +.El +.Pp +.Em Xr objcopy, Xr nm, Xr size, Xr strings Architecture +.Pp +Ways to specify: +.Pp +.Bl -enum +.It +deduced from the input file +.El +.Pp +.Sh Reporting Bugs +Your bug reports play an essential role in making the binary utilities reliable. +.Pp +Reporting a bug may help you by bringing a solution to your problem, or it +may not. But in any case the principal function of a bug report is to help +the entire community by making the next version of the binary utilities work +better. Bug reports are your contribution to their maintenance. +.Pp +In order for a bug report to serve its purpose, you must include the information +that enables us to fix the bug. +.Pp +.Ss Have You Found a Bug? +If you are not sure whether you have found a bug, here are some guidelines: +.Pp +.Bl -bullet +.It +If a binary utility gets a fatal signal, for any input whatever, that is a +bug. Reliable utilities never crash. +.Pp +.It +If a binary utility produces an error message for valid input, that is a bug. +.Pp +.It +If you are an experienced user of binary utilities, your suggestions for improvement +are welcome in any case. +.El +.Pp +.Ss How to Report Bugs +A number of companies and individuals offer support for GNU products. If you +obtained the binary utilities from a support organization, we recommend you +contact that organization first. +.Pp +You can find contact information for many support companies and individuals +in the file +.Pa etc/SERVICE +in the GNU Emacs distribution. +.Pp +The fundamental principle of reporting bugs usefully is this: +.Sy report all the facts . +If you are not sure whether to state a fact or leave it out, state it! +.Pp +Often people omit facts because they think they know what causes the problem +and assume that some details do not matter. Thus, you might assume that the +name of a file you use in an example does not matter. Well, probably it does +not, but one cannot be sure. Perhaps the bug is a stray memory reference which +happens to fetch from the location where that pathname is stored in memory; +perhaps, if the pathname were different, the contents of that location would +fool the utility into doing the right thing despite the bug. Play it safe +and give a specific, complete example. That is the easiest thing for you to +do, and the most helpful. +.Pp +Keep in mind that the purpose of a bug report is to enable us to fix the bug +if it is new to us. Therefore, always write your bug reports on the assumption +that the bug has not been reported previously. +.Pp +Sometimes people give a few sketchy facts and ask, \(lqDoes this ring a bell?\(rq +This cannot help us fix a bug, so it is basically useless. We respond by asking +for enough details to enable us to investigate. You might as well expedite +matters by sending them to begin with. +.Pp +To enable us to fix the bug, you should include all these things: +.Pp +.Bl -bullet +.It +The version of the utility. Each utility announces it if you start it with +the +.Op --version +argument. +.Pp +Without this, we will not know whether there is any point in looking for the +bug in the current version of the binary utilities. +.Pp +.It +Any patches you may have applied to the source, including any patches made +to the +.Li BFD +library. +.Pp +.It +The type of machine you are using, and the operating system name and version +number. +.Pp +.It +What compiler (and its version) was used to compile the utilities---e.g. \(lq +.Li gcc-2.7 +\(rq\&. +.Pp +.It +The command arguments you gave the utility to observe the bug. To guarantee +you will not omit something important, list them all. A copy of the Makefile +(or the output from make) is sufficient. +.Pp +If we were to try to guess the arguments, we would probably guess wrong and +then we might not encounter the bug. +.Pp +.It +A complete input file, or set of input files, that will reproduce the bug. +If the utility is reading an object file or files, then it is generally most +helpful to send the actual object files. +.Pp +If the source files were produced exclusively using GNU programs (e.g., +.Xr gcc , +.Xr gas , +and/or the GNU +.Xr ld ) , +then it may be OK to send the source files rather than the object files. In +this case, be sure to say exactly what version of +.Xr gcc , +or whatever, was used to produce the object files. Also say how +.Xr gcc , +or whatever, was configured. +.Pp +.It +A description of what behavior you observe that you believe is incorrect. +For example, \(lqIt gets a fatal signal.\(rq +.Pp +Of course, if the bug is that the utility gets a fatal signal, then we will +certainly notice it. But if the bug is incorrect output, we might not notice +unless it is glaringly wrong. You might as well not give us a chance to make +a mistake. +.Pp +Even if the problem you experience is a fatal signal, you should still say +so explicitly. Suppose something strange is going on, such as your copy of +the utility is out of sync, or you have encountered a bug in the C library +on your system. (This has happened!) Your copy might crash and ours would +not. If you told us to expect a crash, then when ours fails to crash, we would +know that the bug was not happening for us. If you had not told us to expect +a crash, then we would not be able to draw any conclusion from our observations. +.Pp +.It +If you wish to suggest changes to the source, send us context diffs, as generated +by +.Xr diff +with the +.Op -u , +.Op -c , +or +.Op -p +option. Always send diffs from the old file to the new file. If you wish to +discuss something in the +.Xr ld +source, refer to it by context, not by line number. +.Pp +The line numbers in our development sources will not match those in your sources. +Your line numbers would convey no useful information to us. +.El +.Pp +Here are some things that are not necessary: +.Pp +.Bl -bullet +.It +A description of the envelope of the bug. +.Pp +Often people who encounter a bug spend a lot of time investigating which changes +to the input file will make the bug go away and which changes will not affect +it. +.Pp +This is often time consuming and not very useful, because the way we will +find the bug is by running a single example under the debugger with breakpoints, +not by pure deduction from a series of examples. We recommend that you save +your time for something else. +.Pp +Of course, if you can find a simpler example to report +.Em instead +of the original one, that is a convenience for us. Errors in the output will +be easier to spot, running under the debugger will take less time, and so +on. +.Pp +However, simplification is not vital; if you do not want to do this, report +the bug anyway and send us the entire test case you used. +.Pp +.It +A patch for the bug. +.Pp +A patch for the bug does help us if it is a good one. But do not omit the +necessary information, such as the test case, on the assumption that a patch +is all we need. We might see problems with your patch and decide to fix the +problem another way, or we might not understand it at all. +.Pp +Sometimes with programs as complicated as the binary utilities it is very +hard to construct an example that will make the program follow a certain path +through the code. If you do not send us the example, we will not be able to +construct one, so we will not be able to verify that the bug is fixed. +.Pp +And if we cannot understand what bug you are trying to fix, or why your patch +should be an improvement, we will not install it. A test case will help us +to understand. +.Pp +.It +A guess about what the bug is or what it depends on. +.Pp +Such guesses are usually wrong. Even we cannot guess right about such things +without first using the debugger to find the facts. +.El +.Pp +.Sh GNU Free Documentation License +.Bd -filled -offset indent +Copyright (C) 2000, 2003 Free Software Foundation, Inc. 51 Franklin Street, +Fifth Floor, Boston, MA 02110-1301 USA +.Pp +Everyone is permitted to copy and distribute verbatim copies of this license +document, but changing it is not allowed. +.Ed +.Pp +.Bl -enum +.It +PREAMBLE +.Pp +The purpose of this License is to make a manual, textbook, or other written +document \(lqfree\(rq in the sense of freedom: to assure everyone the effective freedom +to copy and redistribute it, with or without modifying it, either commercially +or noncommercially. Secondarily, this License preserves for the author and +publisher a way to get credit for their work, while not being considered responsible +for modifications made by others. +.Pp +This License is a kind of \(lqcopyleft\(rq, which means that derivative works of the +document must themselves be free in the same sense. It complements the GNU +General Public License, which is a copyleft license designed for free software. +.Pp +We have designed this License in order to use it for manuals for free software, +because free software needs free documentation: a free program should come +with manuals providing the same freedoms that the software does. But this +License is not limited to software manuals; it can be used for any textual +work, regardless of subject matter or whether it is published as a printed +book. We recommend this License principally for works whose purpose is instruction +or reference. +.Pp +.It +APPLICABILITY AND DEFINITIONS +.Pp +This License applies to any manual or other work that contains a notice placed +by the copyright holder saying it can be distributed under the terms of this +License. The \(lqDocument\(rq, below, refers to any such manual or work. Any member +of the public is a licensee, and is addressed as \(lqyou.\(rq +.Pp +A \(lqModified Version\(rq of the Document means any work containing the Document +or a portion of it, either copied verbatim, or with modifications and/or translated +into another language. +.Pp +A \(lqSecondary Section\(rq is a named appendix or a front-matter section of the Document +that deals exclusively with the relationship of the publishers or authors +of the Document to the Document's overall subject (or to related matters) +and contains nothing that could fall directly within that overall subject. +(For example, if the Document is in part a textbook of mathematics, a Secondary +Section may not explain any mathematics.) The relationship could be a matter +of historical connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding them. +.Pp +The \(lqInvariant Sections\(rq are certain Secondary Sections whose titles are designated, +as being those of Invariant Sections, in the notice that says that the Document +is released under this License. +.Pp +The \(lqCover Texts\(rq are certain short passages of text that are listed, as Front-Cover +Texts or Back-Cover Texts, in the notice that says that the Document is released +under this License. +.Pp +A \(lqTransparent\(rq copy of the Document means a machine-readable copy, represented +in a format whose specification is available to the general public, whose +contents can be viewed and edited directly and straightforwardly with generic +text editors or (for images composed of pixels) generic paint programs or +(for drawings) some widely available drawing editor, and that is suitable +for input to text formatters or for automatic translation to a variety of +formats suitable for input to text formatters. A copy made in an otherwise +Transparent file format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is not +\(lqTransparent\(rq is called \(lqOpaque.\(rq +.Pp +Examples of suitable formats for Transparent copies include plain ASCII without +markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly +available DTD, and standard-conforming simple HTML designed for human modification. +Opaque formats include PostScript, PDF, proprietary formats that can be read +and edited only by proprietary word processors, SGML or XML for which the +DTD and/or processing tools are not generally available, and the machine-generated +HTML produced by some word processors for output purposes only. +.Pp +The \(lqTitle Page\(rq means, for a printed book, the title page itself, plus such +following pages as are needed to hold, legibly, the material this License +requires to appear in the title page. For works in formats which do not have +any title page as such, \(lqTitle Page\(rq means the text near the most prominent +appearance of the work's title, preceding the beginning of the body of the +text. +.Pp +.It +VERBATIM COPYING +.Pp +You may copy and distribute the Document in any medium, either commercially +or noncommercially, provided that this License, the copyright notices, and +the license notice saying this License applies to the Document are reproduced +in all copies, and that you add no other conditions whatsoever to those of +this License. You may not use technical measures to obstruct or control the +reading or further copying of the copies you make or distribute. However, +you may accept compensation in exchange for copies. If you distribute a large +enough number of copies you must also follow the conditions in section 3. +.Pp +You may also lend copies, under the same conditions stated above, and you +may publicly display copies. +.Pp +.It +COPYING IN QUANTITY +.Pp +If you publish printed copies of the Document numbering more than 100, and +the Document's license notice requires Cover Texts, you must enclose the copies +in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover +Texts on the front cover, and Back-Cover Texts on the back cover. Both covers +must also clearly and legibly identify you as the publisher of these copies. +The front cover must present the full title with all words of the title equally +prominent and visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve the title +of the Document and satisfy these conditions, can be treated as verbatim copying +in other respects. +.Pp +If the required texts for either cover are too voluminous to fit legibly, +you should put the first ones listed (as many as fit reasonably) on the actual +cover, and continue the rest onto adjacent pages. +.Pp +If you publish or distribute Opaque copies of the Document numbering more +than 100, you must either include a machine-readable Transparent copy along +with each Opaque copy, or state in or with each Opaque copy a publicly-accessible +computer-network location containing a complete Transparent copy of the Document, +free of added material, which the general network-using public has access +to download anonymously at no charge using public-standard network protocols. +If you use the latter option, you must take reasonably prudent steps, when +you begin distribution of Opaque copies in quantity, to ensure that this Transparent +copy will remain thus accessible at the stated location until at least one +year after the last time you distribute an Opaque copy (directly or through +your agents or retailers) of that edition to the public. +.Pp +It is requested, but not required, that you contact the authors of the Document +well before redistributing any large number of copies, to give them a chance +to provide you with an updated version of the Document. +.Pp +.It +MODIFICATIONS +.Pp +You may copy and distribute a Modified Version of the Document under the conditions +of sections 2 and 3 above, provided that you release the Modified Version +under precisely this License, with the Modified Version filling the role of +the Document, thus licensing distribution and modification of the Modified +Version to whoever possesses a copy of it. In addition, you must do these +things in the Modified Version: +.Pp +A. Use in the Title Page (and on the covers, if any) a title distinct from +that of the Document, and from those of previous versions (which should, if +there were any, be listed in the History section of the Document). You may +use the same title as a previous version if the original publisher of that +version gives permission. B. List on the Title Page, as authors, one or more +persons or entities responsible for authorship of the modifications in the +Modified Version, together with at least five of the principal authors of +the Document (all of its principal authors, if it has less than five). C. +State on the Title page the name of the publisher of the Modified Version, +as the publisher. D. Preserve all the copyright notices of the Document. +E. Add an appropriate copyright notice for your modifications adjacent to +the other copyright notices. F. Include, immediately after the copyright +notices, a license notice giving the public permission to use the Modified +Version under the terms of this License, in the form shown in the Addendum +below. G. Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. H. Include +an unaltered copy of this License. I. Preserve the section entitled \(lqHistory\(rq, +and its title, and add to it an item stating at least the title, year, new +authors, and publisher of the Modified Version as given on the Title Page. +If there is no section entitled \(lqHistory\(rq in the Document, create one stating +the title, year, authors, and publisher of the Document as given on its Title +Page, then add an item describing the Modified Version as stated in the previous +sentence. J. Preserve the network location, if any, given in the Document +for public access to a Transparent copy of the Document, and likewise the +network locations given in the Document for previous versions it was based +on. These may be placed in the \(lqHistory\(rq section. You may omit a network location +for a work that was published at least four years before the Document itself, +or if the original publisher of the version it refers to gives permission. +K. In any section entitled \(lqAcknowledgements\(rq or \(lqDedications\(rq, preserve the section's +title, and preserve in the section all the substance and tone of each of the +contributor acknowledgements and/or dedications given therein. L. Preserve +all the Invariant Sections of the Document, unaltered in their text and in +their titles. Section numbers or the equivalent are not considered part of +the section titles. M. Delete any section entitled \(lqEndorsements.\(rq Such a section +may not be included in the Modified Version. N. Do not retitle any existing +section as \(lqEndorsements\(rq or to conflict in title with any Invariant Section. +.Pp +If the Modified Version includes new front-matter sections or appendices that +qualify as Secondary Sections and contain no material copied from the Document, +you may at your option designate some or all of these sections as invariant. +To do this, add their titles to the list of Invariant Sections in the Modified +Version's license notice. These titles must be distinct from any other section +titles. +.Pp +You may add a section entitled \(lqEndorsements\(rq, provided it contains nothing +but endorsements of your Modified Version by various parties--for example, +statements of peer review or that the text has been approved by an organization +as the authoritative definition of a standard. +.Pp +You may add a passage of up to five words as a Front-Cover Text, and a passage +of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts +in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover +Text may be added by (or through arrangements made by) any one entity. If +the Document already includes a cover text for the same cover, previously +added by you or by arrangement made by the same entity you are acting on behalf +of, you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. +.Pp +The author(s) and publisher(s) of the Document do not by this License give +permission to use their names for publicity for or to assert or imply endorsement +of any Modified Version. +.Pp +.It +COMBINING DOCUMENTS +.Pp +You may combine the Document with other documents released under this License, +under the terms defined in section 4 above for modified versions, provided +that you include in the combination all of the Invariant Sections of all of +the original documents, unmodified, and list them all as Invariant Sections +of your combined work in its license notice. +.Pp +The combined work need only contain one copy of this License, and multiple +identical Invariant Sections may be replaced with a single copy. If there +are multiple Invariant Sections with the same name but different contents, +make the title of each such section unique by adding at the end of it, in +parentheses, the name of the original author or publisher of that section +if known, or else a unique number. Make the same adjustment to the section +titles in the list of Invariant Sections in the license notice of the combined +work. +.Pp +In the combination, you must combine any sections entitled \(lqHistory\(rq in the +various original documents, forming one section entitled \(lqHistory\(rq; likewise +combine any sections entitled \(lqAcknowledgements\(rq, and any sections entitled +\(lqDedications.\(rq You must delete all sections entitled \(lqEndorsements.\(rq +.Pp +.It +COLLECTIONS OF DOCUMENTS +.Pp +You may make a collection consisting of the Document and other documents released +under this License, and replace the individual copies of this License in the +various documents with a single copy that is included in the collection, provided +that you follow the rules of this License for verbatim copying of each of +the documents in all other respects. +.Pp +You may extract a single document from such a collection, and distribute it +individually under this License, provided you insert a copy of this License +into the extracted document, and follow this License in all other respects +regarding verbatim copying of that document. +.Pp +.It +AGGREGATION WITH INDEPENDENT WORKS +.Pp +A compilation of the Document or its derivatives with other separate and independent +documents or works, in or on a volume of a storage or distribution medium, +does not as a whole count as a Modified Version of the Document, provided +no compilation copyright is claimed for the compilation. Such a compilation +is called an \(lqaggregate\(rq, and this License does not apply to the other self-contained +works thus compiled with the Document, on account of their being thus compiled, +if they are not themselves derivative works of the Document. +.Pp +If the Cover Text requirement of section 3 is applicable to these copies of +the Document, then if the Document is less than one quarter of the entire +aggregate, the Document's Cover Texts may be placed on covers that surround +only the Document within the aggregate. Otherwise they must appear on covers +around the whole aggregate. +.Pp +.It +TRANSLATION +.Pp +Translation is considered a kind of modification, so you may distribute translations +of the Document under the terms of section 4. Replacing Invariant Sections +with translations requires special permission from their copyright holders, +but you may include translations of some or all Invariant Sections in addition +to the original versions of these Invariant Sections. You may include a translation +of this License provided that you also include the original English version +of this License. In case of a disagreement between the translation and the +original English version of this License, the original English version will +prevail. +.Pp +.It +TERMINATION +.Pp +You may not copy, modify, sublicense, or distribute the Document except as +expressly provided for under this License. Any other attempt to copy, modify, +sublicense or distribute the Document is void, and will automatically terminate +your rights under this License. However, parties who have received copies, +or rights, from you under this License will not have their licenses terminated +so long as such parties remain in full compliance. +.Pp +.It +FUTURE REVISIONS OF THIS LICENSE +.Pp +The Free Software Foundation may publish new, revised versions of the GNU +Free Documentation License from time to time. Such new versions will be similar +in spirit to the present version, but may differ in detail to address new +problems or concerns. See http://www.gnu.org/copyleft/. +.Pp +Each version of the License is given a distinguishing version number. If the +Document specifies that a particular numbered version of this License \(lqor any +later version\(rq applies to it, you have the option of following the terms and +conditions either of that specified version or of any later version that has +been published (not as a draft) by the Free Software Foundation. If the Document +does not specify a version number of this License, you may choose any version +ever published (not as a draft) by the Free Software Foundation. +.Pp +.El +.Ss ADDENDUM: How to use this License for your documents +To use this License in a document you have written, include a copy of the +License in the document and put the following copyright and license notices +just after the title page: +.Pp +.Bd -literal -offset indent + +Copyright (C) year your name. +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 +or any later version published by the Free Software Foundation; +with the Invariant Sections being list their titles, with the +Front-Cover Texts being list, and with the Back-Cover Texts being list. +A copy of the license is included in the section entitled "GNU +Free Documentation License." + +.Ed +.Pp +If you have no Invariant Sections, write \(lqwith no Invariant Sections\(rq instead +of saying which ones are invariant. If you have no Front-Cover Texts, write +\(lqno Front-Cover Texts\(rq instead of \(lqFront-Cover Texts being +.Va list +\(rq; likewise for Back-Cover Texts. +.Pp +If your document contains nontrivial examples of program code, we recommend +releasing these examples in parallel under your choice of free software license, +such as the GNU General Public License, to permit their use in free software. +.Pp +.Sh Binutils Index diff --git a/contrib/binutils/gas/doc/as.7 b/contrib/binutils/gas/doc/as.7 new file mode 100644 index 0000000..4d33557 --- /dev/null +++ b/contrib/binutils/gas/doc/as.7 @@ -0,0 +1,8368 @@ +.Dd 2015-03-02 +.Dt AS 7 +.Os +.Sh NAME +.Nm as +.Nd Using as (machine specific) +.Sh Using as +This file is a user guide to the GNU assembler +.Xr as +version "2.17.50 [FreeBSD] 2007-07-03". This version of the file describes +.Xr as +configured to generate code for machine specific architectures. +.Pp +This document is distributed under the terms of the GNU Free Documentation +License. A copy of the license is included in the section entitled \(lqGNU Free +Documentation License\(rq. +.Pp +.Sh Overview +Here is a brief summary of how to invoke +.Xr as . +For details, see Invoking,,Command-Line Options. +.Pp +.Bd -literal -offset indent +as [-a[cdhlns][=file]] [--alternate] [-D] + [--defsym sym=val] [-f] [-g] [--gstabs] + [--gstabs+] [--gdwarf-2] [--help] [-I dir] [-J] + [-K] [-L] [--listing-lhs-width=NUM] + [--listing-lhs-width2=NUM] [--listing-rhs-width=NUM] + [--listing-cont-lines=NUM] [--keep-locals] [-o + objfile] [-R] [--reduce-memory-overheads] [--statistics] + [-v] [-version] [--version] [-W] [--warn] + [--fatal-warnings] [-w] [-x] [-Z] [@FILE] + [--target-help] [target-options] + [--|files ...] + +Target ARM options: + [-mcpu=processor[+extension...]] + [-march=architecture[+extension...]] + [-mfpu=floating-point-format] + [-mfloat-abi=abi] + [-meabi=ver] + [-mthumb] + [-EB|-EL] + [-mapcs-32|-mapcs-26|-mapcs-float| + -mapcs-reentrant] + [-mthumb-interwork] [-k] + + +Target i386 options: + [--32|--64] [-n] + [-march=CPU] [-mtune=CPU] + + +Target IA-64 options: + [-mconstant-gp|-mauto-pic] + [-milp32|-milp64|-mlp64|-mp64] + [-mle|mbe] + [-mtune=itanium1|-mtune=itanium2] + [-munwind-check=warning|-munwind-check=error] + [-mhint.b=ok|-mhint.b=warning|-mhint.b=error] + [-x|-xexplicit] [-xauto] [-xdebug] + + +Target MIPS options: + [-nocpp] [-EL] [-EB] [-O[optimization level]] + [-g[debug level]] [-G num] [-KPIC] [-call_shared] + [-non_shared] [-xgot [-mvxworks-pic] + [-mabi=ABI] [-32] [-n32] [-64] [-mfp32] [-mgp32] + [-march=CPU] [-mtune=CPU] [-mips1] [-mips2] + [-mips3] [-mips4] [-mips5] [-mips32] [-mips32r2] + [-mips64] [-mips64r2] + [-construct-floats] [-no-construct-floats] + [-trap] [-no-break] [-break] [-no-trap] + [-mfix7000] [-mno-fix7000] + [-mips16] [-no-mips16] + [-msmartmips] [-mno-smartmips] + [-mips3d] [-no-mips3d] + [-mdmx] [-no-mdmx] + [-mdsp] [-mno-dsp] + [-mdspr2] [-mno-dspr2] + [-mmt] [-mno-mt] + [-mdebug] [-no-mdebug] + [-mpdr] [-mno-pdr] + + +Target PowerPC options: + [-mpwrx|-mpwr2|-mpwr|-m601|-mppc|-mppc32|-m603|-m604| + -m403|-m405|-mppc64|-m620|-mppc64bridge|-mbooke| + -mbooke32|-mbooke64] + [-mcom|-many|-maltivec] [-memb] + [-mregnames|-mno-regnames] + [-mrelocatable|-mrelocatable-lib] + [-mlittle|-mlittle-endian|-mbig|-mbig-endian] + [-msolaris|-mno-solaris] + + +Target SPARC options: + [-Av6|-Av7|-Av8|-Asparclet|-Asparclite + -Av8plus|-Av8plusa|-Av9|-Av9a] + [-xarch=v8plus|-xarch=v8plusa] [-bump] + [-32|-64] + + + +.Ed +.Pp +.Bl -tag -width Ds +.It @ Va file +Read command-line options from +.Va file . +The options read are inserted in place of the original @ +.Va file +option. If +.Va file +does not exist, or cannot be read, then the option will be treated literally, +and not removed. +.Pp +Options in +.Va file +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 +.Va file +may itself contain additional @ +.Va file +options; any such options will be processed recursively. +.Pp +.It -a[cdhlmns] +Turn on listings, in any of a variety of ways: +.Pp +.Bl -tag -width Ds +.It -ac +omit false conditionals +.Pp +.It -ad +omit debugging directives +.Pp +.It -ah +include high-level source +.Pp +.It -al +include assembly +.Pp +.It -am +include macro expansions +.Pp +.It -an +omit forms processing +.Pp +.It -as +include symbols +.Pp +.It =file +set the name of the listing file +.El +.Pp +You may combine these options; for example, use +.Li -aln +for assembly listing without forms processing. The +.Li =file +option, if used, must be the last one. By itself, +.Li -a +defaults to +.Li -ahls . +.Pp +.It --alternate +Begin in alternate macro mode.See Section +.Dq Altmacro . +.Pp +.It -D +Ignored. This option is accepted for script compatibility with calls to other +assemblers. +.Pp +.It --defsym Va sym= Va value +Define the symbol +.Va sym +to be +.Va value +before assembling the input file. +.Va value +must be an integer constant. As in C, a leading +.Li 0x +indicates a hexadecimal value, and a leading +.Li 0 +indicates an octal value. The value of the symbol can be overridden inside +a source file via the use of a +.Li .set +pseudo-op. +.Pp +.It -f +\(lqfast\(rq---skip whitespace and comment preprocessing (assume source is compiler +output). +.Pp +.It -g +.It --gen-debug +Generate debugging information for each assembler source line using whichever +debug format is preferred by the target. This currently means either STABS, +ECOFF or DWARF2. +.Pp +.It --gstabs +Generate stabs debugging information for each assembler line. This may help +debugging assembler code, if the debugger can handle it. +.Pp +.It --gstabs+ +Generate stabs debugging information for each assembler line, with GNU 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 GNU extension is the location of the current working directory at +assembling time. +.Pp +.It --gdwarf-2 +Generate DWARF2 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. +.Pp +.It --help +Print a summary of the command line options and exit. +.Pp +.It --target-help +Print a summary of all target specific options and exit. +.Pp +.It -I Va dir +Add directory +.Va dir +to the search list for +.Li .include +directives. +.Pp +.It -J +Don't warn about signed overflow. +.Pp +.It -K +This option is accepted but has no effect on the machine specific family. +.Pp +.It -L +.It --keep-locals +Keep (in the symbol table) local symbols. These symbols start with system-specific +local label prefixes, typically +.Li .L +for ELF systems or +.Li L +for traditional a.out systems.See Section +.Dq Symbol Names . +.Pp +.It --listing-lhs-width= Va number +Set the maximum width, in words, of the output data column for an assembler +listing to +.Va number . +.Pp +.It --listing-lhs-width2= Va number +Set the maximum width, in words, of the output data column for continuation +lines in an assembler listing to +.Va number . +.Pp +.It --listing-rhs-width= Va number +Set the maximum width of an input source line, as displayed in a listing, +to +.Va number +bytes. +.Pp +.It --listing-cont-lines= Va number +Set the maximum number of lines printed in a listing for a single line of +input to +.Va number ++ 1. +.Pp +.It -o Va objfile +Name the object-file output from +.Xr as +.Va objfile . +.Pp +.It -R +Fold the data section into the text section. +.Pp +Set the default size of GAS's hash tables to a prime number close to +.Va number . +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. +.Pp +.It --reduce-memory-overheads +This option reduces GAS's memory requirements, at the expense of making the +assembly processes slower. Currently this switch is a synonym for +.Li --hash-size=4051 , +but in the future it may have other effects as well. +.Pp +.It --statistics +Print the maximum space (in bytes) and total time (in seconds) used by assembly. +.Pp +.It --strip-local-absolute +Remove local absolute symbols from the outgoing symbol table. +.Pp +.It -v +.It -version +Print the +.Xr as +version. +.Pp +.It --version +Print the +.Xr as +version and exit. +.Pp +.It -W +.It --no-warn +Suppress warning messages. +.Pp +.It --fatal-warnings +Treat warnings as errors. +.Pp +.It --warn +Don't suppress warning messages or treat them as errors. +.Pp +.It -w +Ignored. +.Pp +.It -x +Ignored. +.Pp +.It -Z +Generate an object file even after errors. +.Pp +.It -- | Va files ... +Standard input, or source files to assemble. +.Pp +.El +The following options are available when as is configured for the ARM processor +family. +.Pp +.Bl -tag -width Ds +.It -mcpu= Va processor[+ Va extension...] +Specify which ARM processor variant is the target. +.It -march= Va architecture[+ Va extension...] +Specify which ARM architecture variant is used by the target. +.It -mfpu= Va floating-point-format +Select which Floating Point architecture is the target. +.It -mfloat-abi= Va abi +Select which floating point ABI is in use. +.It -mthumb +Enable Thumb only instruction decoding. +.It -mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant +Select which procedure calling convention is in use. +.It -EB | -EL +Select either big-endian (-EB) or little-endian (-EL) output. +.It -mthumb-interwork +Specify that the code has been generated with interworking between Thumb and +ARM code in mind. +.It -k +Specify that PIC code has been generated. +.El +.Pp +The following options are available when +.Xr as +is configured for the SPARC architecture: +.Pp +.Bl -tag -width Ds +.It -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite +.It -Av8plus | -Av8plusa | -Av9 | -Av9a +Explicitly select a variant of the SPARC architecture. +.Pp +.Li -Av8plus +and +.Li -Av8plusa +select a 32 bit environment. +.Li -Av9 +and +.Li -Av9a +select a 64 bit environment. +.Pp +.Li -Av8plusa +and +.Li -Av9a +enable the SPARC V9 instruction set with UltraSPARC extensions. +.Pp +.It -xarch=v8plus | -xarch=v8plusa +For compatibility with the Solaris v9 assembler. These options are equivalent +to -Av8plus and -Av8plusa, respectively. +.Pp +.It -bump +Warn when the assembler switches to another architecture. +.El +.Pp +The following options are available when as is configured for a mips processor. +.Pp +.Bl -tag -width Ds +.It -G Va num +This option sets the largest size of an object that can be referenced implicitly +with the +.Li gp +register. It is only accepted for targets that use ECOFF format, such as a +DECstation running Ultrix. The default value is 8. +.Pp +.It -EB +Generate \(lqbig endian\(rq format output. +.Pp +.It -EL +Generate \(lqlittle endian\(rq format output. +.Pp +.It -mips1 +.It -mips2 +.It -mips3 +.It -mips4 +.It -mips5 +.It -mips32 +.It -mips32r2 +.It -mips64 +.It -mips64r2 +Generate code for a particular mips Instruction Set Architecture level. +.Li -mips1 +is an alias for +.Li -march=r3000 , +.Li -mips2 +is an alias for +.Li -march=r6000 , +.Li -mips3 +is an alias for +.Li -march=r4000 +and +.Li -mips4 +is an alias for +.Li -march=r8000 . +.Li -mips5 , +.Li -mips32 , +.Li -mips32r2 , +.Li -mips64 , +and +.Li -mips64r2 +correspond to generic +.Li MIPS V , +.Li MIPS32 , +.Li MIPS32 Release 2 , +.Li MIPS64 , +and +.Li MIPS64 Release 2 +ISA processors, respectively. +.Pp +.It -march= Va CPU +Generate code for a particular mips cpu. +.Pp +.It -mtune= Va cpu +Schedule and tune for a particular mips cpu. +.Pp +.It -mfix7000 +.It -mno-fix7000 +Cause nops to be inserted if the read of the destination register of an mfhi +or mflo instruction occurs in the following two instructions. +.Pp +.It -mdebug +.It -no-mdebug +Cause stabs-style debugging output to go into an ECOFF-style .mdebug section +instead of the standard ELF .stabs sections. +.Pp +.It -mpdr +.It -mno-pdr +Control generation of +.Li .pdr +sections. +.Pp +.It -mgp32 +.It -mfp32 +The register sizes are normally inferred from the ISA and ABI, but these flags +force a certain group of registers to be treated as 32 bits wide at all times. +.Li -mgp32 +controls the size of general-purpose registers and +.Li -mfp32 +controls the size of floating-point registers. +.Pp +.It -mips16 +.It -no-mips16 +Generate code for the MIPS 16 processor. This is equivalent to putting +.Li .set mips16 +at the start of the assembly file. +.Li -no-mips16 +turns off this option. +.Pp +.It -msmartmips +.It -mno-smartmips +Enables the SmartMIPS extension to the MIPS32 instruction set. This is equivalent +to putting +.Li .set smartmips +at the start of the assembly file. +.Li -mno-smartmips +turns off this option. +.Pp +.It -mips3d +.It -no-mips3d +Generate code for the MIPS-3D Application Specific Extension. This tells the +assembler to accept MIPS-3D instructions. +.Li -no-mips3d +turns off this option. +.Pp +.It -mdmx +.It -no-mdmx +Generate code for the MDMX Application Specific Extension. This tells the +assembler to accept MDMX instructions. +.Li -no-mdmx +turns off this option. +.Pp +.It -mdsp +.It -mno-dsp +Generate code for the DSP Release 1 Application Specific Extension. This tells +the assembler to accept DSP Release 1 instructions. +.Li -mno-dsp +turns off this option. +.Pp +.It -mdspr2 +.It -mno-dspr2 +Generate code for the DSP Release 2 Application Specific Extension. This option +implies -mdsp. This tells the assembler to accept DSP Release 2 instructions. +.Li -mno-dspr2 +turns off this option. +.Pp +.It -mmt +.It -mno-mt +Generate code for the MT Application Specific Extension. This tells the assembler +to accept MT instructions. +.Li -mno-mt +turns off this option. +.Pp +.It --construct-floats +.It --no-construct-floats +The +.Li --no-construct-floats +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 +.Li --construct-floats +is selected, allowing construction of these floating point constants. +.Pp +.It --emulation= Va name +This option causes +.Xr as +to emulate +.Xr as +configured for some other target, in all respects, including output format +(choosing between ELF and ECOFF only), handling of pseudo-opcodes which may +generate debugging information or store symbol table information, and default +endianness. The available configuration names are: +.Li mipsecoff , +.Li mipself , +.Li mipslecoff , +.Li mipsbecoff , +.Li mipslelf , +.Li mipsbelf . +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 +.Li b +or +.Li l +in the name. Using +.Li -EB +or +.Li -EL +will override the endianness selection in any case. +.Pp +This option is currently supported only when the primary target +.Xr as +is configured for is a mips ELF or ECOFF target. Furthermore, the primary +target or others specified with +.Li --enable-targets=... +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. +.Pp +Eventually, this option will support more configurations, with more fine-grained +control over the assembler's behavior, and will be supported for more processors. +.Pp +.It -nocpp +.Xr as +ignores this option. It is accepted for compatibility with the native tools. +.Pp +.It --trap +.It --no-trap +.It --break +.It --no-break +Control how to deal with multiplication overflow and division by zero. +.Li --trap +or +.Li --no-break +(which are synonyms) take a trap exception (and only work for Instruction +Set Architecture level 2 and higher); +.Li --break +or +.Li --no-trap +(also synonyms, and the default) take a break exception. +.Pp +.It -n +When this option is used, +.Xr as +will issue a warning every time it generates a nop instruction from a macro. +.El +.Pp +.Ss Structure of this Manual +This manual is intended to describe what you need to know to use GNU +.Xr as . +We cover the syntax expected in source files, including notation for symbols, +constants, and expressions; the directives that +.Xr as +understands; and of course how to invoke +.Xr as . +.Pp +We also cover special features in the machine specific configuration of +.Xr as , +including assembler directives. +.Pp +On the other hand, this manual is +.Em not +intended as an introduction to programming in assembly language---let alone +programming in general! In a similar vein, we make no attempt to introduce +the machine architecture; we do +.Em not +describe the instruction set, standard mnemonics, registers or addressing +modes that are standard to a particular architecture. +.Pp +.Ss The GNU Assembler +GNU +.Xr as +is really a family of assemblers. This manual describes +.Xr as , +a member of that family which is configured for the machine specific architectures. +If you use (or have used) the GNU 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 +.Em pseudo-ops ) +and assembler syntax. +.Pp +.Xr as +is primarily intended to assemble the output of the GNU C compiler +.Li gcc +for use by the linker +.Li ld . +Nevertheless, we've tried to make +.Xr as +assemble correctly everything that other assemblers for the same machine would +assemble. +.Pp +Unlike older assemblers, +.Xr as +is designed to assemble a source program in one pass of the source file. This +has a subtle impact on the +.Li .org +directive (see Section +.Dq Org ) . +.Pp +.Ss Object File Formats +The GNU assembler can be configured to produce several alternative object +file formats. For the most part, this does not affect how you write assembly +language programs; but directives for debugging symbols are typically different +in different file formats.See Section +.Dq Symbol Attributes . +For the machine specific target, +.Xr as +is configured to produce ELF format object files. +.Pp +.Ss Command Line +After the program name +.Xr as , +the command line may contain options and file names. Options may appear in +any order, and may be before, after, or between file names. The order of file +names is significant. +.Pp +.Pa -- +(two hyphens) by itself names the standard input file explicitly, as one of +the files for +.Xr as +to assemble. +.Pp +Except for +.Li -- +any command line argument that begins with a hyphen ( +.Li - ) +is an option. Each option changes the behavior of +.Xr as . +No option changes the way another option works. An option is a +.Li - +followed by one or more letters; the case of the letter is important. All +options are optional. +.Pp +Some options expect exactly one file name to follow them. The file name may +either immediately follow the option's letter (compatible with older assemblers) +or it may be the next command argument (GNU standard). These two command lines +are equivalent: +.Pp +.Bd -literal -offset indent +as -o my-object-file.o mumble.s +as -omy-object-file.o mumble.s +.Ed +.Pp +.Ss Input Files +We use the phrase +.Em source program , +abbreviated +.Em source , +to describe the program input to one run of +.Xr as . +The program may be in one or more files; how the source is partitioned into +files doesn't change the meaning of the source. +.Pp +The source program is a concatenation of the text in all the files, in the +order specified. +.Pp +Each time you run +.Xr as +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 +.Xr as +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 +.Xr as +no file names it attempts to read one input file from the +.Xr as +standard input, which is normally your terminal. You may have to type ctl-D +to tell +.Xr as +there is no more program to assemble. +.Pp +Use +.Li -- +if you need to explicitly name the standard input file in your command line. +.Pp +If the source is empty, +.Xr as +produces a small, empty object file. +.Pp +.Em Filenames and Line-numbers +.Pp +There are two ways of locating a line in the input file (or files) and either +may be used in reporting error messages. One way refers to a line number in +a physical file; the other refers to a line number in a \(lqlogical\(rq file.See Section +.Dq Errors . +.Pp +.Em Physical files +are those files named in the command line given to +.Xr as . +.Pp +.Em Logical files +are simply names declared explicitly by assembler directives; they bear no +relation to physical files. Logical file names help error messages reflect +the original source file, when +.Xr as +source is itself synthesized from other files. +.Xr as +understands the +.Li # +directives emitted by the +.Li gcc +preprocessor. See also File,, +.Li .file +\&. +.Pp +.Ss Output (Object) File +Every time you run +.Xr as +it produces an output file, which is your assembly language program translated +into numbers. This file is the object file. Its default name is +.Li a.out . +You can give it another name by using the +.Op -o +option. Conventionally, object file names end with +.Pa .o . +The default name is used for historical reasons: older assemblers were capable +of assembling self-contained programs directly into a runnable program. (For +some formats, this isn't currently possible, but it can be done for the +.Li a.out +format.) +.Pp +The object file is meant for input to the linker +.Li ld . +It contains assembled program code, information to help +.Li ld +integrate the assembled program into a runnable file, and (optionally) symbolic +information for the debugger. +.Pp +.Ss Error and Warning Messages +.Xr as +may write warnings and error messages to the standard error file (usually +your terminal). This should not happen when a compiler runs +.Xr as +automatically. Warnings report an assumption made so that +.Xr as +could keep assembling a flawed program; errors report a grave problem that +stops the assembly. +.Pp +Warning messages have the format +.Pp +.Bd -literal -offset indent +file_name:NNN:Warning Message Text +.Ed +.Pp +(where +.Sy NNN +is a line number). If a logical file name has been given (see Section +.Dq File ) +it is used for the filename, otherwise the name of the current input file +is used. If a logical line number was given then it is used to calculate the +number printed, otherwise the actual line in the current source file is printed. +The message text is intended to be self explanatory (in the grand Unix tradition). +.Pp +Error messages have the format +.Bd -literal -offset indent +file_name:NNN:FATAL:Error Message Text +.Ed +The file name and line number are derived as for warning messages. The actual +message text may be rather less explanatory because many of them aren't supposed +to happen. +.Pp +.Sh Command-Line Options +This chapter describes command-line options available in +.Em all +versions of the GNU assembler; see Machine Dependencies, for options specific +to the machine specific target. +.Pp +If you are invoking +.Xr as +via the GNU C compiler, you can use the +.Li -Wa +option to pass arguments through to the assembler. The assembler arguments +must be separated from each other (and the +.Li -Wa ) +by commas. For example: +.Pp +.Bd -literal -offset indent +gcc -c -g -O -Wa,-alh,-L file.c +.Ed +.Pp +This passes two options to the assembler: +.Li -alh +(emit a listing to standard output with high-level and assembly source) and +.Li -L +(retain local symbols in the symbol table). +.Pp +Usually you do not need to use this +.Li -Wa +mechanism, since many compiler command-line options are automatically passed +to the assembler by the compiler. (You can call the GNU compiler driver with +the +.Li -v +option to see precisely what options it passes to each compilation pass, including +the assembler.) +.Pp +.Ss Enable Listings: Op -a[cdhlns] +These options enable listing output from the assembler. By itself, +.Li -a +requests high-level, assembly, and symbols listing. You can use other letters +to select specific options for the list: +.Li -ah +requests a high-level language listing, +.Li -al +requests an output-program assembly listing, and +.Li -as +requests a symbol table listing. High-level listings require that a compiler +debugging option like +.Li -g +be used, and that assembly listings ( +.Li -al ) +be requested also. +.Pp +Use the +.Li -ac +option to omit false conditionals from a listing. Any lines which are not +assembled because of a false +.Li .if +(or +.Li .ifdef , +or any other conditional), or a true +.Li .if +followed by an +.Li .else , +will be omitted from the listing. +.Pp +Use the +.Li -ad +option to omit debugging directives from the listing. +.Pp +Once you have specified one of these options, you can further control listing +output and its appearance using the directives +.Li .list , +.Li .nolist , +.Li .psize , +.Li .eject , +.Li .title , +and +.Li .sbttl . +The +.Li -an +option turns off all forms processing. If you do not request listing output +with one of the +.Li -a +options, the listing-control directives have no effect. +.Pp +The letters after +.Li -a +may be combined into one option, +.Em e.g. , +.Li -aln . +.Pp +Note if the assembler source is coming from the standard input (e.g., because +it is being created by +.Li gcc +and the +.Li -pipe +command line switch is being used) then the listing will not contain any comments +or preprocessor directives. This is because the listing code buffers input +source lines from stdin only after they have been preprocessed by the assembler. +This reduces memory usage and makes the code more efficient. +.Pp +.Ss Op --alternate +Begin in alternate macro mode, see Altmacro,, +.Li .altmacro +\&. +.Pp +.Ss Op -D +This option has no effect whatsoever, but it is accepted to make it more likely +that scripts written for other assemblers also work with +.Xr as . +.Pp +.Ss Work Faster: Op -f +.Li -f +should only be used when assembling programs written by a (trusted) compiler. +.Li -f +stops the assembler from doing whitespace and comment preprocessing on the +input file(s) before assembling them.See Section +.Dq Preprocessing . +.Pp +.Qo +.Em Warning: +if you use +.Li -f +when the files actually need to be preprocessed (if they contain comments, +for example), +.Xr as +does not work correctly. +.Qc +.Pp +.Ss Li .include Search Path: Op -I Va path +Use this option to add a +.Va path +to the list of directories +.Xr as +searches for files specified in +.Li .include +directives (see Section +.Dq Include ) . +You may use +.Op -I +as many times as necessary to include a variety of paths. The current working +directory is always searched first; after that, +.Xr as +searches any +.Li -I +directories in the same order as they were specified (left to right) on the +command line. +.Pp +.Ss Difference Tables: Op -K +On the machine specific family, this option is allowed, but has no effect. +It is permitted for compatibility with the GNU assembler on other platforms, +where it can be used to warn when the assembler alters the machine code generated +for +.Li .word +directives in difference tables. The machine specific family does not have +the addressing limitations that sometimes lead to this alteration on other +platforms. +.Pp +.Ss Include Local Symbols: Op -L +Symbols beginning with system-specific local label prefixes, typically +.Li .L +for ELF systems or +.Li L +for traditional a.out systems, are called +.Em local symbols . +See Section.Dq Symbol Names . +Normally you do not see such symbols when debugging, because they are intended +for the use of programs (like compilers) that compose assembler programs, +not for your notice. Normally both +.Xr as +and +.Li ld +discard such symbols, so you do not normally debug with them. +.Pp +This option tells +.Xr as +to retain those local symbols in the object file. Usually if you do this you +also tell the linker +.Li ld +to preserve those symbols. +.Pp +.Ss Configuring listing output: Op --listing +The listing feature of the assembler can be enabled via the command line switch +.Li -a +(see Section +.Dq a ) . +This feature combines the input source file(s) with a hex dump of the corresponding +locations in the output object file, and displays them as a listing file. +The format of this listing can be controlled by directives inside the assembler +source (i.e., +.Li .list +(see Section +.Dq List ) , +.Li .title +(see Section +.Dq Title ) , +.Li .sbttl +(see Section +.Dq Sbttl ) , +.Li .psize +(see Section +.Dq Psize ) , +and +.Li .eject +(see Section +.Dq Eject ) +and also by the following switches: +.Pp +.Bl -tag -width Ds +.It --listing-lhs-width= Li number +Sets the maximum width, in words, of the first line of the hex byte dump. +This dump appears on the left hand side of the listing output. +.Pp +.It --listing-lhs-width2= Li number +Sets the maximum width, in words, of any further lines of the hex byte dump +for a given input source line. If this value is not specified, it defaults +to being the same as the value specified for +.Li --listing-lhs-width . +If neither switch is used the default is to one. +.Pp +.It --listing-rhs-width= Li number +Sets the maximum width, in characters, of the source line that is displayed +alongside the hex dump. The default value for this parameter is 100. The source +line is displayed on the right hand side of the listing output. +.Pp +.It --listing-cont-lines= Li number +Sets the maximum number of continuation lines of hex dump that will be displayed +for a given single line of source input. The default value is 4. +.El +.Pp +.Ss Assemble in MRI Compatibility Mode: Op -M +The +.Op -M +or +.Op --mri +option selects MRI compatibility mode. This changes the syntax and pseudo-op +handling of +.Xr as +to make it compatible with the +.Li ASM68K +or the +.Li ASM960 +(depending upon the configured target) assembler from Microtec Research. The +exact nature of the MRI syntax will not be documented here; see the MRI manuals +for more information. Note in particular that the handling of macros and macro +arguments is somewhat different. The purpose of this option is to permit assembling +existing MRI assembler code using +.Xr as . +.Pp +The MRI compatibility is not complete. Certain operations of the MRI assembler +depend upon its object file format, and can not be supported using other object +file formats. Supporting these would require enhancing each object file format +individually. These are: +.Pp +.Bl -bullet +.It +global symbols in common section +.Pp +The m68k MRI assembler supports common sections which are merged by the linker. +Other object file formats do not support this. +.Xr as +handles common sections by treating them as a single common symbol. It permits +local symbols to be defined within a common section, but it can not support +global symbols, since it has no way to describe them. +.Pp +.It +complex relocations +.Pp +The MRI assemblers support relocations against a negated section address, +and relocations which combine the start addresses of two or more sections. +These are not support by other object file formats. +.Pp +.It +.Li END +pseudo-op specifying start address +.Pp +The MRI +.Li END +pseudo-op permits the specification of a start address. This is not supported +by other object file formats. The start address may instead be specified using +the +.Op -e +option to the linker, or in a linker script. +.Pp +.It +.Li IDNT , +.Li .ident +and +.Li NAME +pseudo-ops +.Pp +The MRI +.Li IDNT , +.Li .ident +and +.Li NAME +pseudo-ops assign a module name to the output file. This is not supported +by other object file formats. +.Pp +.It +.Li ORG +pseudo-op +.Pp +The m68k MRI +.Li ORG +pseudo-op begins an absolute section at a given address. This differs from +the usual +.Xr as +.Li .org +pseudo-op, which changes the location within the current section. Absolute +sections are not supported by other object file formats. The address of a +section may be assigned within a linker script. +.El +.Pp +There are some other features of the MRI assembler which are not supported +by +.Xr as , +typically either because they are difficult or because they seem of little +consequence. Some of these may be supported in future releases. +.Pp +.Bl -bullet +.It +EBCDIC strings +.Pp +EBCDIC strings are not supported. +.Pp +.It +packed binary coded decimal +.Pp +Packed binary coded decimal is not supported. This means that the +.Li DC.P +and +.Li DCB.P +pseudo-ops are not supported. +.Pp +.It +.Li FEQU +pseudo-op +.Pp +The m68k +.Li FEQU +pseudo-op is not supported. +.Pp +.It +.Li NOOBJ +pseudo-op +.Pp +The m68k +.Li NOOBJ +pseudo-op is not supported. +.Pp +.It +.Li OPT +branch control options +.Pp +The m68k +.Li OPT +branch control options--- +.Li B , +.Li BRS , +.Li BRB , +.Li BRL , +and +.Li BRW +---are ignored. +.Xr as +automatically relaxes all branches, whether forward or backward, to an appropriate +size, so these options serve no purpose. +.Pp +.It +.Li OPT +list control options +.Pp +The following m68k +.Li OPT +list control options are ignored: +.Li C , +.Li CEX , +.Li CL , +.Li CRE , +.Li E , +.Li G , +.Li I , +.Li M , +.Li MEX , +.Li MC , +.Li MD , +.Li X . +.Pp +.It +other +.Li OPT +options +.Pp +The following m68k +.Li OPT +options are ignored: +.Li NEST , +.Li O , +.Li OLD , +.Li OP , +.Li P , +.Li PCO , +.Li PCR , +.Li PCS , +.Li R . +.Pp +.It +.Li OPT +.Li D +option is default +.Pp +The m68k +.Li OPT +.Li D +option is the default, unlike the MRI assembler. +.Li OPT NOD +may be used to turn it off. +.Pp +.It +.Li XREF +pseudo-op. +.Pp +The m68k +.Li XREF +pseudo-op is ignored. +.Pp +.It +.Li .debug +pseudo-op +.Pp +The i960 +.Li .debug +pseudo-op is not supported. +.Pp +.It +.Li .extended +pseudo-op +.Pp +The i960 +.Li .extended +pseudo-op is not supported. +.Pp +.It +.Li .list +pseudo-op. +.Pp +The various options of the i960 +.Li .list +pseudo-op are not supported. +.Pp +.It +.Li .optimize +pseudo-op +.Pp +The i960 +.Li .optimize +pseudo-op is not supported. +.Pp +.It +.Li .output +pseudo-op +.Pp +The i960 +.Li .output +pseudo-op is not supported. +.Pp +.It +.Li .setreal +pseudo-op +.Pp +The i960 +.Li .setreal +pseudo-op is not supported. +.Pp +.El +.Ss Dependency Tracking: Op --MD +.Xr as +can generate a dependency file for the file it creates. This file consists +of a single rule suitable for +.Li make +describing the dependencies of the main source file. +.Pp +The rule is written to the file named in its argument. +.Pp +This feature is used in the automatic updating of makefiles. +.Pp +.Ss Name the Object File: Op -o +There is always one object file output when you run +.Xr as . +By default it has the name +.Pa a.out . +You use this option (which takes exactly one filename) to give the object +file a different name. +.Pp +Whatever the object file is called, +.Xr as +overwrites any existing file of the same name. +.Pp +.Ss Join Data and Text Sections: Op -R +.Op -R +tells +.Xr as +to write the object file as if all data-section data lives in the text section. +This is only done at the very last moment: your binary data are the same, +but data section parts are relocated differently. The data section part of +your object file is zero bytes long because all its bytes are appended to +the text section. (See Section +.Dq Sections . ) +.Pp +When you specify +.Op -R +it would be possible to generate shorter address displacements (because we +do not have to cross between text and data section). We refrain from doing +this simply for compatibility with older versions of +.Xr as . +In future, +.Op -R +may work this way. +.Pp +When +.Xr as +is configured for COFF or ELF output, this option is only useful if you use +sections named +.Li .text +and +.Li .data . +.Pp +.Ss Display Assembly Statistics: Op --statistics +Use +.Li --statistics +to display two statistics about the resources used by +.Xr as : +the maximum amount of space allocated during the assembly (in bytes), and +the total execution time taken for the assembly (in cpu seconds). +.Pp +.Ss Compatible Output: Op --traditional-format +For some targets, the output of +.Xr as +is different in some ways from the output of some existing assembler. This +switch requests +.Xr as +to use the traditional format instead. +.Pp +For example, it disables the exception frame optimizations which +.Xr as +normally does by default on +.Li gcc +output. +.Pp +.Ss Announce Version: Op -v +You can find out what version of as is running by including the option +.Li -v +(which you can also spell as +.Li -version ) +on the command line. +.Pp +.Ss Control Warnings: Op -W, Op --warn, Op --no-warn, Op --fatal-warnings +.Xr as +should never give a warning or error message when assembling compiler output. +But programs written by people often cause +.Xr as +to give a warning that a particular assumption was made. All such warnings +are directed to the standard error file. +.Pp +If you use the +.Op -W +and +.Op --no-warn +options, no warnings are issued. This only affects the warning messages: it +does not change any particular of how +.Xr as +assembles your file. Errors, which stop the assembly, are still reported. +.Pp +If you use the +.Op --fatal-warnings +option, +.Xr as +considers files that generate warnings to be in error. +.Pp +You can switch these options off again by specifying +.Op --warn , +which causes warnings to be output as usual. +.Pp +.Ss Generate Object File in Spite of Errors: Op -Z +After an error message, +.Xr as +normally produces no output. If for some reason you are interested in object +file output even after +.Xr as +gives an error message on your program, use the +.Li -Z +option. If there are any errors, +.Xr as +continues anyways, and writes an object file after a final warning message +of the form +.Li Va n errors, Va m warnings, generating bad object file. +.Pp +.Sh Syntax +This chapter describes the machine-independent syntax allowed in a source +file. +.Xr as +syntax is similar to what many other assemblers use; it is inspired by the +BSD 4.2 assembler. +.Pp +.Ss Preprocessing +The +.Xr as +internal preprocessor: +.Bl -bullet +.It +adjusts and removes extra whitespace. It leaves one space or tab before the +keywords on a line, and turns any other whitespace on the line into a single +space. +.Pp +.It +removes all comments, replacing them with a single space, or an appropriate +number of newlines. +.Pp +.It +converts character constants into the appropriate numeric values. +.El +.Pp +It does not do macro processing, include file handling, or anything else you +may get from your C compiler's preprocessor. You can do include file processing +with the +.Li .include +directive (see Section +.Dq Include ) . +You can use the GNU C compiler driver to get other \(lqCPP\(rq style preprocessing +by giving the input file a +.Li .S +suffix.See Section +.Dq Overall Options . +.Pp +Excess whitespace, comments, and character constants cannot be used in the +portions of the input text that are not preprocessed. +.Pp +If the first line of an input file is +.Li #NO_APP +or if you use the +.Li -f +option, whitespace and comments are not removed from the input file. Within +an input file, you can ask for whitespace and comment removal in specific +portions of the by putting a line that says +.Li #APP +before the text that may contain whitespace or comments, and putting a line +that says +.Li #NO_APP +after this text. This feature is mainly intend to support +.Li asm +statements in compilers whose output is otherwise free of comments and whitespace. +.Pp +.Ss Whitespace +.Em Whitespace +is one or more blanks or tabs, in any order. Whitespace is used to separate +symbols, and to make programs neater for people to read. Unless within character +constants (see Section +.Dq Characters ) , +any whitespace means the same as exactly one space. +.Pp +.Ss Comments +There are two ways of rendering comments to +.Xr as . +In both cases the comment is equivalent to one space. +.Pp +Anything from +.Li /* +through the next +.Li */ +is a comment. This means you may not nest these comments. +.Pp +.Bd -literal -offset indent +/* + The only way to include a newline ('\en') in a comment + is to use this sort of comment. +*/ + +/* This sort of comment does not nest. */ +.Ed +.Pp +Anything from the +.Em line comment +character to the next newline is considered a comment and is ignored. The +line comment character is +.Li @ +on the ARM; +.Li # +on the i386 and x86-64; +.Li # +for Motorola PowerPC; +.Li ! +on the SPARC; see Machine Dependencies. +.Pp +To be compatible with past assemblers, lines that begin with +.Li # +have a special interpretation. Following the +.Li # +should be an absolute expression (see Section +.Dq Expressions ) : +the logical line number of the +.Em next +line. Then a string (see Section +.Dq Strings ) +is allowed: if present it is a new logical file name. The rest of the line, +if any, should be whitespace. +.Pp +If the first non-whitespace characters on the line are not numeric, the line +is ignored. (Just like a comment.) +.Pp +.Bd -literal -offset indent + # This is an ordinary comment. +# 42-6 "new_file_name" # New logical file name + # This is logical line # 36. +.Ed +This feature is deprecated, and may disappear from future versions of +.Xr as . +.Pp +.Ss Symbols +A +.Em symbol +is one or more characters chosen from the set of all letters (both upper and +lower case), digits and the three characters +.Li _.$ . +No symbol may begin with a digit. Case is significant. There is no length +limit: all characters are significant. Symbols are delimited by characters +not in that set, or by the beginning of a file (since the source program must +end with a newline, the end of a file is not a possible symbol delimiter).See Section +.Dq Symbols . +.Pp +.Ss Statements +A +.Em statement +ends at a newline character ( +.Li \en ) +or at a semicolon ( +.Li ; ) . +The newline or semicolon is considered part of the preceding statement. Newlines +and semicolons within character constants are an exception: they do not end +statements. +.Pp +It is an error to end any statement with end-of-file: the last character of +any input file should be a newline. +.Pp +An empty statement is allowed, and may include whitespace. It is ignored. +.Pp +A statement begins with zero or more labels, optionally followed by a key +symbol which determines what kind of statement it is. The key symbol determines +the syntax of the rest of the statement. If the symbol begins with a dot +.Li . +then the statement is an assembler directive: typically valid for any computer. +If the symbol begins with a letter the statement is an assembly language +.Em instruction : +it assembles into a machine language instruction. +.Pp +A label is a symbol immediately followed by a colon ( +.Li : ) . +Whitespace before a label or after a colon is permitted, but you may not have +whitespace between a label's symbol and its colon.See Section +.Dq Labels . +.Pp +.Bd -literal -offset indent +label: .directive followed by something +another_label: # This is an empty statement. + instruction operand_1, operand_2, ... +.Ed +.Pp +.Ss Constants +A constant is a number, written so that its value is known by inspection, +without knowing any context. Like this: +.Bd -literal -offset indent + +\&.byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\eJ # All the same value. +\&.ascii "Ring the bell\e7" # A string constant. +\&.octa 0x123456789abcdef0123456789ABCDEF0 # A biGNUm. +\&.float 0f-314159265358979323846264338327\e +95028841971.693993751E-40 # - pi, a flonum. + +.Ed +.Pp +.Em Character Constants +.Pp +There are two kinds of character constants. A +.Em character +stands for one character in one byte and its value may be used in numeric +expressions. String constants (properly called string +.Em literals ) +are potentially many bytes and their values may not be used in arithmetic +expressions. +.Pp +.No Strings +.Pp +A +.Em string +is written between double-quotes. It may contain double-quotes or null characters. +The way to get special characters into a string is to +.Em escape +these characters: precede them with a backslash +.Li \e +character. For example +.Li \e\e +represents one backslash: the first +.Li \e +is an escape which tells +.Xr as +to interpret the second character literally as a backslash (which prevents +.Xr as +from recognizing the second +.Li \e +as an escape character). The complete list of escapes follows. +.Pp +.Bl -tag -width Ds +.It \eb +Mnemonic for backspace; for ASCII this is octal code 010. +.Pp +.It \ef +Mnemonic for FormFeed; for ASCII this is octal code 014. +.Pp +.It \en +Mnemonic for newline; for ASCII this is octal code 012. +.Pp +.It \er +Mnemonic for carriage-Return; for ASCII this is octal code 015. +.Pp +.It \et +Mnemonic for horizontal Tab; for ASCII this is octal code 011. +.Pp +.It \e Va digit Va digit Va digit +An octal character code. The numeric code is 3 octal digits. For compatibility +with other Unix systems, 8 and 9 are accepted as digits: for example, +.Li \e008 +has the value 010, and +.Li \e009 +the value 011. +.Pp +.It \e Li x Va hex-digits... +A hex character code. All trailing hex digits are combined. Either upper or +lower case +.Li x +works. +.Pp +.It \e\e +Represents one +.Li \e +character. +.Pp +.It \e" +Represents one +.Li " +character. Needed in strings to represent this character, because an unescaped +.Li " +would end the string. +.Pp +.It \e Va anything-else +Any other character when escaped by +.Li \e +gives a warning, but assembles as if the +.Li \e +was not present. The idea is that if you used an escape sequence you clearly +didn't want the literal interpretation of the following character. However +.Xr as +has no other interpretation, so +.Xr as +knows it is giving you the wrong code and warns you of the fact. +.El +.Pp +Which characters are escapable, and what those escapes represent, varies widely +among assemblers. The current set is what we think the BSD 4.2 assembler recognizes, +and is a subset of what most C compilers recognize. If you are in doubt, do +not use an escape sequence. +.Pp +.No Characters +.Pp +A single character may be written as a single quote immediately followed by +that character. The same escapes apply to characters as to strings. So if +you want to write the character backslash, you must write +.Li '\e\e +where the first +.Li \e +escapes the second +.Li \e . +As you can see, the quote is an acute accent, not a grave accent. A newline +(or semicolon +.Li ; ) +immediately following an acute accent is taken as a literal character and +does not count as the end of a statement. The value of a character constant +in a numeric expression is the machine's byte-wide code for that character. +.Xr as +assumes your character code is ASCII: +.Li 'A +means 65, +.Li 'B +means 66, and so on. +.Pp +.Em Number Constants +.Pp +.Xr as +distinguishes three kinds of numbers according to how they are stored in the +target machine. +.Em Integers +are numbers that would fit into an +.Li int +in the C language. +.Em BiGNUms +are integers, but they are stored in more than 32 bits. +.Em Flonums +are floating point numbers, described below. +.Pp +.No Integers +.Pp +A binary integer is +.Li 0b +or +.Li 0B +followed by zero or more of the binary digits +.Li 01 . +.Pp +An octal integer is +.Li 0 +followed by zero or more of the octal digits ( +.Li 01234567 ) . +.Pp +A decimal integer starts with a non-zero digit followed by zero or more digits +( +.Li 0123456789 ) . +.Pp +A hexadecimal integer is +.Li 0x +or +.Li 0X +followed by one or more hexadecimal digits chosen from +.Li 0123456789abcdefABCDEF . +.Pp +Integers have the usual values. To denote a negative integer, use the prefix +operator +.Li - +discussed under expressions (see Section +.Dq Prefix Ops ) . +.Pp +.No BiGNUms +.Pp +A +.Em biGNUm +has the same syntax and semantics as an integer except that the number (or +its negative) takes more than 32 bits to represent in binary. The distinction +is made because in some places integers are permitted while biGNUms are not. +.Pp +.No Flonums +.Pp +A +.Em flonum +represents a floating point number. The translation is indirect: a decimal +floating point number from the text is converted by +.Xr as +to a generic binary floating point number of more than sufficient precision. +This generic floating point number is converted to a particular computer's +floating point format (or formats) by a portion of +.Xr as +specialized to that computer. +.Pp +A flonum is written by writing (in order) +.Bl -bullet +.It +The digit +.Li 0 . +.Pp +.It +A letter, to tell +.Xr as +the rest of the number is a flonum. +.Pp +.It +An optional sign: either +.Li + +or +.Li - . +.Pp +.It +An optional +.Em integer part : +zero or more decimal digits. +.Pp +.It +An optional +.Em fractional part : +.Li . +followed by zero or more decimal digits. +.Pp +.It +An optional exponent, consisting of: +.Pp +.Bl -bullet +.It +An +.Li E +or +.Li e . +.It +Optional sign: either +.Li + +or +.Li - . +.It +One or more decimal digits. +.El +.Pp +.El +At least one of the integer part or the fractional part must be present. The +floating point number has the usual base-10 value. +.Pp +.Xr as +does all processing using integers. Flonums are computed independently of +any floating point hardware in the computer running +.Xr as . +.Pp +.Sh Sections and Relocation +.Ss Background +Roughly, a section is a range of addresses, with no gaps; all data \(lqin\(rq those +addresses is treated the same for some particular purpose. For example there +may be a \(lqread only\(rq section. +.Pp +The linker +.Li ld +reads many object files (partial programs) and combines their contents to +form a runnable program. When +.Xr as +emits an object file, the partial program is assumed to start at address 0. +.Li ld +assigns the final addresses for the partial program, so that different partial +programs do not overlap. This is actually an oversimplification, but it suffices +to explain how +.Xr as +uses sections. +.Pp +.Li ld +moves blocks of bytes of your program to their run-time addresses. These blocks +slide to their run-time addresses as rigid units; their length does not change +and neither does the order of bytes within them. Such a rigid unit is called +a +.Em section . +Assigning run-time addresses to sections is called +.Em relocation . +It includes the task of adjusting mentions of object-file addresses so they +refer to the proper run-time addresses. +.Pp +An object file written by +.Xr as +has at least three sections, any of which may be empty. These are named +.Em text , +.Em data +and +.Em bss +sections. +.Pp +.Xr as +can also generate whatever other named sections you specify using the +.Li .section +directive (see Section +.Dq Section ) . +If you do not use any directives that place output in the +.Li .text +or +.Li .data +sections, these sections still exist, but are empty. +.Pp +Within the object file, the text section starts at address +.Li 0 , +the data section follows, and the bss section follows the data section. +.Pp +To let +.Li ld +know which data changes when the sections are relocated, and how to change +that data, +.Xr as +also writes to the object file details of the relocation needed. To perform +relocation +.Li ld +must know, each time an address in the object file is mentioned: +.Bl -bullet +.It +Where in the object file is the beginning of this reference to an address? +.It +How long (in bytes) is this reference? +.It +Which section does the address refer to? What is the numeric value of +.Bd -filled -offset indent +( +.Va address ) +\-( +.Va start-address of section ) ? +.Ed +.It +Is the reference to an address \(lqProgram-Counter relative\(rq? +.El +.Pp +In fact, every address +.Xr as +ever uses is expressed as +.Bd -filled -offset indent +( +.Va section ) ++ ( +.Va offset into section ) +.Ed +Further, most expressions +.Xr as +computes have this section-relative nature. +.Pp +In this manual we use the notation { +.Va secname +.Va N +}to mean \(lqoffset +.Va N +into section +.Va secname +\&.\(rq +.Pp +Apart from text, data and bss sections you need to know about the +.Em absolute +section. When +.Li ld +mixes partial programs, addresses in the absolute section remain unchanged. +For example, address +.Li {absolute 0} +is \(lqrelocated\(rq to run-time address 0 by +.Li ld . +Although the linker never arranges two partial programs' data sections with +overlapping addresses after linking, +.Em by definition +their absolute sections must overlap. Address +.Li {absolute 239} +in one part of a program is always the same address when the program is running +as address +.Li {absolute 239} +in any other part of the program. +.Pp +The idea of sections is extended to the +.Em undefined +section. Any address whose section is unknown at assembly time is by definition +rendered {undefined +.Va U +}---where +.Va U +is filled in later. Since numbers are always defined, the only way to generate +an undefined address is to mention an undefined symbol. A reference to a named +common block would be such a symbol: its value is unknown at assembly time +so it has section +.Em undefined . +.Pp +By analogy the word +.Em section +is used to describe groups of sections in the linked program. +.Li ld +puts all partial programs' text sections in contiguous addresses in the linked +program. It is customary to refer to the +.Em text section +of a program, meaning all the addresses of all partial programs' text sections. +Likewise for data and bss sections. +.Pp +Some sections are manipulated by +.Li ld ; +others are invented for use of +.Xr as +and have no meaning except during assembly. +.Pp +.Ss Linker Sections +.Li ld +deals with just four kinds of sections, summarized below. +.Pp +.Bl -tag -width Ds +.It named sections +These sections hold your program. +.Xr as +and +.Li ld +treat them as separate but equal sections. Anything you can say of one section +is true of another. When the program is running, however, it is customary +for the text section to be unalterable. The text section is often shared among +processes: it contains instructions, constants and the like. The data section +of a running program is usually alterable: for example, C variables would +be stored in the data section. +.Pp +.It bss section +This section contains zeroed bytes when your program begins running. It is +used to hold uninitialized variables or common storage. The length of each +partial program's bss section is important, but because it starts out containing +zeroed bytes there is no need to store explicit zero bytes in the object file. +The bss section was invented to eliminate those explicit zeros from object +files. +.Pp +.It absolute section +Address 0 of this section is always \(lqrelocated\(rq to runtime address 0. This is +useful if you want to refer to an address that +.Li ld +must not change when relocating. In this sense we speak of absolute addresses +being \(lqunrelocatable\(rq: they do not change during relocation. +.Pp +.It undefined section +This \(lqsection\(rq is a catch-all for address references to objects not in the preceding +sections. +.El +.Pp +An idealized example of three relocatable sections follows. The example uses +the traditional section names +.Li .text +and +.Li .data . +Memory addresses are on the horizontal axis. +.Pp +.Bd -literal -offset indent + +-----+----+--+ +partial program # 1: |ttttt|dddd|00| + +-----+----+--+ + + text data bss + seg. seg. seg. + + +---+---+---+ +partial program # 2: |TTT|DDD|000| + +---+---+---+ + + +--+---+-----+--+----+---+-----+~~ +linked program: | |TTT|ttttt| |dddd|DDD|00000| + +--+---+-----+--+----+---+-----+~~ + + addresses: 0 ... +.Ed +.Pp +.Ss Assembler Internal Sections +These sections are meant only for the internal use of +.Xr as . +They have no meaning at run-time. You do not really need to know about these +sections for most purposes; but they can be mentioned in +.Xr as +warning messages, so it might be helpful to have an idea of their meanings +to +.Xr as . +These sections are used to permit the value of every expression in your assembly +language program to be a section-relative address. +.Pp +.Bl -tag -width Ds +.It ASSEMBLER-INTERNAL-LOGIC-ERROR! +An internal assembler logic error has been found. This means there is a bug +in the assembler. +.Pp +.It expr section +The assembler stores complex expression internally as combinations of symbols. +When it needs to represent an expression as a symbol, it puts it in the expr +section. +.El +.Pp +.Ss Sub-Sections +You may have separate groups of data in named sections that you want to end +up near to each other in the object file, even though they are not contiguous +in the assembler source. +.Xr as +allows you to use +.Em subsections +for this purpose. Within each section, there can be numbered subsections with +values from 0 to 8192. Objects assembled into the same subsection go into +the object file together with other objects in the same subsection. For example, +a compiler might want to store constants in the text section, but might not +want to have them interspersed with the program being assembled. In this case, +the compiler could issue a +.Li .text 0 +before each section of code being output, and a +.Li .text 1 +before each group of constants being output. +.Pp +Subsections are optional. If you do not use subsections, everything goes in +subsection number zero. +.Pp +Subsections appear in your object file in numeric order, lowest numbered to +highest. (All this to be compatible with other people's assemblers.) The object +file contains no representation of subsections; +.Li ld +and other programs that manipulate object files see no trace of them. They +just see all your text subsections as a text section, and all your data subsections +as a data section. +.Pp +To specify which subsection you want subsequent statements assembled into, +use a numeric argument to specify it, in a +.Li .text Va expression +or a +.Li .data Va expression +statement. You can also use the +.Li .subsection +directive (see Section +.Dq SubSection ) +to specify a subsection: +.Li .subsection Va expression . +.Va Expression +should be an absolute expression (see Section +.Dq Expressions ) . +If you just say +.Li .text +then +.Li .text 0 +is assumed. Likewise +.Li .data +means +.Li .data 0 . +Assembly begins in +.Li text 0 . +For instance: +.Bd -literal -offset indent +\&.text 0 # The default subsection is text 0 anyway. +\&.ascii "This lives in the first text subsection. *" +\&.text 1 +\&.ascii "But this lives in the second text subsection." +\&.data 0 +\&.ascii "This lives in the data section," +\&.ascii "in the first data subsection." +\&.text 0 +\&.ascii "This lives in the first text section," +\&.ascii "immediately following the asterisk (*)." +.Ed +.Pp +Each section has a +.Em location counter +incremented by one for every byte assembled into that section. Because subsections +are merely a convenience restricted to +.Xr as +there is no concept of a subsection location counter. There is no way to directly +manipulate a location counter---but the +.Li .align +directive changes it, and any label definition captures its current value. +The location counter of the section where statements are being assembled is +said to be the +.Em active +location counter. +.Pp +.Ss bss Section +The bss section is used for local common variable storage. You may allocate +address space in the bss section, but you may not dictate data to load into +it before your program executes. When your program starts running, all the +contents of the bss section are zeroed bytes. +.Pp +The +.Li .lcomm +pseudo-op defines a symbol in the bss section; see Lcomm,, +.Li .lcomm +\&. +.Pp +The +.Li .comm +pseudo-op may be used to declare a common symbol, which is another form of +uninitialized symbol; see Comm,, +.Li .comm +\&. +.Pp +.Sh Symbols +Symbols are a central concept: the programmer uses symbols to name things, +the linker uses symbols to link, and the debugger uses symbols to debug. +.Pp +.Qo +.Em Warning: +.Xr as +does not place symbols in the object file in the same order they were declared. +This may break some debuggers. +.Qc +.Pp +.Ss Labels +A +.Em label +is written as a symbol immediately followed by a colon +.Li : . +The symbol then represents the current value of the active location counter, +and is, for example, a suitable instruction operand. You are warned if you +use the same symbol to represent two different locations: the first definition +overrides any other definitions. +.Pp +.Ss Giving Symbols Other Values +A symbol can be given an arbitrary value by writing a symbol, followed by +an equals sign +.Li = , +followed by an expression (see Section +.Dq Expressions ) . +This is equivalent to using the +.Li .set +directive.See Section +.Dq Set . +In the same way, using a double equals sign +.Li = +.Li = +here represents an equivalent of the +.Li .eqv +directive.See Section +.Dq Eqv . +.Pp +.Ss Symbol Names +Symbol names begin with a letter or with one of +.Li ._ . +On most machines, you can also use +.Li $ +in symbol names; exceptions are noted in Machine Dependencies. That character +may be followed by any string of digits, letters, dollar signs (unless otherwise +noted for a particular target machine), and underscores. +.Pp +Case of letters is significant: +.Li foo +is a different symbol name than +.Li Foo . +.Pp +Each symbol has exactly one name. Each name in an assembly language program +refers to exactly one symbol. You may use that symbol name any number of times +in a program. +.Pp +.Em Local Symbol Names +.Pp +A local symbol is any symbol beginning with certain local label prefixes. +By default, the local label prefix is +.Li .L +for ELF systems or +.Li L +for traditional a.out systems, but each target may have its own set of local +label prefixes. +.Pp +Local symbols are defined and used within the assembler, but they are normally +not saved in object files. Thus, they are not visible when debugging. You +may use the +.Li -L +option (see Section +.Dq L ) +to retain the local symbols in the object files. +.Pp +.Em Local Labels +.Pp +Local labels help compilers and programmers use names temporarily. They create +symbols which are guaranteed to be unique over the entire scope of the input +source code and which can be referred to by a simple notation. To define a +local label, write a label of the form +.Li Sy N: +(where +.Sy N +represents any positive integer). To refer to the most recent previous definition +of that label write +.Li Sy Nb , +using the same number as when you defined the label. To refer to the next +definition of a local label, write +.Li Sy Nf +---the +.Li b +stands for \(lqbackwards\(rq and the +.Li f +stands for \(lqforwards\(rq. +.Pp +There is no restriction on how you can use these labels, and you can reuse +them too. So that it is possible to repeatedly define the same local label +(using the same number +.Li Sy N ) , +although you can only refer to the most recently defined local label of that +number (for a backwards reference) or the next definition of a specific local +label for a forward reference. It is also worth noting that the first 10 local +labels ( +.Li Sy 0: +\&....Li Sy 9: ) +are implemented in a slightly more efficient manner than the others. +.Pp +Here is an example: +.Pp +.Bd -literal -offset indent +1: branch 1f +2: branch 1b +1: branch 2f +2: branch 1b +.Ed +.Pp +Which is the equivalent of: +.Pp +.Bd -literal -offset indent +label_1: branch label_3 +label_2: branch label_1 +label_3: branch label_4 +label_4: branch label_3 +.Ed +.Pp +Local label names are only a notational device. They are immediately transformed +into more conventional symbol names before the assembler uses them. The symbol +names are stored in the symbol table, appear in error messages, and are optionally +emitted to the object file. The names are constructed using these parts: +.Pp +.Bl -tag -width Ds +.It Em local label prefix +All local symbols begin with the system-specific local label prefix. Normally +both +.Xr as +and +.Li ld +forget symbols that start with the local label prefix. These labels are used +for symbols you are never intended to see. If you use the +.Li -L +option then +.Xr as +retains these symbols in the object file. If you also instruct +.Li ld +to retain these symbols, you may use them in debugging. +.Pp +.It Va number +This is the number that was used in the local label definition. So if the +label is written +.Li 55: +then the number is +.Li 55 . +.Pp +.It Li C-B +This unusual character is included so you do not accidentally invent a symbol +of the same name. The character has ASCII value of +.Li \e002 +(control-B). +.Pp +.It Em ordinal number +This is a serial number to keep the labels distinct. The first definition +of +.Li 0: +gets the number +.Li 1 . +The 15th definition of +.Li 0: +gets the number +.Li 15 , +and so on. Likewise the first definition of +.Li 1: +gets the number +.Li 1 +and its 15th definition gets +.Li 15 +as well. +.El +.Pp +So for example, the first +.Li 1: +may be named +.Li .L1 Li C-B1 , +and the 44th +.Li 3: +may be named +.Li .L3 Li C-B44 . +.Pp +.Em Dollar Local Labels +.Pp +.Li as +also supports an even more local form of local labels called dollar labels. +These labels go out of scope (i.e., they become undefined) as soon as a non-local +label is defined. Thus they remain valid for only a small region of the input +source code. Normal local labels, by contrast, remain in scope for the entire +file, or until they are redefined by another occurrence of the same local +label. +.Pp +Dollar labels are defined in exactly the same way as ordinary local labels, +except that instead of being terminated by a colon, they are terminated by +a dollar sign, e.g., +.Li Sy 55$ . +.Pp +They can also be distinguished from ordinary local labels by their transformed +names which use ASCII character +.Li \e001 +(control-A) as the magic character to distinguish them from ordinary labels. +For example, the fifth definition of +.Li 6$ +may be named +.Li .L6 Li C-A5 . +.Pp +.Ss The Special Dot Symbol +The special symbol +.Li . +refers to the current address that +.Xr as +is assembling into. Thus, the expression +.Li melvin: .long . +defines +.Li melvin +to contain its own address. Assigning a value to +.Li . +is treated the same as a +.Li .org +directive. Thus, the expression +.Li .=.+4 +is the same as saying +.Li .space 4 . +.Pp +.Ss Symbol Attributes +Every symbol has, as well as its name, the attributes \(lqValue\(rq and \(lqType\(rq. Depending +on output format, symbols can also have auxiliary attributes. The detailed +definitions are in +.Pa a.out.h . +.Pp +If you use a symbol without defining it, +.Xr as +assumes zero for all these attributes, and probably won't warn you. This makes +the symbol an externally defined symbol, which is generally what you would +want. +.Pp +.Em Value +.Pp +The value of a symbol is (usually) 32 bits. For a symbol which labels a location +in the text, data, bss or absolute sections the value is the number of addresses +from the start of that section to the label. Naturally for text, data and +bss sections the value of a symbol changes as +.Li ld +changes section base addresses during linking. Absolute symbols' values do +not change during linking: that is why they are called absolute. +.Pp +The value of an undefined symbol is treated in a special way. If it is 0 then +the symbol is not defined in this assembler source file, and +.Li ld +tries to determine its value from other files linked into the same program. +You make this kind of symbol simply by mentioning a symbol name without defining +it. A non-zero value represents a +.Li .comm +common declaration. The value is how much common storage to reserve, in bytes +(addresses). The symbol refers to the first address of the allocated storage. +.Pp +.Em Type +.Pp +The type attribute of a symbol contains relocation (section) information, +any flag settings indicating that a symbol is external, and (optionally), +other information for linkers and debuggers. The exact format depends on the +object-code output format in use. +.Pp +.Sh Expressions +An +.Em expression +specifies an address or numeric value. Whitespace may precede and/or follow +an expression. +.Pp +The result of an expression must be an absolute number, or else an offset +into a particular section. If an expression is not absolute, and there is +not enough information when +.Xr as +sees the expression to know its section, a second pass over the source program +might be necessary to interpret the expression---but the second pass is currently +not implemented. +.Xr as +aborts with an error message in this situation. +.Pp +.Ss Empty Expressions +An empty expression has no value: it is just whitespace or null. Wherever +an absolute expression is required, you may omit the expression, and +.Xr as +assumes a value of (absolute) 0. This is compatible with other assemblers. +.Pp +.Ss Integer Expressions +An +.Em integer expression +is one or more +.Em arguments +delimited by +.Em operators . +.Pp +.Em Arguments +.Pp +.Em Arguments +are symbols, numbers or subexpressions. In other contexts arguments are sometimes +called \(lqarithmetic operands\(rq. In this manual, to avoid confusing them with the +\(lqinstruction operands\(rq of the machine language, we use the term \(lqargument\(rq to +refer to parts of expressions only, reserving the word \(lqoperand\(rq to refer only +to machine instruction operands. +.Pp +Symbols are evaluated to yield { +.Va section +.Va NNN +}where +.Va section +is one of text, data, bss, absolute, or undefined. +.Va NNN +is a signed, 2's complement 32 bit integer. +.Pp +Numbers are usually integers. +.Pp +A number can be a flonum or biGNUm. In this case, you are warned that only +the low order 32 bits are used, and +.Xr as +pretends these 32 bits are an integer. You may write integer-manipulating +instructions that act on exotic constants, compatible with other assemblers. +.Pp +Subexpressions are a left parenthesis +.Li ( +followed by an integer expression, followed by a right parenthesis +.Li ) ; +or a prefix operator followed by an argument. +.Pp +.Em Operators +.Pp +.Em Operators +are arithmetic functions, like +.Li + +or +.Li % . +Prefix operators are followed by an argument. Infix operators appear between +their arguments. Operators may be preceded and/or followed by whitespace. +.Pp +.Em Prefix Operator +.Pp +.Xr as +has the following +.Em prefix operators . +They each take one argument, which must be absolute. +.Pp +.Bl -tag -width Ds +.It - +.Em Negation . +Two's complement negation. +.It ~ +.Em Complementation . +Bitwise not. +.El +.Pp +.Em Infix Operators +.Pp +.Em Infix operators +take two arguments, one on either side. Operators have precedence, but operations +with equal precedence are performed left to right. Apart from +.Li + +or +.Op - , +both arguments must be absolute, and the result is absolute. +.Pp +.Bl -enum +.It +Highest Precedence +.Pp +.Bl -tag -width Ds +.It * +.Em Multiplication . +.Pp +.It / +.Em Division . +Truncation is the same as the C operator +.Li / +.Pp +.It % +.Em Remainder . +.Pp +.It << +.Em Shift Left . +Same as the C operator +.Li << . +.Pp +.It >> +.Em Shift Right . +Same as the C operator +.Li >> . +.El +.Pp +.It +Intermediate precedence +.Pp +.Bl -tag -width Ds +.It | +.Pp +.Em Bitwise Inclusive Or . +.Pp +.It & +.Em Bitwise And . +.Pp +.It ^ +.Em Bitwise Exclusive Or . +.Pp +.It ! +.Em Bitwise Or Not . +.El +.Pp +.It +Low Precedence +.Pp +.Bl -tag -width Ds +.It + +.Em Addition . +If either argument is absolute, the result has the section of the other argument. +You may not add together arguments from different sections. +.Pp +.It - +.Em Subtraction . +If the right argument is absolute, the result has the section of the left +argument. If both arguments are in the same section, the result is absolute. +You may not subtract arguments from different sections. +.Pp +.It == +.Em Is Equal To +.It <> +.It != +.Em Is Not Equal To +.It < +.Em Is Less Than +.It > +.Em Is Greater Than +.It >= +.Em Is Greater Than Or Equal To +.It <= +.Em Is Less Than Or Equal To +.Pp +The comparison operators can be used as infix operators. A true results has +a value of -1 whereas a false result has a value of 0. Note, these operators +perform signed comparisons. +.El +.Pp +.It +Lowest Precedence +.Pp +.Bl -tag -width Ds +.It && +.Em Logical And . +.Pp +.It || +.Em Logical Or . +.Pp +These two logical operations can be used to combine the results of sub expressions. +Note, unlike the comparison operators a true result returns a value of 1 but +a false results does still return 0. Also note that the logical or operator +has a slightly lower precedence than logical and. +.Pp +.El +.El +In short, it's only meaningful to add or subtract the +.Em offsets +in an address; you can only have a defined section in one of the two arguments. +.Pp +.Sh Assembler Directives +All assembler directives have names that begin with a period ( +.Li . ) . +The rest of the name is letters, usually in lower case. +.Pp +This chapter discusses directives that are available regardless of the target +machine configuration for the GNU assembler. +.Pp +.Ss Li .abort +This directive stops the assembly immediately. It is for compatibility with +other assemblers. The original idea was that the assembly language source +would be piped into the assembler. If the sender of the source quit, it could +use this directive tells +.Xr as +to quit also. One day +.Li .abort +will not be supported. +.Pp +.Ss Li .align Va abs-expr, Va abs-expr, Va abs-expr +Pad the location counter (in the current subsection) to a particular storage +boundary. The first expression (which must be absolute) is the alignment required, +as described below. +.Pp +The second expression (also absolute) gives the fill value to be stored in +the padding bytes. It (and the comma) may be omitted. If it is omitted, the +padding bytes are normally zero. However, on some systems, if the section +is marked as containing code and the fill value is omitted, the space is filled +with no-op instructions. +.Pp +The third expression is also absolute, and is also optional. If it is present, +it is the maximum number of bytes that should be skipped by this alignment +directive. If doing the alignment would require skipping more bytes than the +specified maximum, then the alignment is not done at all. You can omit the +fill value (the second argument) entirely by simply using two commas after +the required alignment; this can be useful if you want the alignment to be +filled with no-op instructions when appropriate. +.Pp +The way the required alignment is specified varies from system to system. +For the arc, hppa, i386 using ELF, i860, iq2000, m68k, or32, s390, sparc, +tic4x, tic80 and xtensa, the first expression is the alignment request in +bytes. For example +.Li .align 8 +advances the location counter until it is a multiple of 8. If the location +counter is already a multiple of 8, no change is needed. For the tic54x, the +first expression is the alignment request in words. +.Pp +For other systems, including the i386 using a.out format, and the arm and +strongarm, it is the number of low-order zero bits the location counter must +have after advancement. For example +.Li .align 3 +advances the location counter until it a multiple of 8. If the location counter +is already a multiple of 8, no change is needed. +.Pp +This inconsistency is due to the different behaviors of the various native +assemblers for these systems which GAS must emulate. GAS also provides +.Li .balign +and +.Li .p2align +directives, described later, which have a consistent behavior across all architectures +(but are specific to GAS). +.Pp +.Ss Li .ascii " Va string"... +.Li .ascii +expects zero or more string literals (see Section +.Dq Strings ) +separated by commas. It assembles each string (with no automatic trailing +zero byte) into consecutive addresses. +.Pp +.Ss Li .asciz " Va string"... +.Li .asciz +is just like +.Li .ascii , +but each string is followed by a zero byte. The \(lqz\(rq in +.Li .asciz +stands for \(lqzero\(rq. +.Pp +.Ss Li .balign[wl] Va abs-expr, Va abs-expr, Va abs-expr +Pad the location counter (in the current subsection) to a particular storage +boundary. The first expression (which must be absolute) is the alignment request +in bytes. For example +.Li .balign 8 +advances the location counter until it is a multiple of 8. If the location +counter is already a multiple of 8, no change is needed. +.Pp +The second expression (also absolute) gives the fill value to be stored in +the padding bytes. It (and the comma) may be omitted. If it is omitted, the +padding bytes are normally zero. However, on some systems, if the section +is marked as containing code and the fill value is omitted, the space is filled +with no-op instructions. +.Pp +The third expression is also absolute, and is also optional. If it is present, +it is the maximum number of bytes that should be skipped by this alignment +directive. If doing the alignment would require skipping more bytes than the +specified maximum, then the alignment is not done at all. You can omit the +fill value (the second argument) entirely by simply using two commas after +the required alignment; this can be useful if you want the alignment to be +filled with no-op instructions when appropriate. +.Pp +The +.Li .balignw +and +.Li .balignl +directives are variants of the +.Li .balign +directive. The +.Li .balignw +directive treats the fill pattern as a two byte word value. The +.Li .balignl +directives treats the fill pattern as a four byte longword value. For example, +.Li .balignw 4,0x368d +will align to a multiple of 4. If it skips two bytes, they will be filled +in with the value 0x368d (the exact placement of the bytes depends upon the +endianness of the processor). If it skips 1 or 3 bytes, the fill value is +undefined. +.Pp +.Ss Li .byte Va expressions +.Li .byte +expects zero or more expressions, separated by commas. Each expression is +assembled into the next byte. +.Pp +.Ss Li .comm Va symbol , Va length +.Li .comm +declares a common symbol named +.Va symbol . +When linking, a common symbol in one object file may be merged with a defined +or common symbol of the same name in another object file. If +.Li ld +does not see a definition for the symbol--just one or more common symbols--then +it will allocate +.Va length +bytes of uninitialized memory. +.Va length +must be an absolute expression. If +.Li ld +sees multiple common symbols with the same name, and they do not all have +the same size, it will allocate space using the largest size. +.Pp +When using ELF, the +.Li .comm +directive takes an optional third argument. This is the desired alignment +of the symbol, specified as a byte boundary (for example, an alignment of +16 means that the least significant 4 bits of the address should be zero). +The alignment must be an absolute expression, and it must be a power of two. +If +.Li ld +allocates uninitialized memory for the common symbol, it will use the alignment +when placing the symbol. If no alignment is specified, +.Xr as +will set the alignment to the largest power of two less than or equal to the +size of the symbol, up to a maximum of 16. +.Pp +.Ss Li .cfi_startproc [simple] +.Li .cfi_startproc +is used at the beginning of each function that should have an entry in +.Li .eh_frame . +It initializes some internal data structures. Don't forget to close the function +by +.Li .cfi_endproc . +.Pp +Unless +.Li .cfi_startproc +is used along with parameter +.Li simple +it also emits some architecture dependent initial CFI instructions. +.Ss Li .cfi_endproc +.Li .cfi_endproc +is used at the end of a function where it closes its unwind entry previously +opened by +.Li .cfi_startproc , +and emits it to +.Li .eh_frame . +.Pp +.Ss Li .cfi_personality Va encoding [, Va exp] +.Li .cfi_personality +defines personality routine and its encoding. +.Va encoding +must be a constant determining how the personality should be encoded. If it +is 255 ( +.Li DW_EH_PE_omit ) , +second argument is not present, otherwise second argument should be a constant +or a symbol name. When using indirect encodings, the symbol provided should +be the location where personality can be loaded from, not the personality +routine itself. The default after +.Li .cfi_startproc +is +.Li .cfi_personality 0xff , +no personality routine. +.Pp +.Ss Li .cfi_lsda Va encoding [, Va exp] +.Li .cfi_lsda +defines LSDA and its encoding. +.Va encoding +must be a constant determining how the LSDA should be encoded. If it is 255 +( +.Li DW_EH_PE_omit ) , +second argument is not present, otherwise second argument should be a constant +or a symbol name. The default after +.Li .cfi_startproc +is +.Li .cfi_lsda 0xff , +no LSDA. +.Pp +.Ss Li .cfi_def_cfa Va register, Va offset +.Li .cfi_def_cfa +defines a rule for computing CFA as: +.Em take address from Va register and add Va offset to it . +.Pp +.Ss Li .cfi_def_cfa_register Va register +.Li .cfi_def_cfa_register +modifies a rule for computing CFA. From now on +.Va register +will be used instead of the old one. Offset remains the same. +.Pp +.Ss Li .cfi_def_cfa_offset Va offset +.Li .cfi_def_cfa_offset +modifies a rule for computing CFA. Register remains the same, but +.Va offset +is new. Note that it is the absolute offset that will be added to a defined +register to compute CFA address. +.Pp +.Ss Li .cfi_adjust_cfa_offset Va offset +Same as +.Li .cfi_def_cfa_offset +but +.Va offset +is a relative value that is added/substracted from the previous offset. +.Pp +.Ss Li .cfi_offset Va register, Va offset +Previous value of +.Va register +is saved at offset +.Va offset +from CFA. +.Pp +.Ss Li .cfi_rel_offset Va register, Va offset +Previous value of +.Va register +is saved at offset +.Va offset +from the current CFA register. This is transformed to +.Li .cfi_offset +using the known displacement of the CFA register from the CFA. This is often +easier to use, because the number will match the code it's annotating. +.Pp +.Ss Li .cfi_register Va register1, Va register2 +Previous value of +.Va register1 +is saved in register +.Va register2 . +.Pp +.Ss Li .cfi_restore Va register +.Li .cfi_restore +says that the rule for +.Va register +is now the same as it was at the beginning of the function, after all initial +instruction added by +.Li .cfi_startproc +were executed. +.Pp +.Ss Li .cfi_undefined Va register +From now on the previous value of +.Va register +can't be restored anymore. +.Pp +.Ss Li .cfi_same_value Va register +Current value of +.Va register +is the same like in the previous frame, i.e. no restoration needed. +.Pp +.Ss Li .cfi_remember_state, +First save all current rules for all registers by +.Li .cfi_remember_state , +then totally screw them up by subsequent +.Li .cfi_* +directives and when everything is hopelessly bad, use +.Li .cfi_restore_state +to restore the previous saved state. +.Pp +.Ss Li .cfi_return_column Va register +Change return column +.Va register , +i.e. the return address is either directly in +.Va register +or can be accessed by rules for +.Va register . +.Pp +.Ss Li .cfi_signal_frame +Mark current function as signal trampoline. +.Pp +.Ss Li .cfi_window_save +SPARC register window has been saved. +.Pp +.Ss Li .cfi_escape Va expression[, ...] +Allows the user to add arbitrary bytes to the unwind info. One might use this +to add OS-specific CFI opcodes, or generic CFI opcodes that GAS does not yet +support. +.Pp +.Ss Li .file Va fileno Va filename +When emitting dwarf2 line number information +.Li .file +assigns filenames to the +.Li .debug_line +file name table. The +.Va fileno +operand should be a unique positive integer to use as the index of the entry +in the table. The +.Va filename +operand is a C string literal. +.Pp +The detail of filename indices is exposed to the user because the filename +table is shared with the +.Li .debug_info +section of the dwarf2 debugging information, and thus the user must know the +exact indices that table entries will have. +.Pp +.Ss Li .loc Va fileno Va lineno [ Va column] [ Va options] +The +.Li .loc +directive will add row to the +.Li .debug_line +line number matrix corresponding to the immediately following assembly instruction. +The +.Va fileno , +.Va lineno , +and optional +.Va column +arguments will be applied to the +.Li .debug_line +state machine before the row is added. +.Pp +The +.Va options +are a sequence of the following tokens in any order: +.Pp +.Bl -tag -width Ds +.It basic_block +This option will set the +.Li basic_block +register in the +.Li .debug_line +state machine to +.Li true . +.Pp +.It prologue_end +This option will set the +.Li prologue_end +register in the +.Li .debug_line +state machine to +.Li true . +.Pp +.It epilogue_begin +This option will set the +.Li epilogue_begin +register in the +.Li .debug_line +state machine to +.Li true . +.Pp +.It is_stmt Va value +This option will set the +.Li is_stmt +register in the +.Li .debug_line +state machine to +.Li value , +which must be either 0 or 1. +.Pp +.It isa Va value +This directive will set the +.Li isa +register in the +.Li .debug_line +state machine to +.Va value , +which must be an unsigned integer. +.Pp +.El +.Ss Li .loc_mark_blocks Va enable +The +.Li .loc_mark_blocks +directive makes the assembler emit an entry to the +.Li .debug_line +line number matrix with the +.Li basic_block +register in the state machine set whenever a code label is seen. The +.Va enable +argument should be either 1 or 0, to enable or disable this function respectively. +.Pp +.Ss Li .data Va subsection +.Li .data +tells +.Xr as +to assemble the following statements onto the end of the data subsection numbered +.Va subsection +(which is an absolute expression). If +.Va subsection +is omitted, it defaults to zero. +.Pp +.Ss Li .double Va flonums +.Li .double +expects zero or more flonums, separated by commas. It assembles floating point +numbers. +.Pp +.Ss Li .eject +Force a page break at this point, when generating assembly listings. +.Pp +.Ss Li .else +.Li .else +is part of the +.Xr as +support for conditional assembly; see If,, +.Li .if +\&. It marks the beginning of a section of code to be assembled if the condition +for the preceding +.Li .if +was false. +.Pp +.Ss Li .elseif +.Li .elseif +is part of the +.Xr as +support for conditional assembly; see If,, +.Li .if +\&. It is shorthand for beginning a new +.Li .if +block that would otherwise fill the entire +.Li .else +section. +.Pp +.Ss Li .end +.Li .end +marks the end of the assembly file. +.Xr as +does not process anything in the file past the +.Li .end +directive. +.Pp +.Ss Li .endfunc +.Li .endfunc +marks the end of a function specified with +.Li .func . +.Pp +.Ss Li .endif +.Li .endif +is part of the +.Xr as +support for conditional assembly; it marks the end of a block of code that +is only assembled conditionally.See Section +.Dq If . +.Pp +.Ss Li .equ Va symbol, Va expression +This directive sets the value of +.Va symbol +to +.Va expression . +It is synonymous with +.Li .set ; +see Set,, +.Li .set +\&. +.Pp +.Ss Li .equiv Va symbol, Va expression +The +.Li .equiv +directive is like +.Li .equ +and +.Li .set , +except that the assembler will signal an error if +.Va symbol +is already defined. Note a symbol which has been referenced but not actually +defined is considered to be undefined. +.Pp +Except for the contents of the error message, this is roughly equivalent to +.Bd -literal -offset indent +\&.ifdef SYM +\&.err +\&.endif +\&.equ SYM,VAL +.Ed +plus it protects the symbol from later redefinition. +.Pp +.Ss Li .eqv Va symbol, Va expression +The +.Li .eqv +directive is like +.Li .equiv , +but no attempt is made to evaluate the expression or any part of it immediately. +Instead each time the resulting symbol is used in an expression, a snapshot +of its current value is taken. +.Pp +.Ss Li .err +If +.Xr as +assembles a +.Li .err +directive, it will print an error message and, unless the +.Op -Z +option was used, it will not generate an object file. This can be used to +signal an error in conditionally compiled code. +.Pp +.Ss Li .error " Va string" +Similarly to +.Li .err , +this directive emits an error, but you can specify a string that will be emitted +as the error message. If you don't specify the message, it defaults to +.Li ".error directive invoked in source file" . +See Section.Dq Errors . +.Pp +.Bd -literal -offset indent + .error "This code has not been assembled and tested." +.Ed +.Pp +.Ss Li .exitm +Exit early from the current macro definition.See Section +.Dq Macro . +.Pp +.Ss Li .extern +.Li .extern +is accepted in the source program---for compatibility with other assemblers---but +it is ignored. +.Xr as +treats all undefined symbols as external. +.Pp +.Ss Li .fail Va expression +Generates an error or a warning. If the value of the +.Va expression +is 500 or more, +.Xr as +will print a warning message. If the value is less than 500, +.Xr as +will print an error message. The message will include the value of +.Va expression . +This can occasionally be useful inside complex nested macros or conditional +assembly. +.Pp +.Ss Li .file Va string +.Li .file +tells +.Xr as +that we are about to start a new logical file. +.Va string +is the new file name. In general, the filename is recognized whether or not +it is surrounded by quotes +.Li " ; +but if you wish to specify an empty file name, you must give the quotes-- +.Li "" . +This statement may go away in future: it is only recognized to be compatible +with old +.Xr as +programs. +.Pp +.Ss Li .fill Va repeat , Va size , Va value +.Va repeat , +.Va size +and +.Va value +are absolute expressions. This emits +.Va repeat +copies of +.Va size +bytes. +.Va Repeat +may be zero or more. +.Va Size +may be zero or more, but if it is more than 8, then it is deemed to have the +value 8, compatible with other people's assemblers. The contents of each +.Va repeat +bytes is taken from an 8-byte number. The highest order 4 bytes are zero. +The lowest order 4 bytes are +.Va value +rendered in the byte-order of an integer on the computer +.Xr as +is assembling for. Each +.Va size +bytes in a repetition is taken from the lowest order +.Va size +bytes of this number. Again, this bizarre behavior is compatible with other +people's assemblers. +.Pp +.Va size +and +.Va value +are optional. If the second comma and +.Va value +are absent, +.Va value +is assumed zero. If the first comma and following tokens are absent, +.Va size +is assumed to be 1. +.Pp +.Ss Li .float Va flonums +This directive assembles zero or more flonums, separated by commas. It has +the same effect as +.Li .single . +.Pp +.Ss Li .func Va name[, Va label] +.Li .func +emits debugging information to denote function +.Va name , +and is ignored unless the file is assembled with debugging enabled. Only +.Li --gstabs[+] +is currently supported. +.Va label +is the entry point of the function and if omitted +.Va name +prepended with the +.Li leading char +is used. +.Li leading char +is usually +.Li _ +or nothing, depending on the target. All functions are currently defined to +have +.Li void +return type. The function must be terminated with +.Li .endfunc . +.Pp +.Ss Li .global Va symbol, Li .globl Va symbol +.Li .global +makes the symbol visible to +.Li ld . +If you define +.Va symbol +in your partial program, its value is made available to other partial programs +that are linked with it. Otherwise, +.Va symbol +takes its attributes from a symbol of the same name from another file linked +into the same program. +.Pp +Both spellings ( +.Li .globl +and +.Li .global ) +are accepted, for compatibility with other assemblers. +.Pp +.Ss Li .hidden Va names +This is one of the ELF visibility directives. The other two are +.Li .internal +(see Section +.Dq Internal ) +and +.Li .protected +(see Section +.Dq Protected ) . +.Pp +This directive overrides the named symbols default visibility (which is set +by their binding: local, global or weak). The directive sets the visibility +to +.Li hidden +which means that the symbols are not visible to other components. Such symbols +are always considered to be +.Li protected +as well. +.Pp +.Ss Li .hword Va expressions +This expects zero or more +.Va expressions , +and emits a 16 bit number for each. +.Pp +This directive is a synonym for +.Li .short . +.Pp +.Ss Li .ident +This directive is used by some assemblers to place tags in object files. The +behavior of this directive varies depending on the target. When using the +a.out object file format, +.Xr as +simply accepts the directive for source-file compatibility with existing assemblers, +but does not emit anything for it. When using COFF, comments are emitted to +the +.Li .comment +or +.Li .rdata +section, depending on the target. When using ELF, comments are emitted to +the +.Li .comment +section. +.Pp +.Ss Li .if Va absolute expression +.Li .if +marks the beginning of a section of code which is only considered part of +the source program being assembled if the argument (which must be an +.Va absolute expression ) +is non-zero. The end of the conditional section of code must be marked by +.Li .endif +(see Section +.Dq Endif ) ; +optionally, you may include code for the alternative condition, flagged by +.Li .else +(see Section +.Dq Else ) . +If you have several conditions to check, +.Li .elseif +may be used to avoid nesting blocks if/else within each subsequent +.Li .else +block. +.Pp +The following variants of +.Li .if +are also supported: +.Bl -tag -width Ds +.It .ifdef Va symbol +Assembles the following section of code if the specified +.Va symbol +has been defined. Note a symbol which has been referenced but not yet defined +is considered to be undefined. +.Pp +.It .ifb Va text +Assembles the following section of code if the operand is blank (empty). +.Pp +.It .ifc Va string1, Va string2 +Assembles the following section of code if the two strings are the same. The +strings may be optionally quoted with single quotes. If they are not quoted, +the first string stops at the first comma, and the second string stops at +the end of the line. Strings which contain whitespace should be quoted. The +string comparison is case sensitive. +.Pp +.It .ifeq Va absolute expression +Assembles the following section of code if the argument is zero. +.Pp +.It .ifeqs Va string1, Va string2 +Another form of +.Li .ifc . +The strings must be quoted using double quotes. +.Pp +.It .ifge Va absolute expression +Assembles the following section of code if the argument is greater than or +equal to zero. +.Pp +.It .ifgt Va absolute expression +Assembles the following section of code if the argument is greater than zero. +.Pp +.It .ifle Va absolute expression +Assembles the following section of code if the argument is less than or equal +to zero. +.Pp +.It .iflt Va absolute expression +Assembles the following section of code if the argument is less than zero. +.Pp +.It .ifnb Va text +Like +.Li .ifb , +but the sense of the test is reversed: this assembles the following section +of code if the operand is non-blank (non-empty). +.Pp +.It .ifnc Va string1, Va string2. +Like +.Li .ifc , +but the sense of the test is reversed: this assembles the following section +of code if the two strings are not the same. +.Pp +.It .ifndef Va symbol +.It .ifnotdef Va symbol +Assembles the following section of code if the specified +.Va symbol +has not been defined. Both spelling variants are equivalent. Note a symbol +which has been referenced but not yet defined is considered to be undefined. +.Pp +.It .ifne Va absolute expression +Assembles the following section of code if the argument is not equal to zero +(in other words, this is equivalent to +.Li .if ) . +.Pp +.It .ifnes Va string1, Va string2 +Like +.Li .ifeqs , +but the sense of the test is reversed: this assembles the following section +of code if the two strings are not the same. +.El +.Pp +.Ss Li .incbin " Va file"[, Va skip[, Va count]] +The +.Li incbin +directive includes +.Va file +verbatim at the current location. You can control the search paths used with +the +.Li -I +command-line option (see Section +.Dq Invoking ) . +Quotation marks are required around +.Va file . +.Pp +The +.Va skip +argument skips a number of bytes from the start of the +.Va file . +The +.Va count +argument indicates the maximum number of bytes to read. Note that the data +is not aligned in any way, so it is the user's responsibility to make sure +that proper alignment is provided both before and after the +.Li incbin +directive. +.Pp +.Ss Li .include " Va file" +This directive provides a way to include supporting files at specified points +in your source program. The code from +.Va file +is assembled as if it followed the point of the +.Li .include ; +when the end of the included file is reached, assembly of the original file +continues. You can control the search paths used with the +.Li -I +command-line option (see Section +.Dq Invoking ) . +Quotation marks are required around +.Va file . +.Pp +.Ss Li .int Va expressions +Expect zero or more +.Va expressions , +of any section, separated by commas. For each expression, emit a number that, +at run time, is the value of that expression. The byte order and bit size +of the number depends on what kind of target the assembly is for. +.Pp +.Ss Li .internal Va names +This is one of the ELF visibility directives. The other two are +.Li .hidden +(see Section +.Dq Hidden ) +and +.Li .protected +(see Section +.Dq Protected ) . +.Pp +This directive overrides the named symbols default visibility (which is set +by their binding: local, global or weak). The directive sets the visibility +to +.Li internal +which means that the symbols are considered to be +.Li hidden +(i.e., not visible to other components), and that some extra, processor specific +processing must also be performed upon the symbols as well. +.Pp +.Ss Li .irp Va symbol, Va values... +Evaluate a sequence of statements assigning different values to +.Va symbol . +The sequence of statements starts at the +.Li .irp +directive, and is terminated by an +.Li .endr +directive. For each +.Va value , +.Va symbol +is set to +.Va value , +and the sequence of statements is assembled. If no +.Va value +is listed, the sequence of statements is assembled once, with +.Va symbol +set to the null string. To refer to +.Va symbol +within the sequence of statements, use +.Va \esymbol . +.Pp +For example, assembling +.Pp +.Bd -literal -offset indent + .irp param,1,2,3 + move d\eparam,sp@- + .endr +.Ed +.Pp +is equivalent to assembling +.Pp +.Bd -literal -offset indent + move d1,sp@- + move d2,sp@- + move d3,sp@- +.Ed +.Pp +For some caveats with the spelling of +.Va symbol , +see also Macro. +.Pp +.Ss Li .irpc Va symbol, Va values... +Evaluate a sequence of statements assigning different values to +.Va symbol . +The sequence of statements starts at the +.Li .irpc +directive, and is terminated by an +.Li .endr +directive. For each character in +.Va value , +.Va symbol +is set to the character, and the sequence of statements is assembled. If no +.Va value +is listed, the sequence of statements is assembled once, with +.Va symbol +set to the null string. To refer to +.Va symbol +within the sequence of statements, use +.Va \esymbol . +.Pp +For example, assembling +.Pp +.Bd -literal -offset indent + .irpc param,123 + move d\eparam,sp@- + .endr +.Ed +.Pp +is equivalent to assembling +.Pp +.Bd -literal -offset indent + move d1,sp@- + move d2,sp@- + move d3,sp@- +.Ed +.Pp +For some caveats with the spelling of +.Va symbol , +see also the discussion atSee Section +.Dq Macro . +.Pp +.Ss Li .lcomm Va symbol , Va length +Reserve +.Va length +(an absolute expression) bytes for a local common denoted by +.Va symbol . +The section and value of +.Va symbol +are those of the new local common. The addresses are allocated in the bss +section, so that at run-time the bytes start off zeroed. +.Va Symbol +is not declared global (see Section +.Dq Global ) , +so is normally not visible to +.Li ld . +.Pp +.Ss Li .lflags +.Xr as +accepts this directive, for compatibility with other assemblers, but ignores +it. +.Pp +.Ss Li .line Va line-number +Even though this is a directive associated with the +.Li a.out +or +.Li b.out +object-code formats, +.Xr as +still recognizes it when producing COFF output, and treats +.Li .line +as though it were the COFF +.Li .ln +.Em if +it is found outside a +.Li .def +/ +.Li .endef +pair. +.Pp +Inside a +.Li .def , +.Li .line +is, instead, one of the directives used by compilers to generate auxiliary +symbol information for debugging. +.Pp +.Ss Li .linkonce [ Va type] +Mark the current section so that the linker only includes a single copy of +it. This may be used to include the same section in several different object +files, but ensure that the linker will only include it once in the final output +file. The +.Li .linkonce +pseudo-op must be used for each instance of the section. Duplicate sections +are detected based on the section name, so it should be unique. +.Pp +This directive is only supported by a few object file formats; as of this +writing, the only object file format which supports it is the Portable Executable +format used on Windows NT. +.Pp +The +.Va type +argument is optional. If specified, it must be one of the following strings. +For example: +.Bd -literal -offset indent +\&.linkonce same_size +.Ed +Not all types may be supported on all object file formats. +.Pp +.Bl -tag -width Ds +.It discard +Silently discard duplicate sections. This is the default. +.Pp +.It one_only +Warn if there are duplicate sections, but still keep only one copy. +.Pp +.It same_size +Warn if any of the duplicates have different sizes. +.Pp +.It same_contents +Warn if any of the duplicates do not have exactly the same contents. +.El +.Pp +.Ss Li .ln Va line-number +.Li .ln +is a synonym for +.Li .line . +.Pp +.Ss Li .mri Va val +If +.Va val +is non-zero, this tells +.Xr as +to enter MRI mode. If +.Va val +is zero, this tells +.Xr as +to exit MRI mode. This change affects code assembled until the next +.Li .mri +directive, or until the end of the file.See Section +.Dq M . +.Pp +.Ss Li .list +Control (in conjunction with the +.Li .nolist +directive) whether or not assembly listings are generated. These two directives +maintain an internal counter (which is zero initially). +.Li .list +increments the counter, and +.Li .nolist +decrements it. Assembly listings are generated whenever the counter is greater +than zero. +.Pp +By default, listings are disabled. When you enable them (with the +.Li -a +command line option;see Section +.Dq Invoking ) , +the initial value of the listing counter is one. +.Pp +.Ss Li .long Va expressions +.Li .long +is the same as +.Li .int . +See Section.Dq Int . +.Pp +.Ss Li .macro +The commands +.Li .macro +and +.Li .endm +allow you to define macros that generate assembly output. For example, this +definition specifies a macro +.Li sum +that puts a sequence of numbers into memory: +.Pp +.Bd -literal -offset indent + .macro sum from=0, to=5 + .long \efrom + .if \eto-\efrom + sum "(\efrom+1)",\eto + .endif + .endm +.Ed +.Pp +With that definition, +.Li SUM 0,5 +is equivalent to this assembly input: +.Pp +.Bd -literal -offset indent + .long 0 + .long 1 + .long 2 + .long 3 + .long 4 + .long 5 +.Ed +.Pp +.Bl -tag -width Ds +.It .macro Va macname +.It .macro Va macname Va macargs ... +Begin the definition of a macro called +.Va macname . +If your macro definition requires arguments, specify their names after the +macro name, separated by commas or spaces. You can qualify the macro argument +to indicate whether all invocations must specify a non-blank value (through +.Li : Li req ) , +or whether it takes all of the remaining arguments (through +.Li : Li vararg ) . +You can supply a default value for any macro argument by following the name +with +.Li = Va deflt . +You cannot define two macros with the same +.Va macname +unless it has been subject to the +.Li .purgem +directive (see Section +.Dq Purgem ) +between the two definitions. For example, these are all valid +.Li .macro +statements: +.Pp +.Bl -tag -width Ds +.It .macro comm +Begin the definition of a macro called +.Li comm , +which takes no arguments. +.Pp +.It .macro plus1 p, p1 +.It .macro plus1 p p1 +Either statement begins the definition of a macro called +.Li plus1 , +which takes two arguments; within the macro definition, write +.Li \ep +or +.Li \ep1 +to evaluate the arguments. +.Pp +.It .macro reserve_str p1=0 p2 +Begin the definition of a macro called +.Li reserve_str , +with two arguments. The first argument has a default value, but not the second. +After the definition is complete, you can call the macro either as +.Li reserve_str Va a, Va b +(with +.Li \ep1 +evaluating to +.Va a +and +.Li \ep2 +evaluating to +.Va b ) , +or as +.Li reserve_str , Va b +(with +.Li \ep1 +evaluating as the default, in this case +.Li 0 , +and +.Li \ep2 +evaluating to +.Va b ) . +.Pp +.It .macro m p1:req, p2=0, p3:vararg +Begin the definition of a macro called +.Li m , +with at least three arguments. The first argument must always have a value +specified, but not the second, which instead has a default value. The third +formal will get assigned all remaining arguments specified at invocation time. +.Pp +When you call a macro, you can specify the argument values either by position, +or by keyword. For example, +.Li sum 9,17 +is equivalent to +.Li sum to=17, from=9 . +.Pp +.El +Note that since each of the +.Va macargs +can be an identifier exactly as any other one permitted by the target architecture, +there may be occasional problems if the target hand-crafts special meanings +to certain characters when they occur in a special position. For example, +if the colon ( +.Li : ) +is generally permitted to be part of a symbol name, but the architecture specific +code special-cases it when occurring as the final character of a symbol (to +denote a label), then the macro parameter replacement code will have no way +of knowing that and consider the whole construct (including the colon) an +identifier, and check only this identifier for being the subject to parameter +substitution. So for example this macro definition: +.Pp +.Bd -literal -offset indent + .macro label l +\el: + .endm +.Ed +.Pp +might not work as expected. Invoking +.Li label foo +might not create a label called +.Li foo +but instead just insert the text +.Li \el: +into the assembler source, probably generating an error about an unrecognised +identifier. +.Pp +Similarly problems might occur with the period character ( +.Li . ) +which is often allowed inside opcode names (and hence identifier names). So +for example constructing a macro to build an opcode from a base name and a +length specifier like this: +.Pp +.Bd -literal -offset indent + .macro opcode base length + \ebase.\elength + .endm +.Ed +.Pp +and invoking it as +.Li opcode store l +will not create a +.Li store.l +instruction but instead generate some kind of error as the assembler tries +to interpret the text +.Li \ebase.\elength . +.Pp +There are several possible ways around this problem: +.Pp +.Bl -tag -width Ds +.It Insert white space +If it is possible to use white space characters then this is the simplest +solution. eg: +.Pp +.Bd -literal -offset indent + .macro label l +\el : + .endm +.Ed +.Pp +.It Use Li \e() +The string +.Li \e() +can be used to separate the end of a macro argument from the following text. +eg: +.Pp +.Bd -literal -offset indent + .macro opcode base length + \ebase\e().\elength + .endm +.Ed +.Pp +.It Use the alternate macro syntax mode +In the alternative macro syntax mode the ampersand character ( +.Li & ) +can be used as a separator. eg: +.Pp +.Bd -literal -offset indent + .altmacro + .macro label l +l&: + .endm +.Ed +.El +.Pp +Note: this problem of correctly identifying string parameters to pseudo ops +also applies to the identifiers used in +.Li .irp +(see Section +.Dq Irp ) +and +.Li .irpc +(see Section +.Dq Irpc ) +as well. +.Pp +.It .endm +Mark the end of a macro definition. +.Pp +.It .exitm +Exit early from the current macro definition. +.Pp +.It \e@ +.Xr as +maintains a counter of how many macros it has executed in this pseudo-variable; +you can copy that number to your output with +.Li \e@ , +but +.Em only within a macro definition . +.Pp +.It LOCAL Va name [ , ... ] +.Em Warning: Li LOCAL is only available if you select \(lqalternate macro syntax\(rq with Li --alternate or Li .altmacro. +See Section.Dq Altmacro . +.El +.Pp +.Ss Li .altmacro +Enable alternate macro mode, enabling: +.Pp +.Bl -tag -width Ds +.It LOCAL Va name [ , ... ] +One additional directive, +.Li LOCAL , +is available. It is used to generate a string replacement for each of the +.Va name +arguments, and replace any instances of +.Va name +in each macro expansion. The replacement string is unique in the assembly, +and different for each separate macro expansion. +.Li LOCAL +allows you to write macros that define symbols, without fear of conflict between +separate macro expansions. +.Pp +.It String delimiters +You can write strings delimited in these other ways besides +.Li " Va string" : +.Pp +.Bl -tag -width Ds +.It ' Va string' +You can delimit strings with single-quote characters. +.Pp +.It < Va string> +You can delimit strings with matching angle brackets. +.El +.Pp +.It single-character string escape +To include any single character literally in a string (even if the character +would otherwise have some special meaning), you can prefix the character with +.Li ! +(an exclamation mark). For example, you can write +.Li <4.3 !> 5.4!!> +to get the literal text +.Li 4.3 > 5.4! . +.Pp +.It Expression results as strings +You can write +.Li % Va expr +to evaluate the expression +.Va expr +and use the result as a string. +.El +.Pp +.Ss Li .noaltmacro +Disable alternate macro mode.See Section +.Dq Altmacro . +.Pp +.Ss Li .nolist +Control (in conjunction with the +.Li .list +directive) whether or not assembly listings are generated. These two directives +maintain an internal counter (which is zero initially). +.Li .list +increments the counter, and +.Li .nolist +decrements it. Assembly listings are generated whenever the counter is greater +than zero. +.Pp +.Ss Li .octa Va biGNUms +This directive expects zero or more biGNUms, separated by commas. For each +biGNUm, it emits a 16-byte integer. +.Pp +The term \(lqocta\(rq comes from contexts in which a \(lqword\(rq is two bytes; hence +.Em octa +-word for 16 bytes. +.Pp +.Ss Li .org Va new-lc , Va fill +Advance the location counter of the current section to +.Va new-lc . +.Va new-lc +is either an absolute expression or an expression with the same section as +the current subsection. That is, you can't use +.Li .org +to cross sections: if +.Va new-lc +has the wrong section, the +.Li .org +directive is ignored. To be compatible with former assemblers, if the section +of +.Va new-lc +is absolute, +.Xr as +issues a warning, then pretends the section of +.Va new-lc +is the same as the current subsection. +.Pp +.Li .org +may only increase the location counter, or leave it unchanged; you cannot +use +.Li .org +to move the location counter backwards. +.Pp +Because +.Xr as +tries to assemble programs in one pass, +.Va new-lc +may not be undefined. If you really detest this restriction we eagerly await +a chance to share your improved assembler. +.Pp +Beware that the origin is relative to the start of the section, not to the +start of the subsection. This is compatible with other people's assemblers. +.Pp +When the location counter (of the current subsection) is advanced, the intervening +bytes are filled with +.Va fill +which should be an absolute expression. If the comma and +.Va fill +are omitted, +.Va fill +defaults to zero. +.Pp +.Ss Li .p2align[wl] Va abs-expr, Va abs-expr, Va abs-expr +Pad the location counter (in the current subsection) to a particular storage +boundary. The first expression (which must be absolute) is the number of low-order +zero bits the location counter must have after advancement. For example +.Li .p2align 3 +advances the location counter until it a multiple of 8. If the location counter +is already a multiple of 8, no change is needed. +.Pp +The second expression (also absolute) gives the fill value to be stored in +the padding bytes. It (and the comma) may be omitted. If it is omitted, the +padding bytes are normally zero. However, on some systems, if the section +is marked as containing code and the fill value is omitted, the space is filled +with no-op instructions. +.Pp +The third expression is also absolute, and is also optional. If it is present, +it is the maximum number of bytes that should be skipped by this alignment +directive. If doing the alignment would require skipping more bytes than the +specified maximum, then the alignment is not done at all. You can omit the +fill value (the second argument) entirely by simply using two commas after +the required alignment; this can be useful if you want the alignment to be +filled with no-op instructions when appropriate. +.Pp +The +.Li .p2alignw +and +.Li .p2alignl +directives are variants of the +.Li .p2align +directive. The +.Li .p2alignw +directive treats the fill pattern as a two byte word value. The +.Li .p2alignl +directives treats the fill pattern as a four byte longword value. For example, +.Li .p2alignw 2,0x368d +will align to a multiple of 4. If it skips two bytes, they will be filled +in with the value 0x368d (the exact placement of the bytes depends upon the +endianness of the processor). If it skips 1 or 3 bytes, the fill value is +undefined. +.Pp +.Ss Li .previous +This is one of the ELF section stack manipulation directives. The others are +.Li .section +(see Section +.Dq Section ) , +.Li .subsection +(see Section +.Dq SubSection ) , +.Li .pushsection +(see Section +.Dq PushSection ) , +and +.Li .popsection +(see Section +.Dq PopSection ) . +.Pp +This directive swaps the current section (and subsection) with most recently +referenced section (and subsection) prior to this one. Multiple +.Li .previous +directives in a row will flip between two sections (and their subsections). +.Pp +In terms of the section stack, this directive swaps the current section with +the top section on the section stack. +.Pp +.Ss Li .popsection +This is one of the ELF section stack manipulation directives. The others are +.Li .section +(see Section +.Dq Section ) , +.Li .subsection +(see Section +.Dq SubSection ) , +.Li .pushsection +(see Section +.Dq PushSection ) , +and +.Li .previous +(see Section +.Dq Previous ) . +.Pp +This directive replaces the current section (and subsection) with the top +section (and subsection) on the section stack. This section is popped off +the stack. +.Pp +.Ss Li .print Va string +.Xr as +will print +.Va string +on the standard output during assembly. You must put +.Va string +in double quotes. +.Pp +.Ss Li .protected Va names +This is one of the ELF visibility directives. The other two are +.Li .hidden +(see Section +.Dq Hidden ) +and +.Li .internal +(see Section +.Dq Internal ) . +.Pp +This directive overrides the named symbols default visibility (which is set +by their binding: local, global or weak). The directive sets the visibility +to +.Li protected +which means that any references to the symbols from within the components +that defines them must be resolved to the definition in that component, even +if a definition in another component would normally preempt this. +.Pp +.Ss Li .psize Va lines , Va columns +Use this directive to declare the number of lines---and, optionally, the number +of columns---to use for each page, when generating listings. +.Pp +If you do not use +.Li .psize , +listings use a default line-count of 60. You may omit the comma and +.Va columns +specification; the default width is 200 columns. +.Pp +.Xr as +generates formfeeds whenever the specified number of lines is exceeded (or +whenever you explicitly request one, using +.Li .eject ) . +.Pp +If you specify +.Va lines +as +.Li 0 , +no formfeeds are generated save those explicitly specified with +.Li .eject . +.Pp +.Ss Li .purgem Va name +Undefine the macro +.Va name , +so that later uses of the string will not be expanded.See Section +.Dq Macro . +.Pp +.Ss Li .pushsection Va name , Va subsection +This is one of the ELF section stack manipulation directives. The others are +.Li .section +(see Section +.Dq Section ) , +.Li .subsection +(see Section +.Dq SubSection ) , +.Li .popsection +(see Section +.Dq PopSection ) , +and +.Li .previous +(see Section +.Dq Previous ) . +.Pp +This directive pushes the current section (and subsection) onto the top of +the section stack, and then replaces the current section and subsection with +.Li name +and +.Li subsection . +.Pp +.Ss Li .quad Va biGNUms +.Li .quad +expects zero or more biGNUms, separated by commas. For each bignum, it emits +an 8-byte integer. If the biGNUm won't fit in 8 bytes, it prints a warning +message; and just takes the lowest order 8 bytes of the biGNUm. +.Pp +The term \(lqquad\(rq comes from contexts in which a \(lqword\(rq is two bytes; hence +.Em quad +-word for 8 bytes. +.Pp +.Ss Li .reloc Va offset, Va reloc_name[, Va expression] +Generate a relocation at +.Va offset +of type +.Va reloc_name +with value +.Va expression . +If +.Va offset +is a number, the relocation is generated in the current section. If +.Va offset +is an expression that resolves to a symbol plus offset, the relocation is +generated in the given symbol's section. +.Va expression , +if present, must resolve to a symbol plus addend or to an absolute value, +but note that not all targets support an addend. e.g. ELF REL targets such +as i386 store an addend in the section contents rather than in the relocation. +This low level interface does not support addends stored in the section. +.Pp +.Ss Li .rept Va count +Repeat the sequence of lines between the +.Li .rept +directive and the next +.Li .endr +directive +.Va count +times. +.Pp +For example, assembling +.Pp +.Bd -literal -offset indent + .rept 3 + .long 0 + .endr +.Ed +.Pp +is equivalent to assembling +.Pp +.Bd -literal -offset indent + .long 0 + .long 0 + .long 0 +.Ed +.Pp +.Ss Li .sbttl " Va subheading" +Use +.Va subheading +as the title (third line, immediately after the title line) when generating +assembly listings. +.Pp +This directive affects subsequent pages, as well as the current page if it +appears within ten lines of the top of a page. +.Pp +.Ss Li .section Va name +Use the +.Li .section +directive to assemble the following code into a section named +.Va name . +.Pp +This directive is only supported for targets that actually support arbitrarily +named sections; on +.Li a.out +targets, for example, it is not accepted, even with a standard +.Li a.out +section name. +.Pp +This is one of the ELF section stack manipulation directives. The others are +.Li .subsection +(see Section +.Dq SubSection ) , +.Li .pushsection +(see Section +.Dq PushSection ) , +.Li .popsection +(see Section +.Dq PopSection ) , +and +.Li .previous +(see Section +.Dq Previous ) . +.Pp +For ELF targets, the +.Li .section +directive is used like this: +.Pp +.Bd -literal -offset indent +\&.section name [, "flags"[, @type[,flag_specific_arguments]]] +.Ed +.Pp +The optional +.Va flags +argument is a quoted string which may contain any combination of the following +characters: +.Bl -tag -width Ds +.It a +section is allocatable +.It w +section is writable +.It x +section is executable +.It M +section is mergeable +.It S +section contains zero terminated strings +.It G +section is a member of a section group +.It T +section is used for thread-local-storage +.El +.Pp +The optional +.Va type +argument may contain one of the following constants: +.Bl -tag -width Ds +.It @progbits +section contains data +.It @nobits +section does not contain data (i.e., section only occupies space) +.It @note +section contains data which is used by things other than the program +.It @init_array +section contains an array of pointers to init functions +.It @fini_array +section contains an array of pointers to finish functions +.It @preinit_array +section contains an array of pointers to pre-init functions +.El +.Pp +Many targets only support the first three section types. +.Pp +Note on targets where the +.Li @ +character is the start of a comment (eg ARM) then another character is used +instead. For example the ARM port uses the +.Li % +character. +.Pp +If +.Va flags +contains the +.Li M +symbol then the +.Va type +argument must be specified as well as an extra argument--- +.Va entsize +---like this: +.Pp +.Bd -literal -offset indent +\&.section name , "flags"M, @type, entsize +.Ed +.Pp +Sections with the +.Li M +flag but not +.Li S +flag must contain fixed size constants, each +.Va entsize +octets long. Sections with both +.Li M +and +.Li S +must contain zero terminated strings where each character is +.Va entsize +bytes long. The linker may remove duplicates within sections with the same +name, same entity size and same flags. +.Va entsize +must be an absolute expression. +.Pp +If +.Va flags +contains the +.Li G +symbol then the +.Va type +argument must be present along with an additional field like this: +.Pp +.Bd -literal -offset indent +\&.section name , "flags"G, @type, GroupName[, linkage] +.Ed +.Pp +The +.Va GroupName +field specifies the name of the section group to which this particular section +belongs. The optional linkage field can contain: +.Bl -tag -width Ds +.It comdat +indicates that only one copy of this section should be retained +.It .GNU.linkonce +an alias for comdat +.El +.Pp +Note: if both the +.Va M +and +.Va G +flags are present then the fields for the Merge flag should come first, like +this: +.Pp +.Bd -literal -offset indent +\&.section name , "flags"MG, @type, entsize, GroupName[, linkage] +.Ed +.Pp +If no flags are specified, the default flags depend upon the section name. +If the section name is not recognized, the default will be for the section +to have none of the above flags: it will not be allocated in memory, nor writable, +nor executable. The section will contain data. +.Pp +For ELF targets, the assembler supports another type of +.Li .section +directive for compatibility with the Solaris assembler: +.Pp +.Bd -literal -offset indent +\&.section "name"[, flags...] +.Ed +.Pp +Note that the section name is quoted. There may be a sequence of comma separated +flags: +.Bl -tag -width Ds +.It #alloc +section is allocatable +.It #write +section is writable +.It #execinstr +section is executable +.It #tls +section is used for thread local storage +.El +.Pp +This directive replaces the current section and subsection. See the contents +of the gas testsuite directory +.Li gas/testsuite/gas/elf +for some examples of how this directive and the other section stack directives +work. +.Pp +.Ss Li .set Va symbol, Va expression +Set the value of +.Va symbol +to +.Va expression . +This changes +.Va symbol +\&'s value and type to conform to +.Va expression . +If +.Va symbol +was flagged as external, it remains flagged (see Section +.Dq Symbol Attributes ) . +.Pp +You may +.Li .set +a symbol many times in the same assembly. +.Pp +If you +.Li .set +a global symbol, the value stored in the object file is the last value stored +into it. +.Pp +.Ss Li .short Va expressions +This expects zero or more +.Va expressions , +and emits a 16 bit number for each. +.Pp +.Ss Li .single Va flonums +This directive assembles zero or more flonums, separated by commas. It has +the same effect as +.Li .float . +.Pp +.Ss Li .size +This directive is used to set the size associated with a symbol. +.Pp +For ELF targets, the +.Li .size +directive is used like this: +.Pp +.Bd -literal -offset indent +\&.size name , expression +.Ed +.Pp +This directive sets the size associated with a symbol +.Va name . +The size in bytes is computed from +.Va expression +which can make use of label arithmetic. This directive is typically used to +set the size of function symbols. +.Pp +.Ss Li .sleb128 Va expressions +.Va sleb128 +stands for \(lqsigned little endian base 128.\(rq This is a compact, variable length +representation of numbers used by the DWARF symbolic debugging format.See Section +.Dq Uleb128 . +.Pp +.Ss Li .skip Va size , Va fill +This directive emits +.Va size +bytes, each of value +.Va fill . +Both +.Va size +and +.Va fill +are absolute expressions. If the comma and +.Va fill +are omitted, +.Va fill +is assumed to be zero. This is the same as +.Li .space . +.Pp +.Ss Li .space Va size , Va fill +This directive emits +.Va size +bytes, each of value +.Va fill . +Both +.Va size +and +.Va fill +are absolute expressions. If the comma and +.Va fill +are omitted, +.Va fill +is assumed to be zero. This is the same as +.Li .skip . +.Pp +.Ss Li .stabd, .stabn, .stabs +There are three directives that begin +.Li .stab . +All emit symbols (see Section +.Dq Symbols ) , +for use by symbolic debuggers. The symbols are not entered in the +.Xr as +hash table: they cannot be referenced elsewhere in the source file. Up to +five fields are required: +.Pp +.Bl -tag -width Ds +.It string +This is the symbol's name. It may contain any character except +.Li \e000 , +so is more general than ordinary symbol names. Some debuggers used to code +arbitrarily complex structures into symbol names using this field. +.Pp +.It type +An absolute expression. The symbol's type is set to the low 8 bits of this +expression. Any bit pattern is permitted, but +.Li ld +and debuggers choke on silly bit patterns. +.Pp +.It other +An absolute expression. The symbol's \(lqother\(rq attribute is set to the low 8 bits +of this expression. +.Pp +.It desc +An absolute expression. The symbol's descriptor is set to the low 16 bits +of this expression. +.Pp +.It value +An absolute expression which becomes the symbol's value. +.El +.Pp +If a warning is detected while reading a +.Li .stabd , +.Li .stabn , +or +.Li .stabs +statement, the symbol has probably already been created; you get a half-formed +symbol in your object file. This is compatible with earlier assemblers! +.Pp +.Bl -tag -width Ds +.It .stabd Va type , Va other , Va desc +.Pp +The \(lqname\(rq of the symbol generated is not even an empty string. It is a null +pointer, for compatibility. Older assemblers used a null pointer so they didn't +waste space in object files with empty strings. +.Pp +The symbol's value is set to the location counter, relocatably. When your +program is linked, the value of this symbol is the address of the location +counter when the +.Li .stabd +was assembled. +.Pp +.It .stabn Va type , Va other , Va desc , Va value +The name of the symbol is set to the empty string +.Li "" . +.Pp +.It .stabs Va string , Va type , Va other , Va desc , Va value +All five fields are specified. +.El +.Pp +.Ss Li .string " Va str" +Copy the characters in +.Va str +to the object file. You may specify more than one string to copy, separated +by commas. Unless otherwise specified for a particular machine, the assembler +marks the end of each string with a 0 byte. You can use any of the escape +sequences described in Strings,,Strings. +.Pp +.Ss Li .struct Va expression +Switch to the absolute section, and set the section offset to +.Va expression , +which must be an absolute expression. You might use this as follows: +.Bd -literal -offset indent + .struct 0 +field1: + .struct field1 + 4 +field2: + .struct field2 + 4 +field3: +.Ed +This would define the symbol +.Li field1 +to have the value 0, the symbol +.Li field2 +to have the value 4, and the symbol +.Li field3 +to have the value 8. Assembly would be left in the absolute section, and you +would need to use a +.Li .section +directive of some sort to change to some other section before further assembly. +.Pp +.Ss Li .subsection Va name +This is one of the ELF section stack manipulation directives. The others are +.Li .section +(see Section +.Dq Section ) , +.Li .pushsection +(see Section +.Dq PushSection ) , +.Li .popsection +(see Section +.Dq PopSection ) , +and +.Li .previous +(see Section +.Dq Previous ) . +.Pp +This directive replaces the current subsection with +.Li name . +The current section is not changed. The replaced subsection is put onto the +section stack in place of the then current top of stack subsection. +.Pp +.Ss Li .symver +Use the +.Li .symver +directive to bind symbols to specific version nodes within a source file. +This is only supported on ELF platforms, and is typically used when assembling +files to be linked into a shared library. There are cases where it may make +sense to use this in objects to be bound into an application itself so as +to override a versioned symbol from a shared library. +.Pp +For ELF targets, the +.Li .symver +directive can be used like this: +.Bd -literal -offset indent +\&.symver name, name2@nodename +.Ed +If the symbol +.Va name +is defined within the file being assembled, the +.Li .symver +directive effectively creates a symbol alias with the name +.Va name2@nodename , +and in fact the main reason that we just don't try and create a regular alias +is that the +.Va @ +character isn't permitted in symbol names. The +.Va name2 +part of the name is the actual name of the symbol by which it will be externally +referenced. The name +.Va name +itself is merely a name of convenience that is used so that it is possible +to have definitions for multiple versions of a function within a single source +file, and so that the compiler can unambiguously know which version of a function +is being mentioned. The +.Va nodename +portion of the alias should be the name of a node specified in the version +script supplied to the linker when building a shared library. If you are attempting +to override a versioned symbol from a shared library, then +.Va nodename +should correspond to the nodename of the symbol you are trying to override. +.Pp +If the symbol +.Va name +is not defined within the file being assembled, all references to +.Va name +will be changed to +.Va name2@nodename . +If no reference to +.Va name +is made, +.Va name2@nodename +will be removed from the symbol table. +.Pp +Another usage of the +.Li .symver +directive is: +.Bd -literal -offset indent +\&.symver name, name2@@nodename +.Ed +In this case, the symbol +.Va name +must exist and be defined within the file being assembled. It is similar to +.Va name2@nodename . +The difference is +.Va name2@@nodename +will also be used to resolve references to +.Va name2 +by the linker. +.Pp +The third usage of the +.Li .symver +directive is: +.Bd -literal -offset indent +\&.symver name, name2@@@nodename +.Ed +When +.Va name +is not defined within the file being assembled, it is treated as +.Va name2@nodename . +When +.Va name +is defined within the file being assembled, the symbol name, +.Va name , +will be changed to +.Va name2@@nodename . +.Pp +.Ss Li .text Va subsection +Tells +.Xr as +to assemble the following statements onto the end of the text subsection numbered +.Va subsection , +which is an absolute expression. If +.Va subsection +is omitted, subsection number zero is used. +.Pp +.Ss Li .title " Va heading" +Use +.Va heading +as the title (second line, immediately after the source file name and pagenumber) +when generating assembly listings. +.Pp +This directive affects subsequent pages, as well as the current page if it +appears within ten lines of the top of a page. +.Pp +.Ss Li .type +This directive is used to set the type of a symbol. +.Pp +For ELF targets, the +.Li .type +directive is used like this: +.Pp +.Bd -literal -offset indent +\&.type name , type description +.Ed +.Pp +This sets the type of symbol +.Va name +to be either a function symbol or an object symbol. There are five different +syntaxes supported for the +.Va type description +field, in order to provide compatibility with various other assemblers. +.Pp +Because some of the characters used in these syntaxes (such as +.Li @ +and +.Li # ) +are comment characters for some architectures, some of the syntaxes below +do not work on all architectures. The first variant will be accepted by the +GNU assembler on all architectures so that variant should be used for maximum +portability, if you do not need to assemble your code with other assemblers. +.Pp +The syntaxes supported are: +.Pp +.Bd -literal -offset indent + .type <name> STT_FUNCTION + .type <name> STT_OBJECT + + .type <name>,#function + .type <name>,#object + + .type <name>,@function + .type <name>,@object + + .type <name>,%function + .type <name>,%object + + .type <name>,"function" + .type <name>,"object" +.Ed +.Pp +.Ss Li .uleb128 Va expressions +.Va uleb128 +stands for \(lqunsigned little endian base 128.\(rq This is a compact, variable length +representation of numbers used by the DWARF symbolic debugging format.See Section +.Dq Sleb128 . +.Pp +.Ss Li .version " Va string" +This directive creates a +.Li .note +section and places into it an ELF formatted note of type NT_VERSION. The note's +name is set to +.Li string . +.Pp +.Ss Li .vtable_entry Va table, Va offset +This directive finds or creates a symbol +.Li table +and creates a +.Li VTABLE_ENTRY +relocation for it with an addend of +.Li offset . +.Pp +.Ss Li .vtable_inherit Va child, Va parent +This directive finds the symbol +.Li child +and finds or creates the symbol +.Li parent +and then creates a +.Li VTABLE_INHERIT +relocation for the parent whose addend is the value of the child symbol. As +a special case the parent name of +.Li 0 +is treated as referring to the +.Li *ABS* +section. +.Pp +.Ss Li .warning " Va string" +Similar to the directive +.Li .error +(see Section +.Dq Error ) , +but just emits a warning. +.Pp +.Ss Li .weak Va names +This directive sets the weak attribute on the comma separated list of symbol +.Li names . +If the symbols do not already exist, they will be created. +.Pp +On COFF targets other than PE, weak symbols are a GNU extension. This directive +sets the weak attribute on the comma separated list of symbol +.Li names . +If the symbols do not already exist, they will be created. +.Pp +On the PE target, weak symbols are supported natively as weak aliases. When +a weak symbol is created that is not an alias, GAS creates an alternate symbol +to hold the default value. +.Pp +.Ss Li .weakref Va alias, Va target +This directive creates an alias to the target symbol that enables the symbol +to be referenced with weak-symbol semantics, but without actually making it +weak. If direct references or definitions of the symbol are present, then +the symbol will not be weak, but if all references to it are through weak +references, the symbol will be marked as weak in the symbol table. +.Pp +The effect is equivalent to moving all references to the alias to a separate +assembly source file, renaming the alias to the symbol in it, declaring the +symbol as weak there, and running a reloadable link to merge the object files +resulting from the assembly of the new source file and the old source file +that had the references to the alias removed. +.Pp +The alias itself never makes to the symbol table, and is entirely handled +within the assembler. +.Pp +.Ss Li .word Va expressions +This directive expects zero or more +.Va expressions , +of any section, separated by commas. For each expression, +.Xr as +emits a 32-bit number. +.Pp +.Ss Deprecated Directives +One day these directives won't work. They are included for compatibility with +older assemblers. +.Bl -tag -width Ds +.It .abort +.It .line +.El +.Pp +.Sh ARM Dependent Features +.Ss Options +.Bl -tag -width Ds +.It -mcpu= Va processor[+ Va extension...] +This option specifies the target processor. The assembler will issue an error +message if an attempt is made to assemble an instruction which will not execute +on the target processor. The following processor names are recognized: +.Li arm1 , +.Li arm2 , +.Li arm250 , +.Li arm3 , +.Li arm6 , +.Li arm60 , +.Li arm600 , +.Li arm610 , +.Li arm620 , +.Li arm7 , +.Li arm7m , +.Li arm7d , +.Li arm7dm , +.Li arm7di , +.Li arm7dmi , +.Li arm70 , +.Li arm700 , +.Li arm700i , +.Li arm710 , +.Li arm710t , +.Li arm720 , +.Li arm720t , +.Li arm740t , +.Li arm710c , +.Li arm7100 , +.Li arm7500 , +.Li arm7500fe , +.Li arm7t , +.Li arm7tdmi , +.Li arm7tdmi-s , +.Li arm8 , +.Li arm810 , +.Li strongarm , +.Li strongarm1 , +.Li strongarm110 , +.Li strongarm1100 , +.Li strongarm1110 , +.Li arm9 , +.Li arm920 , +.Li arm920t , +.Li arm922t , +.Li arm940t , +.Li arm9tdmi , +.Li arm9e , +.Li arm926e , +.Li arm926ej-s , +.Li arm946e-r0 , +.Li arm946e , +.Li arm946e-s , +.Li arm966e-r0 , +.Li arm966e , +.Li arm966e-s , +.Li arm968e-s , +.Li arm10t , +.Li arm10tdmi , +.Li arm10e , +.Li arm1020 , +.Li arm1020t , +.Li arm1020e , +.Li arm1022e , +.Li arm1026ej-s , +.Li arm1136j-s , +.Li arm1136jf-s , +.Li arm1156t2-s , +.Li arm1156t2f-s , +.Li arm1176jz-s , +.Li arm1176jzf-s , +.Li mpcore , +.Li mpcorenovfp , +.Li cortex-a8 , +.Li cortex-r4 , +.Li cortex-m3 , +.Li ep9312 +(ARM920 with Cirrus Maverick coprocessor), +.Li i80200 +(Intel XScale processor) +.Li iwmmxt +(Intel(r) XScale processor with Wireless MMX(tm) technology coprocessor) and +.Li xscale . +The special name +.Li all +may be used to allow the assembler to accept instructions valid for any ARM +processor. +.Pp +In addition to the basic instruction set, the assembler can be told to accept +various extension mnemonics that extend the processor using the co-processor +instruction space. For example, +.Li -mcpu=arm920+maverick +is equivalent to specifying +.Li -mcpu=ep9312 . +The following extensions are currently supported: +.Li +maverick +.Li +iwmmxt +and +.Li +xscale . +.Pp +.It -march= Va architecture[+ Va extension...] +This option specifies the target architecture. The assembler will issue an +error message if an attempt is made to assemble an instruction which will +not execute on the target architecture. The following architecture names are +recognized: +.Li armv1 , +.Li armv2 , +.Li armv2a , +.Li armv2s , +.Li armv3 , +.Li armv3m , +.Li armv4 , +.Li armv4xm , +.Li armv4t , +.Li armv4txm , +.Li armv5 , +.Li armv5t , +.Li armv5txm , +.Li armv5te , +.Li armv5texp , +.Li armv6 , +.Li armv6j , +.Li armv6k , +.Li armv6z , +.Li armv6zk , +.Li armv7 , +.Li armv7-a , +.Li armv7-r , +.Li armv7-m , +.Li iwmmxt +and +.Li xscale . +If both +.Li -mcpu +and +.Li -march +are specified, the assembler will use the setting for +.Li -mcpu . +.Pp +The architecture option can be extended with the same instruction set extension +options as the +.Li -mcpu +option. +.Pp +.It -mfpu= Va floating-point-format +.Pp +This option specifies the floating point format to assemble for. The assembler +will issue an error message if an attempt is made to assemble an instruction +which will not execute on the target floating point unit. The following format +options are recognized: +.Li softfpa , +.Li fpe , +.Li fpe2 , +.Li fpe3 , +.Li fpa , +.Li fpa10 , +.Li fpa11 , +.Li arm7500fe , +.Li softvfp , +.Li softvfp+vfp , +.Li vfp , +.Li vfp10 , +.Li vfp10-r0 , +.Li vfp9 , +.Li vfpxd , +.Li arm1020t , +.Li arm1020e , +.Li arm1136jf-s +and +.Li maverick . +.Pp +In addition to determining which instructions are assembled, this option also +affects the way in which the +.Li .double +assembler directive behaves when assembling little-endian code. +.Pp +The default is dependent on the processor selected. For Architecture 5 or +later, the default is to assembler for VFP instructions; for earlier architectures +the default is to assemble for FPA instructions. +.Pp +.It -mthumb +This option specifies that the assembler should start assembling Thumb instructions; +that is, it should behave as though the file starts with a +.Li .code 16 +directive. +.Pp +.It -mthumb-interwork +This option specifies that the output generated by the assembler should be +marked as supporting interworking. +.Pp +.It -mapcs Li [26|32] +This option specifies that the output generated by the assembler should be +marked as supporting the indicated version of the Arm Procedure. Calling Standard. +.Pp +.It -matpcs +This option specifies that the output generated by the assembler should be +marked as supporting the Arm/Thumb Procedure Calling Standard. If enabled +this option will cause the assembler to create an empty debugging section +in the object file called .arm.atpcs. Debuggers can use this to determine +the ABI being used by. +.Pp +.It -mapcs-float +This indicates the floating point variant of the APCS should be used. In this +variant floating point arguments are passed in FP registers rather than integer +registers. +.Pp +.It -mapcs-reentrant +This indicates that the reentrant variant of the APCS should be used. This +variant supports position independent code. +.Pp +.It -mfloat-abi= Va abi +This option specifies that the output generated by the assembler should be +marked as using specified floating point ABI. The following values are recognized: +.Li soft , +.Li softfp +and +.Li hard . +.Pp +.It -meabi= Va ver +This option specifies which EABI version the produced object files should +conform to. The following values are recognized: +.Li GNU , +.Li 4 +and +.Li 5 . +.Pp +.It -EB +This option specifies that the output generated by the assembler should be +marked as being encoded for a big-endian processor. +.Pp +.It -EL +This option specifies that the output generated by the assembler should be +marked as being encoded for a little-endian processor. +.Pp +.It -k +This option specifies that the output of the assembler should be marked as +position-independent code (PIC). +.Pp +.El +.Ss Syntax +.Em Special Characters +.Pp +The presence of a +.Li @ +on a line indicates the start of a comment that extends to the end of the +current line. If a +.Li # +appears as the first character of a line, the whole line is treated as a comment. +.Pp +The +.Li ; +character can be used instead of a newline to separate statements. +.Pp +Either +.Li # +or +.Li $ +can be used to indicate immediate operands. +.Pp +*TODO* Explain about /data modifier on symbols. +.Pp +.Em Register Names +.Pp +*TODO* Explain about ARM register naming, and the predefined names. +.Pp +.Em ARM relocation generation +.Pp +Specific data relocations can be generated by putting the relocation name +in parentheses after the symbol name. For example: +.Pp +.Bd -literal -offset indent + .word foo(TARGET1) +.Ed +.Pp +This will generate an +.Li R_ARM_TARGET1 +relocation against the symbol +.Va foo . +The following relocations are supported: +.Li GOT , +.Li GOTOFF , +.Li TARGET1 , +.Li TARGET2 , +.Li SBREL , +.Li TLSGD , +.Li TLSLDM , +.Li TLSLDO , +.Li GOTTPOFF +and +.Li TPOFF . +.Pp +For compatibility with older toolchains the assembler also accepts +.Li (PLT) +after branch targets. This will generate the deprecated +.Li R_ARM_PLT32 +relocation. +.Pp +Relocations for +.Li MOVW +and +.Li MOVT +instructions can be generated by prefixing the value with +.Li #:lower16: +and +.Li #:upper16 +respectively. For example to load the 32-bit address of foo into r0: +.Pp +.Bd -literal -offset indent + MOVW r0, #:lower16:foo + MOVT r0, #:upper16:foo +.Ed +.Pp +.Ss Floating Point +The ARM family uses ieee floating-point numbers. +.Pp +.Ss ARM Machine Directives +.Bl -tag -width Ds +.It .align Va expression [, Va expression] +This is the generic +.Va .align +directive. For the ARM however if the first argument is zero (ie no alignment +is needed) the assembler will behave as if the argument had been 2 (ie pad +to the next four byte boundary). This is for compatibility with ARM's own +assembler. +.Pp +.It Va name .req Va register name +This creates an alias for +.Va register name +called +.Va name . +For example: +.Pp +.Bd -literal -offset indent + foo .req r0 +.Ed +.Pp +.It .unreq Va alias-name +This undefines a register alias which was previously defined using the +.Li req , +.Li dn +or +.Li qn +directives. For example: +.Pp +.Bd -literal -offset indent + foo .req r0 + .unreq foo +.Ed +.Pp +An error occurs if the name is undefined. Note - this pseudo op can be used +to delete builtin in register name aliases (eg 'r0'). This should only be +done if it is really necessary. +.Pp +.It Va name .dn Va register name [ Va .type] [ Va [index]] +.It Va name .qn Va register name [ Va .type] [ Va [index]] +.Pp +The +.Li dn +and +.Li qn +directives are used to create typed and/or indexed register aliases for use +in Advanced SIMD Extension (Neon) instructions. The former should be used +to create aliases of double-precision registers, and the latter to create +aliases of quad-precision registers. +.Pp +If these directives are used to create typed aliases, those aliases can be +used in Neon instructions instead of writing types after the mnemonic or after +each operand. For example: +.Pp +.Bd -literal -offset indent + x .dn d2.f32 + y .dn d3.f32 + z .dn d4.f32[1] + vmul x,y,z +.Ed +.Pp +This is equivalent to writing the following: +.Pp +.Bd -literal -offset indent + vmul.f32 d2,d3,d4[1] +.Ed +.Pp +Aliases created using +.Li dn +or +.Li qn +can be destroyed using +.Li unreq . +.Pp +.It .code Li [16|32] +This directive selects the instruction set being generated. The value 16 selects +Thumb, with the value 32 selecting ARM. +.Pp +.It .thumb +This performs the same action as +.Va .code 16 . +.Pp +.It .arm +This performs the same action as +.Va .code 32 . +.Pp +.It .force_thumb +This directive forces the selection of Thumb instructions, even if the target +processor does not support those instructions +.Pp +.It .thumb_func +This directive specifies that the following symbol is the name of a Thumb +encoded function. This information is necessary in order to allow the assembler +and linker to generate correct code for interworking between Arm and Thumb +instructions and should be used even if interworking is not going to be performed. +The presence of this directive also implies +.Li .thumb +.Pp +This directive is not neccessary when generating EABI objects. On these targets +the encoding is implicit when generating Thumb code. +.Pp +.It .thumb_set +This performs the equivalent of a +.Li .set +directive in that it creates a symbol which is an alias for another symbol +(possibly not yet defined). This directive also has the added property in +that it marks the aliased symbol as being a thumb function entry point, in +the same way that the +.Li .thumb_func +directive does. +.Pp +.It .ltorg +This directive causes the current contents of the literal pool to be dumped +into the current section (which is assumed to be the .text section) at the +current location (aligned to a word boundary). +.Li GAS +maintains a separate literal pool for each section and each sub-section. The +.Li .ltorg +directive will only affect the literal pool of the current section and sub-section. +At the end of assembly all remaining, un-empty literal pools will automatically +be dumped. +.Pp +Note - older versions of +.Li GAS +would dump the current literal pool any time a section change occurred. This +is no longer done, since it prevents accurate control of the placement of +literal pools. +.Pp +.It .pool +This is a synonym for .ltorg. +.Pp +.It .unwind_fnstart +Marks the start of a function with an unwind table entry. +.Pp +.It .unwind_fnend +Marks the end of a function with an unwind table entry. The unwind index table +entry is created when this directive is processed. +.Pp +If no personality routine has been specified then standard personality routine +0 or 1 will be used, depending on the number of unwind opcodes required. +.Pp +.It .cantunwind +Prevents unwinding through the current function. No personality routine or +exception table data is required or permitted. +.Pp +.It .personality Va name +Sets the personality routine for the current function to +.Va name . +.Pp +.It .personalityindex Va index +Sets the personality routine for the current function to the EABI standard +routine number +.Va index +.Pp +.It .handlerdata +Marks the end of the current function, and the start of the exception table +entry for that function. Anything between this directive and the +.Li .fnend +directive will be added to the exception table entry. +.Pp +Must be preceded by a +.Li .personality +or +.Li .personalityindex +directive. +.Pp +.It .save Va reglist +Generate unwinder annotations to restore the registers in +.Va reglist . +The format of +.Va reglist +is the same as the corresponding store-multiple instruction. +.Pp +.Bd -literal -offset indent + .save {r4, r5, r6, lr} + stmfd sp!, {r4, r5, r6, lr} + .save f4, 2 + sfmfd f4, 2, [sp]! + .save {d8, d9, d10} + fstmdx sp!, {d8, d9, d10} + .save {wr10, wr11} + wstrd wr11, [sp, #-8]! + wstrd wr10, [sp, #-8]! +or + .save wr11 + wstrd wr11, [sp, #-8]! + .save wr10 + wstrd wr10, [sp, #-8]! +.Ed +.Pp +.It .vsave Va vfp-reglist +Generate unwinder annotations to restore the VFP registers in +.Va vfp-reglist +using FLDMD. Also works for VFPv3 registers that are to be restored using +VLDM. The format of +.Va vfp-reglist +is the same as the corresponding store-multiple instruction. +.Pp +.Bd -literal -offset indent + .vsave {d8, d9, d10} + fstmdd sp!, {d8, d9, d10} + .vsave {d15, d16, d17} + vstm sp!, {d15, d16, d17} +.Ed +.Pp +Since FLDMX and FSTMX are now deprecated, this directive should be used in +favour of +.Li .save +for saving VFP registers for ARMv6 and above. +.Pp +.It .pad # Va count +Generate unwinder annotations for a stack adjustment of +.Va count +bytes. A positive value indicates the function prologue allocated stack space +by decrementing the stack pointer. +.Pp +.It .movsp Va reg [, # Va offset] +Tell the unwinder that +.Va reg +contains an offset from the current stack pointer. If +.Va offset +is not specified then it is assumed to be zero. +.Pp +.It .setfp Va fpreg, Va spreg [, # Va offset] +Make all unwinder annotations relaive to a frame pointer. Without this the +unwinder will use offsets from the stack pointer. +.Pp +The syntax of this directive is the same as the +.Li sub +or +.Li mov +instruction used to set the frame pointer. +.Va spreg +must be either +.Li sp +or mentioned in a previous +.Li .movsp +directive. +.Pp +.Bd -literal -offset indent +\&.movsp ip +mov ip, sp +\&... +\&.setfp fp, ip, #4 +sub fp, ip, #4 +.Ed +.Pp +.It .raw Va offset, Va byte1, ... +Insert one of more arbitary unwind opcode bytes, which are known to adjust +the stack pointer by +.Va offset +bytes. +.Pp +For example +.Li .unwind_raw 4, 0xb1, 0x01 +is equivalent to +.Li .save {r0} +.Pp +.It .cpu Va name +Select the target processor. Valid values for +.Va name +are the same as for the +.Op -mcpu +commandline option. +.Pp +.It .arch Va name +Select the target architecture. Valid values for +.Va name +are the same as for the +.Op -march +commandline option. +.Pp +.It .object_arch Va name +Override the architecture recorded in the EABI object attribute section. Valid +values for +.Va name +are the same as for the +.Li .arch +directive. Typically this is useful when code uses runtime detection of CPU +features. +.Pp +.It .fpu Va name +Select the floating point unit to assemble for. Valid values for +.Va name +are the same as for the +.Op -mfpu +commandline option. +.Pp +.It .eabi_attribute Va tag, Va value +Set the EABI object attribute number +.Va tag +to +.Va value . +The value is either a +.Li number , +.Li "string" , +or +.Li number, "string" +depending on the tag. +.Pp +.El +.Ss Opcodes +.Li as +implements all the standard ARM opcodes. It also implements several pseudo +opcodes, including several synthetic load instructions. +.Pp +.Bl -tag -width Ds +.It NOP +.Bd -literal -offset indent + nop +.Ed +.Pp +This pseudo op will always evaluate to a legal ARM instruction that does nothing. +Currently it will evaluate to MOV r0, r0. +.Pp +.It LDR +.Bd -literal -offset indent + ldr <register> , = <expression> +.Ed +.Pp +If expression evaluates to a numeric constant then a MOV or MVN instruction +will be used in place of the LDR instruction, if the constant can be generated +by either of these instructions. Otherwise the constant will be placed into +the nearest literal pool (if it not already there) and a PC relative LDR instruction +will be generated. +.Pp +.It ADR +.Bd -literal -offset indent + adr <register> <label> +.Ed +.Pp +This instruction will load the address of +.Va label +into the indicated register. The instruction will evaluate to a PC relative +ADD or SUB instruction depending upon where the label is located. If the label +is out of range, or if it is not defined in the same file (and section) as +the ADR instruction, then an error will be generated. This instruction will +not make use of the literal pool. +.Pp +.It ADRL +.Bd -literal -offset indent + adrl <register> <label> +.Ed +.Pp +This instruction will load the address of +.Va label +into the indicated register. The instruction will evaluate to one or two PC +relative ADD or SUB instructions depending upon where the label is located. +If a second instruction is not needed a NOP instruction will be generated +in its place, so that this instruction is always 8 bytes long. +.Pp +If the label is out of range, or if it is not defined in the same file (and +section) as the ADRL instruction, then an error will be generated. This instruction +will not make use of the literal pool. +.Pp +.El +For information on the ARM or Thumb instruction sets, see +.Em ARM Software Development Toolkit Reference Manual , +Advanced RISC Machines Ltd. +.Pp +.Ss Mapping Symbols +The ARM ELF specification requires that special symbols be inserted into object +files to mark certain features: +.Pp +.Bl -tag -width Ds +.It $a +At the start of a region of code containing ARM instructions. +.Pp +.It $t +At the start of a region of code containing THUMB instructions. +.Pp +.It $d +At the start of a region of data. +.Pp +.El +The assembler will automatically insert these symbols for you - there is no +need to code them yourself. Support for tagging symbols ($b, $f, $p and $m) +which is also mentioned in the current ARM ELF specification is not implemented. +This is because they have been dropped from the new EABI and so tools cannot +rely upon their presence. +.Pp +.Sh 80386 Dependent Features +The i386 version +.Li as +supports both the original Intel 386 architecture in both 16 and 32-bit mode +as well as AMD x86-64 architecture extending the Intel architecture to 64-bits. +.Pp +.Ss Options +The i386 version of +.Li as +has a few machine dependent options: +.Pp +.Bl -tag -width Ds +.It --32 | --64 +Select the word size, either 32 bits or 64 bits. Selecting 32-bit implies +Intel i386 architecture, while 64-bit implies AMD x86-64 architecture. +.Pp +These options are only available with the ELF object file format, and require +that the necessary BFD support has been included (on a 32-bit platform you +have to add --enable-64-bit-bfd to configure enable 64-bit usage and use x86-64 +as target platform). +.Pp +.It -n +By default, x86 GAS replaces multiple nop instructions used for alignment +within code sections with multi-byte nop instructions such as leal 0(%esi,1),%esi. +This switch disables the optimization. +.Pp +.It --divide +On SVR4-derived platforms, the character +.Li / +is treated as a comment character, which means that it cannot be used in expressions. +The +.Li --divide +option turns +.Li / +into a normal character. This does not disable +.Li / +at the beginning of a line starting a comment, or affect using +.Li # +for starting a comment. +.Pp +.It -march= Va CPU +This option specifies an instruction set architecture for generating instructions. +The following architectures are recognized: +.Li i8086 , +.Li i186 , +.Li i286 , +.Li i386 , +.Li i486 , +.Li i586 , +.Li i686 , +.Li pentium , +.Li pentiumpro , +.Li pentiumii , +.Li pentiumiii , +.Li pentium4 , +.Li prescott , +.Li nocona , +.Li core , +.Li core2 , +.Li k6 , +.Li k6_2 , +.Li athlon , +.Li sledgehammer , +.Li opteron , +.Li k8 , +.Li generic32 +and +.Li generic64 . +.Pp +This option only affects instructions generated by the assembler. The +.Li .arch +directive will take precedent. +.Pp +.It -mtune= Va CPU +This option specifies a processor to optimize for. When used in conjunction +with the +.Op -march +option, only instructions of the processor specified by the +.Op -march +option will be generated. +.Pp +Valid +.Va CPU +values are identical to +.Op -march= Va CPU . +.Pp +.El +.Ss AT&T Syntax versus Intel Syntax +.Li as +now supports assembly using Intel assembler syntax. +.Li .intel_syntax +selects Intel mode, and +.Li .att_syntax +switches back to the usual AT&T mode for compatibility with the output of +.Li gcc . +Either of these directives may have an optional argument, +.Li prefix , +or +.Li noprefix +specifying whether registers require a +.Li % +prefix. AT&T System V/386 assembler syntax is quite different from Intel syntax. +We mention these differences because almost all 80386 documents use Intel +syntax. Notable differences between the two syntaxes are: +.Pp +.Bl -bullet +.It +AT&T immediate operands are preceded by +.Li $ ; +Intel immediate operands are undelimited (Intel +.Li push 4 +is AT&T +.Li pushl $4 ) . +AT&T register operands are preceded by +.Li % ; +Intel register operands are undelimited. AT&T absolute (as opposed to PC relative) +jump/call operands are prefixed by +.Li * ; +they are undelimited in Intel syntax. +.Pp +.It +AT&T and Intel syntax use the opposite order for source and destination operands. +Intel +.Li add eax, 4 +is +.Li addl $4, %eax . +The +.Li source, dest +convention is maintained for compatibility with previous Unix assemblers. +Note that instructions with more than one source operand, such as the +.Li enter +instruction, do +.Em not +have reversed order. i386-Bugs. +.Pp +.It +In AT&T syntax the size of memory operands is determined from the last character +of the instruction mnemonic. Mnemonic suffixes of +.Li b , +.Li w , +.Li l +and +.Li q +specify byte (8-bit), word (16-bit), long (32-bit) and quadruple word (64-bit) +memory references. Intel syntax accomplishes this by prefixing memory operands +( +.Em not +the instruction mnemonics) with +.Li byte ptr , +.Li word ptr , +.Li dword ptr +and +.Li qword ptr . +Thus, Intel +.Li mov al, byte ptr Va foo +is +.Li movb Va foo, %al +in AT&T syntax. +.Pp +.It +Immediate form long jumps and calls are +.Li lcall/ljmp $ Va section, $ Va offset +in AT&T syntax; the Intel syntax is +.Li call/jmp far Va section: Va offset . +Also, the far return instruction is +.Li lret $ Va stack-adjust +in AT&T syntax; Intel syntax is +.Li ret far Va stack-adjust . +.Pp +.It +The AT&T assembler does not provide support for multiple section programs. +Unix style systems expect all programs to be single sections. +.El +.Pp +.Ss Instruction Naming +Instruction mnemonics are suffixed with one character modifiers which specify +the size of operands. The letters +.Li b , +.Li w , +.Li l +and +.Li q +specify byte, word, long and quadruple word operands. If no suffix is specified +by an instruction then +.Li as +tries to fill in the missing suffix based on the destination register operand +(the last one by convention). Thus, +.Li mov %ax, %bx +is equivalent to +.Li movw %ax, %bx ; +also, +.Li mov $1, %bx +is equivalent to +.Li movw $1, bx . +Note that this is incompatible with the AT&T Unix assembler which assumes +that a missing mnemonic suffix implies long operand size. (This incompatibility +does not affect compiler output since compilers always explicitly specify +the mnemonic suffix.) +.Pp +Almost all instructions have the same names in AT&T and Intel format. There +are a few exceptions. The sign extend and zero extend instructions need two +sizes to specify them. They need a size to sign/zero extend +.Em from +and a size to zero extend +.Em to . +This is accomplished by using two instruction mnemonic suffixes in AT&T syntax. +Base names for sign extend and zero extend are +.Li movs... +and +.Li movz... +in AT&T syntax ( +.Li movsx +and +.Li movzx +in Intel syntax). The instruction mnemonic suffixes are tacked on to this +base name, the +.Em from +suffix before the +.Em to +suffix. Thus, +.Li movsbl %al, %edx +is AT&T syntax for \(lqmove sign extend +.Em from +%al +.Em to +%edx.\(rq Possible suffixes, thus, are +.Li bl +(from byte to long), +.Li bw +(from byte to word), +.Li wl +(from word to long), +.Li bq +(from byte to quadruple word), +.Li wq +(from word to quadruple word), and +.Li lq +(from long to quadruple word). +.Pp +The Intel-syntax conversion instructions +.Pp +.Bl -bullet +.It +.Li cbw +--- sign-extend byte in +.Li %al +to word in +.Li %ax , +.Pp +.It +.Li cwde +--- sign-extend word in +.Li %ax +to long in +.Li %eax , +.Pp +.It +.Li cwd +--- sign-extend word in +.Li %ax +to long in +.Li %dx:%ax , +.Pp +.It +.Li cdq +--- sign-extend dword in +.Li %eax +to quad in +.Li %edx:%eax , +.Pp +.It +.Li cdqe +--- sign-extend dword in +.Li %eax +to quad in +.Li %rax +(x86-64 only), +.Pp +.It +.Li cqo +--- sign-extend quad in +.Li %rax +to octuple in +.Li %rdx:%rax +(x86-64 only), +.El +.Pp +are called +.Li cbtw , +.Li cwtl , +.Li cwtd , +.Li cltd , +.Li cltq , +and +.Li cqto +in AT&T naming. +.Li as +accepts either naming for these instructions. +.Pp +Far call/jump instructions are +.Li lcall +and +.Li ljmp +in AT&T syntax, but are +.Li call far +and +.Li jump far +in Intel convention. +.Pp +.Ss Register Naming +Register operands are always prefixed with +.Li % . +The 80386 registers consist of +.Pp +.Bl -bullet +.It +the 8 32-bit registers +.Li %eax +(the accumulator), +.Li %ebx , +.Li %ecx , +.Li %edx , +.Li %edi , +.Li %esi , +.Li %ebp +(the frame pointer), and +.Li %esp +(the stack pointer). +.Pp +.It +the 8 16-bit low-ends of these: +.Li %ax , +.Li %bx , +.Li %cx , +.Li %dx , +.Li %di , +.Li %si , +.Li %bp , +and +.Li %sp . +.Pp +.It +the 8 8-bit registers: +.Li %ah , +.Li %al , +.Li %bh , +.Li %bl , +.Li %ch , +.Li %cl , +.Li %dh , +and +.Li %dl +(These are the high-bytes and low-bytes of +.Li %ax , +.Li %bx , +.Li %cx , +and +.Li %dx ) +.Pp +.It +the 6 section registers +.Li %cs +(code section), +.Li %ds +(data section), +.Li %ss +(stack section), +.Li %es , +.Li %fs , +and +.Li %gs . +.Pp +.It +the 3 processor control registers +.Li %cr0 , +.Li %cr2 , +and +.Li %cr3 . +.Pp +.It +the 6 debug registers +.Li %db0 , +.Li %db1 , +.Li %db2 , +.Li %db3 , +.Li %db6 , +and +.Li %db7 . +.Pp +.It +the 2 test registers +.Li %tr6 +and +.Li %tr7 . +.Pp +.It +the 8 floating point register stack +.Li %st +or equivalently +.Li %st(0) , +.Li %st(1) , +.Li %st(2) , +.Li %st(3) , +.Li %st(4) , +.Li %st(5) , +.Li %st(6) , +and +.Li %st(7) . +These registers are overloaded by 8 MMX registers +.Li %mm0 , +.Li %mm1 , +.Li %mm2 , +.Li %mm3 , +.Li %mm4 , +.Li %mm5 , +.Li %mm6 +and +.Li %mm7 . +.Pp +.It +the 8 SSE registers registers +.Li %xmm0 , +.Li %xmm1 , +.Li %xmm2 , +.Li %xmm3 , +.Li %xmm4 , +.Li %xmm5 , +.Li %xmm6 +and +.Li %xmm7 . +.El +.Pp +The AMD x86-64 architecture extends the register set by: +.Pp +.Bl -bullet +.It +enhancing the 8 32-bit registers to 64-bit: +.Li %rax +(the accumulator), +.Li %rbx , +.Li %rcx , +.Li %rdx , +.Li %rdi , +.Li %rsi , +.Li %rbp +(the frame pointer), +.Li %rsp +(the stack pointer) +.Pp +.It +the 8 extended registers +.Li %r8 +-- +.Li %r15 . +.Pp +.It +the 8 32-bit low ends of the extended registers: +.Li %r8d +-- +.Li %r15d +.Pp +.It +the 8 16-bit low ends of the extended registers: +.Li %r8w +-- +.Li %r15w +.Pp +.It +the 8 8-bit low ends of the extended registers: +.Li %r8b +-- +.Li %r15b +.Pp +.It +the 4 8-bit registers: +.Li %sil , +.Li %dil , +.Li %bpl , +.Li %spl . +.Pp +.It +the 8 debug registers: +.Li %db8 +-- +.Li %db15 . +.Pp +.It +the 8 SSE registers: +.Li %xmm8 +-- +.Li %xmm15 . +.El +.Pp +.Ss Instruction Prefixes +Instruction prefixes are used to modify the following instruction. They are +used to repeat string instructions, to provide section overrides, to perform +bus lock operations, and to change operand and address sizes. (Most instructions +that normally operate on 32-bit operands will use 16-bit operands if the instruction +has an \(lqoperand size\(rq prefix.) Instruction prefixes are best written on the +same line as the instruction they act upon. For example, the +.Li scas +(scan string) instruction is repeated with: +.Pp +.Bd -literal -offset indent + repne scas %es:(%edi),%al +.Ed +.Pp +You may also place prefixes on the lines immediately preceding the instruction, +but this circumvents checks that +.Li as +does with prefixes, and will not work with all prefixes. +.Pp +Here is a list of instruction prefixes: +.Pp +.Bl -bullet +.It +Section override prefixes +.Li cs , +.Li ds , +.Li ss , +.Li es , +.Li fs , +.Li gs . +These are automatically added by specifying using the +.Va section +: +.Va memory-operand +form for memory references. +.Pp +.It +Operand/Address size prefixes +.Li data16 +and +.Li addr16 +change 32-bit operands/addresses into 16-bit operands/addresses, while +.Li data32 +and +.Li addr32 +change 16-bit ones (in a +.Li .code16 +section) into 32-bit operands/addresses. These prefixes +.Em must +appear on the same line of code as the instruction they modify. For example, +in a 16-bit +.Li .code16 +section, you might write: +.Pp +.Bd -literal -offset indent + addr32 jmpl *(%ebx) +.Ed +.Pp +.It +The bus lock prefix +.Li lock +inhibits interrupts during execution of the instruction it precedes. (This +is only valid with certain instructions; see a 80386 manual for details). +.Pp +.It +The wait for coprocessor prefix +.Li wait +waits for the coprocessor to complete the current instruction. This should +never be needed for the 80386/80387 combination. +.Pp +.It +The +.Li rep , +.Li repe , +and +.Li repne +prefixes are added to string instructions to make them repeat +.Li %ecx +times ( +.Li %cx +times if the current address size is 16-bits). +.It +The +.Li rex +family of prefixes is used by x86-64 to encode extensions to i386 instruction +set. The +.Li rex +prefix has four bits --- an operand size overwrite ( +.Li 64 ) +used to change operand size from 32-bit to 64-bit and X, Y and Z extensions +bits used to extend the register set. +.Pp +You may write the +.Li rex +prefixes directly. The +.Li rex64xyz +instruction emits +.Li rex +prefix with all the bits set. By omitting the +.Li 64 , +.Li x , +.Li y +or +.Li z +you may write other prefixes as well. Normally, there is no need to write +the prefixes explicitly, since gas will automatically generate them based +on the instruction operands. +.El +.Pp +.Ss Memory References +An Intel syntax indirect memory reference of the form +.Pp +.Bd -literal -offset indent +section:[base + index*scale + disp] +.Ed +.Pp +is translated into the AT&T syntax +.Pp +.Bd -literal -offset indent +section:disp(base, index, scale) +.Ed +.Pp +where +.Va base +and +.Va index +are the optional 32-bit base and index registers, +.Va disp +is the optional displacement, and +.Va scale , +taking the values 1, 2, 4, and 8, multiplies +.Va index +to calculate the address of the operand. If no +.Va scale +is specified, +.Va scale +is taken to be 1. +.Va section +specifies the optional section register for the memory operand, and may override +the default section register (see a 80386 manual for section register defaults). +Note that section overrides in AT&T syntax +.Em must +be preceded by a +.Li % . +If you specify a section override which coincides with the default section +register, +.Li as +does +.Em not +output any section register override prefixes to assemble the given instruction. +Thus, section overrides can be specified to emphasize which section register +is used for a given memory operand. +.Pp +Here are some examples of Intel and AT&T style memory references: +.Pp +.Bl -tag -width Ds +.It AT&T: Li -4(%ebp), Intel: Li [ebp - 4] +.Va base +is +.Li %ebp ; +.Va disp +is +.Li -4 . +.Va section +is missing, and the default section is used ( +.Li %ss +for addressing with +.Li %ebp +as the base register). +.Va index , +.Va scale +are both missing. +.Pp +.It AT&T: Li foo(,%eax,4), Intel: Li [foo + eax*4] +.Va index +is +.Li %eax +(scaled by a +.Va scale +4); +.Va disp +is +.Li foo . +All other fields are missing. The section register here defaults to +.Li %ds . +.Pp +.It AT&T: Li foo(,1); Intel Li [foo] +This uses the value pointed to by +.Li foo +as a memory operand. Note that +.Va base +and +.Va index +are both missing, but there is only +.Em one +.Li , . +This is a syntactic exception. +.Pp +.It AT&T: Li %gs:foo; Intel Li gs:foo +This selects the contents of the variable +.Li foo +with section register +.Va section +being +.Li %gs . +.El +.Pp +Absolute (as opposed to PC relative) call and jump operands must be prefixed +with +.Li * . +If no +.Li * +is specified, +.Li as +always chooses PC relative addressing for jump/call labels. +.Pp +Any instruction that has a memory operand, but no register operand, +.Em must +specify its size (byte, word, long, or quadruple) with an instruction mnemonic +suffix ( +.Li b , +.Li w , +.Li l +or +.Li q , +respectively). +.Pp +The x86-64 architecture adds an RIP (instruction pointer relative) addressing. +This addressing mode is specified by using +.Li rip +as a base register. Only constant offsets are valid. For example: +.Pp +.Bl -tag -width Ds +.It AT&T: Li 1234(%rip), Intel: Li [rip + 1234] +Points to the address 1234 bytes past the end of the current instruction. +.Pp +.It AT&T: Li symbol(%rip), Intel: Li [rip + symbol] +Points to the +.Li symbol +in RIP relative way, this is shorter than the default absolute addressing. +.El +.Pp +Other addressing modes remain unchanged in x86-64 architecture, except registers +used are 64-bit instead of 32-bit. +.Pp +.Ss Handling of Jump Instructions +Jump instructions are always optimized to use the smallest possible displacements. +This is accomplished by using byte (8-bit) displacement jumps whenever the +target is sufficiently close. If a byte displacement is insufficient a long +displacement is used. We do not support word (16-bit) displacement jumps in +32-bit mode (i.e. prefixing the jump instruction with the +.Li data16 +instruction prefix), since the 80386 insists upon masking +.Li %eip +to 16 bits after the word displacement is added. (See alsosee Section +.Dq i386-Arch ) +.Pp +Note that the +.Li jcxz , +.Li jecxz , +.Li loop , +.Li loopz , +.Li loope , +.Li loopnz +and +.Li loopne +instructions only come in byte displacements, so that if you use these instructions +( +.Li gcc +does not use them) you may get an error message (and incorrect code). The +AT&T 80386 assembler tries to get around this problem by expanding +.Li jcxz foo +to +.Pp +.Bd -literal -offset indent + jcxz cx_zero + jmp cx_nonzero +cx_zero: jmp foo +cx_nonzero: +.Ed +.Pp +.Ss Floating Point +All 80387 floating point types except packed BCD are supported. (BCD support +may be added without much difficulty). These data types are 16-, 32-, and +64- bit integers, and single (32-bit), double (64-bit), and extended (80-bit) +precision floating point. Each supported type has an instruction mnemonic +suffix and a constructor associated with it. Instruction mnemonic suffixes +specify the operand's data type. Constructors build these data types into +memory. +.Pp +.Bl -bullet +.It +Floating point constructors are +.Li .float +or +.Li .single , +.Li .double , +and +.Li .tfloat +for 32-, 64-, and 80-bit formats. These correspond to instruction mnemonic +suffixes +.Li s , +.Li l , +and +.Li t . +.Li t +stands for 80-bit (ten byte) real. The 80387 only supports this format via +the +.Li fldt +(load 80-bit real to stack top) and +.Li fstpt +(store 80-bit real and pop stack) instructions. +.Pp +.It +Integer constructors are +.Li .word , +.Li .long +or +.Li .int , +and +.Li .quad +for the 16-, 32-, and 64-bit integer formats. The corresponding instruction +mnemonic suffixes are +.Li s +(single), +.Li l +(long), and +.Li q +(quad). As with the 80-bit real format, the 64-bit +.Li q +format is only present in the +.Li fildq +(load quad integer to stack top) and +.Li fistpq +(store quad integer and pop stack) instructions. +.El +.Pp +Register to register operations should not use instruction mnemonic suffixes. +.Li fstl %st, %st(1) +will give a warning, and be assembled as if you wrote +.Li fst %st, %st(1) , +since all register to register operations use 80-bit floating point operands. +(Contrast this with +.Li fstl %st, mem , +which converts +.Li %st +from 80-bit to 64-bit floating point format, then stores the result in the +4 byte location +.Li mem ) +.Pp +.Ss Intel's MMX and AMD's 3DNow! SIMD Operations +.Li as +supports Intel's MMX instruction set (SIMD instructions for integer data), +available on Intel's Pentium MMX processors and Pentium II processors, AMD's +K6 and K6-2 processors, Cyrix' M2 processor, and probably others. It also +supports AMD's 3DNow! instruction set (SIMD instructions for 32-bit floating +point data) available on AMD's K6-2 processor and possibly others in the future. +.Pp +Currently, +.Li as +does not support Intel's floating point SIMD, Katmai (KNI). +.Pp +The eight 64-bit MMX operands, also used by 3DNow!, are called +.Li %mm0 , +.Li %mm1 , +\&... +.Li %mm7 . +They contain eight 8-bit integers, four 16-bit integers, two 32-bit integers, +one 64-bit integer, or two 32-bit floating point values. The MMX registers +cannot be used at the same time as the floating point stack. +.Pp +See Intel and AMD documentation, keeping in mind that the operand order in +instructions is reversed from the Intel syntax. +.Pp +.Ss Writing 16-bit Code +While +.Li as +normally writes only \(lqpure\(rq 32-bit i386 code or 64-bit x86-64 code depending +on the default configuration, it also supports writing code to run in real +mode or in 16-bit protected mode code segments. To do this, put a +.Li .code16 +or +.Li .code16gcc +directive before the assembly language instructions to be run in 16-bit mode. +You can switch +.Li as +back to writing normal 32-bit code with the +.Li .code32 +directive. +.Pp +.Li .code16gcc +provides experimental support for generating 16-bit code from gcc, and differs +from +.Li .code16 +in that +.Li call , +.Li ret , +.Li enter , +.Li leave , +.Li push , +.Li pop , +.Li pusha , +.Li popa , +.Li pushf , +and +.Li popf +instructions default to 32-bit size. This is so that the stack pointer is +manipulated in the same way over function calls, allowing access to function +parameters at the same stack offsets as in 32-bit mode. +.Li .code16gcc +also automatically adds address size prefixes where necessary to use the 32-bit +addressing modes that gcc generates. +.Pp +The code which +.Li as +generates in 16-bit mode will not necessarily run on a 16-bit pre-80386 processor. +To write code that runs on such a processor, you must refrain from using +.Em any +32-bit constructs which require +.Li as +to output address or operand size prefixes. +.Pp +Note that writing 16-bit code instructions by explicitly specifying a prefix +or an instruction mnemonic suffix within a 32-bit code section generates different +machine instructions than those generated for a 16-bit code segment. In a +32-bit code section, the following code generates the machine opcode bytes +.Li 66 6a 04 , +which pushes the value +.Li 4 +onto the stack, decrementing +.Li %esp +by 2. +.Pp +.Bd -literal -offset indent + pushw $4 +.Ed +.Pp +The same code in a 16-bit code section would generate the machine opcode bytes +.Li 6a 04 +(i.e., without the operand size prefix), which is correct since the processor +default operand size is assumed to be 16 bits in a 16-bit code section. +.Pp +.Ss AT&T Syntax bugs +The UnixWare assembler, and probably other AT&T derived ix86 Unix assemblers, +generate floating point instructions with reversed source and destination +registers in certain cases. Unfortunately, gcc and possibly many other programs +use this reversed syntax, so we're stuck with it. +.Pp +For example +.Pp +.Bd -literal -offset indent + fsub %st,%st(3) +.Ed +results in +.Li %st(3) +being updated to +.Li %st - %st(3) +rather than the expected +.Li %st(3) - %st . +This happens with all the non-commutative arithmetic floating point operations +with two register operands where the source register is +.Li %st +and the destination register is +.Li %st(i) . +.Pp +.Ss Specifying CPU Architecture +.Li as +may be told to assemble for a particular CPU (sub-)architecture with the +.Li .arch Va cpu_type +directive. This directive enables a warning when gas detects an instruction +that is not supported on the CPU specified. The choices for +.Va cpu_type +are: +.Pp +.TS +l l l l. + +i8086 i186 i286 i386 +i486 i586 i686 pentium +pentiumpro pentiumii pentiumiii pentium4 +prescott nocona core core2 +amdfam10 +k6 athlon sledgehammer k8 +\&.mmx .sse .sse2 .sse3 +\&.ssse3 .sse4.1 .sse4.2 .sse4 +\&.sse4a .3dnow .3dnowa .padlock +\&.pacifica .svme .abm +.TE +.Pp +Apart from the warning, there are only two other effects on +.Li as +operation; Firstly, if you specify a CPU other than +.Li i486 , +then shift by one instructions such as +.Li sarl $1, %eax +will automatically use a two byte opcode sequence. The larger three byte opcode +sequence is used on the 486 (and when no architecture is specified) because +it executes faster on the 486. Note that you can explicitly request the two +byte opcode by writing +.Li sarl %eax . +Secondly, if you specify +.Li i8086 , +.Li i186 , +or +.Li i286 , +.Em and +.Li .code16 +or +.Li .code16gcc +then byte offset conditional jumps will be promoted when necessary to a two +instruction sequence consisting of a conditional jump of the opposite sense +around an unconditional jump to the target. +.Pp +Following the CPU architecture (but not a sub-architecture, which are those +starting with a dot), you may specify +.Li jumps +or +.Li nojumps +to control automatic promotion of conditional jumps. +.Li jumps +is the default, and enables jump promotion; All external jumps will be of +the long variety, and file-local jumps will be promoted as necessary. (see Section +.Dq i386-Jumps ) +.Li nojumps +leaves external conditional jumps as byte offset jumps, and warns about file-local +conditional jumps that +.Li as +promotes. Unconditional jumps are treated as for +.Li jumps . +.Pp +For example +.Pp +.Bd -literal -offset indent + .arch i8086,nojumps +.Ed +.Pp +.Ss Notes +There is some trickery concerning the +.Li mul +and +.Li imul +instructions that deserves mention. The 16-, 32-, 64- and 128-bit expanding +multiplies (base opcode +.Li 0xf6 ; +extension 4 for +.Li mul +and 5 for +.Li imul ) +can be output only in the one operand form. Thus, +.Li imul %ebx, %eax +does +.Em not +select the expanding multiply; the expanding multiply would clobber the +.Li %edx +register, and this would confuse +.Li gcc +output. Use +.Li imul %ebx +to get the 64-bit product in +.Li %edx:%eax . +.Pp +We have added a two operand form of +.Li imul +when the first operand is an immediate mode expression and the second operand +is a register. This is just a shorthand, so that, multiplying +.Li %eax +by 69, for example, can be done with +.Li imul $69, %eax +rather than +.Li imul $69, %eax, %eax . +.Pp +.Sh IA-64 Dependent Features +.Ss Options +.Bl -tag -width Ds +.It -mconstant-gp +This option instructs the assembler to mark the resulting object file as using +the \(lqconstant GP\(rq model. With this model, it is assumed that the entire program +uses a single global pointer (GP) value. Note that this option does not in +any fashion affect the machine code emitted by the assembler. All it does +is turn on the EF_IA_64_CONS_GP flag in the ELF file header. +.Pp +.It -mauto-pic +This option instructs the assembler to mark the resulting object file as using +the \(lqconstant GP without function descriptor\(rq data model. This model is like +the \(lqconstant GP\(rq model, except that it additionally does away with function +descriptors. What this means is that the address of a function refers directly +to the function's code entry-point. Normally, such an address would refer +to a function descriptor, which contains both the code entry-point and the +GP-value needed by the function. Note that this option does not in any fashion +affect the machine code emitted by the assembler. All it does is turn on the +EF_IA_64_NOFUNCDESC_CONS_GP flag in the ELF file header. +.Pp +.It -milp32 +.It -milp64 +.It -mlp64 +.It -mp64 +These options select the data model. The assembler defaults to +.Li -mlp64 +(LP64 data model). +.Pp +.It -mle +.It -mbe +These options select the byte order. The +.Li -mle +option selects little-endian byte order (default) and +.Li -mbe +selects big-endian byte order. Note that IA-64 machine code always uses little-endian +byte order. +.Pp +.It -mtune=itanium1 +.It -mtune=itanium2 +Tune for a particular IA-64 CPU, +.Va itanium1 +or +.Va itanium2 . +The default is +.Va itanium2 . +.Pp +.It -munwind-check=warning +.It -munwind-check=error +These options control what the assembler will do when performing consistency +checks on unwind directives. +.Li -munwind-check=warning +will make the assembler issue a warning when an unwind directive check fails. +This is the default. +.Li -munwind-check=error +will make the assembler issue an error when an unwind directive check fails. +.Pp +.It -mhint.b=ok +.It -mhint.b=warning +.It -mhint.b=error +These options control what the assembler will do when the +.Li hint.b +instruction is used. +.Li -mhint.b=ok +will make the assembler accept +.Li hint.b . +.Li -mint.b=warning +will make the assembler issue a warning when +.Li hint.b +is used. +.Li -mhint.b=error +will make the assembler treat +.Li hint.b +as an error, which is the default. +.Pp +.It -x +.It -xexplicit +These options turn on dependency violation checking. +.Pp +.It -xauto +This option instructs the assembler to automatically insert stop bits where +necessary to remove dependency violations. This is the default mode. +.Pp +.It -xnone +This option turns off dependency violation checking. +.Pp +.It -xdebug +This turns on debug output intended to help tracking down bugs in the dependency +violation checker. +.Pp +.It -xdebugn +This is a shortcut for -xnone -xdebug. +.Pp +.It -xdebugx +This is a shortcut for -xexplicit -xdebug. +.Pp +.El +.Ss Syntax +The assembler syntax closely follows the IA-64 Assembly Language Reference +Guide. +.Pp +.Em Special Characters +.Pp +.Li // +is the line comment token. +.Pp +.Li ; +can be used instead of a newline to separate statements. +.Pp +.Em Register Names +.Pp +The 128 integer registers are referred to as +.Li r Va n . +The 128 floating-point registers are referred to as +.Li f Va n . +The 128 application registers are referred to as +.Li ar Va n . +The 128 control registers are referred to as +.Li cr Va n . +The 64 one-bit predicate registers are referred to as +.Li p Va n . +The 8 branch registers are referred to as +.Li b Va n . +In addition, the assembler defines a number of aliases: +.Li gp +( +.Li r1 ) , +.Li sp +( +.Li r12 ) , +.Li rp +( +.Li b0 ) , +.Li ret0 +( +.Li r8 ) , +.Li ret1 +( +.Li r9 ) , +.Li ret2 +( +.Li r10 ) , +.Li ret3 +( +.Li r9 ) , +.Li farg Va n +( +.Li f8+ Va n ) , +and +.Li fret Va n +( +.Li f8+ Va n ) . +.Pp +For convenience, the assembler also defines aliases for all named application +and control registers. For example, +.Li ar.bsp +refers to the register backing store pointer ( +.Li ar17 ) . +Similarly, +.Li cr.eoi +refers to the end-of-interrupt register ( +.Li cr67 ) . +.Pp +.Em IA-64 Processor-Status-Register (PSR) Bit Names +.Pp +The assembler defines bit masks for each of the bits in the IA-64 processor +status register. For example, +.Li psr.ic +corresponds to a value of 0x2000. These masks are primarily intended for use +with the +.Li ssm +/ +.Li sum +and +.Li rsm +/ +.Li rum +instructions, but they can be used anywhere else where an integer constant +is expected. +.Pp +.Ss Opcodes +For detailed information on the IA-64 machine instruction set, see the +.Lk http://developer.intel.com/design/itanium/arch_spec.htm . +.Pp +.Sh MIPS Dependent Features +GNU +.Li as +for mips architectures supports several different mips processors, and MIPS +ISA levels I through V, MIPS32, and MIPS64. For information about the mips +instruction set, see +.Em MIPS RISC Architecture , +by Kane and Heindrich (Prentice-Hall). For an overview of mips assembly conventions, +see \(lqAppendix D: Assembly Language Programming\(rq in the same work. +.Pp +.Ss Assembler options +The mips configurations of GNU +.Li as +support these special options: +.Pp +.Bl -tag -width Ds +.It -G Va num +This option sets the largest size of an object that can be referenced implicitly +with the +.Li gp +register. It is only accepted for targets that use ecoff format. The default +value is 8. +.Pp +.It -EB +.It -EL +Any mips configuration of +.Li as +can select big-endian or little-endian output at run time (unlike the other +GNU development tools, which must be configured for one or the other). Use +.Li -EB +to select big-endian output, and +.Li -EL +for little-endian. +.Pp +.It -KPIC +Generate SVR4-style PIC. This option tells the assembler to generate SVR4-style +position-independent macro expansions. It also tells the assembler to mark +the output file as PIC. +.Pp +.It -mvxworks-pic +Generate VxWorks PIC. This option tells the assembler to generate VxWorks-style +position-independent macro expansions. +.Pp +.It -mips1 +.It -mips2 +.It -mips3 +.It -mips4 +.It -mips5 +.It -mips32 +.It -mips32r2 +.It -mips64 +.It -mips64r2 +Generate code for a particular MIPS Instruction Set Architecture level. +.Li -mips1 +corresponds to the r2000 and r3000 processors, +.Li -mips2 +to the r6000 processor, +.Li -mips3 +to the r4000 processor, and +.Li -mips4 +to the r8000 and r10000 processors. +.Li -mips5 , +.Li -mips32 , +.Li -mips32r2 , +.Li -mips64 , +and +.Li -mips64r2 +correspond to generic MIPS V, MIPS32, MIPS32 Release 2, MIPS64, and MIPS64 +Release 2 ISA processors, respectively. You can also switch instruction sets +during the assembly; see MIPS ISA, Directives to override the ISA level. +.Pp +.It -mgp32 +.It -mfp32 +Some macros have different expansions for 32-bit and 64-bit registers. The +register sizes are normally inferred from the ISA and ABI, but these flags +force a certain group of registers to be treated as 32 bits wide at all times. +.Li -mgp32 +controls the size of general-purpose registers and +.Li -mfp32 +controls the size of floating-point registers. +.Pp +The +.Li .set gp=32 +and +.Li .set fp=32 +directives allow the size of registers to be changed for parts of an object. +The default value is restored by +.Li .set gp=default +and +.Li .set fp=default . +.Pp +On some MIPS variants there is a 32-bit mode flag; when this flag is set, +64-bit instructions generate a trap. Also, some 32-bit OSes only save the +32-bit registers on a context switch, so it is essential never to use the +64-bit registers. +.Pp +.It -mgp64 +.It -mfp64 +Assume that 64-bit registers are available. This is provided in the interests +of symmetry with +.Li -mgp32 +and +.Li -mfp32 . +.Pp +The +.Li .set gp=64 +and +.Li .set fp=64 +directives allow the size of registers to be changed for parts of an object. +The default value is restored by +.Li .set gp=default +and +.Li .set fp=default . +.Pp +.It -mips16 +.It -no-mips16 +Generate code for the MIPS 16 processor. This is equivalent to putting +.Li .set mips16 +at the start of the assembly file. +.Li -no-mips16 +turns off this option. +.Pp +.It -msmartmips +.It -mno-smartmips +Enables the SmartMIPS extensions to the MIPS32 instruction set, which provides +a number of new instructions which target smartcard and cryptographic applications. +This is equivalent to putting +.Li .set smartmips +at the start of the assembly file. +.Li -mno-smartmips +turns off this option. +.Pp +.It -mips3d +.It -no-mips3d +Generate code for the MIPS-3D Application Specific Extension. This tells the +assembler to accept MIPS-3D instructions. +.Li -no-mips3d +turns off this option. +.Pp +.It -mdmx +.It -no-mdmx +Generate code for the MDMX Application Specific Extension. This tells the +assembler to accept MDMX instructions. +.Li -no-mdmx +turns off this option. +.Pp +.It -mdsp +.It -mno-dsp +Generate code for the DSP Release 1 Application Specific Extension. This tells +the assembler to accept DSP Release 1 instructions. +.Li -mno-dsp +turns off this option. +.Pp +.It -mdspr2 +.It -mno-dspr2 +Generate code for the DSP Release 2 Application Specific Extension. This option +implies -mdsp. This tells the assembler to accept DSP Release 2 instructions. +.Li -mno-dspr2 +turns off this option. +.Pp +.It -mmt +.It -mno-mt +Generate code for the MT Application Specific Extension. This tells the assembler +to accept MT instructions. +.Li -mno-mt +turns off this option. +.Pp +.It -mfix7000 +.It -mno-fix7000 +Cause nops to be inserted if the read of the destination register of an mfhi +or mflo instruction occurs in the following two instructions. +.Pp +.It -mfix-vr4120 +.It -no-mfix-vr4120 +Insert nops to work around certain VR4120 errata. This option is intended +to be used on GCC-generated code: it is not designed to catch all problems +in hand-written assembler code. +.Pp +.It -mfix-vr4130 +.It -no-mfix-vr4130 +Insert nops to work around the VR4130 +.Li mflo +/ +.Li mfhi +errata. +.Pp +.It -m4010 +.It -no-m4010 +Generate code for the LSI r4010 chip. This tells the assembler to accept the +r4010 specific instructions ( +.Li addciu , +.Li ffc , +etc.), and to not schedule +.Li nop +instructions around accesses to the +.Li HI +and +.Li LO +registers. +.Li -no-m4010 +turns off this option. +.Pp +.It -m4650 +.It -no-m4650 +Generate code for the MIPS r4650 chip. This tells the assembler to accept +the +.Li mad +and +.Li madu +instruction, and to not schedule +.Li nop +instructions around accesses to the +.Li HI +and +.Li LO +registers. +.Li -no-m4650 +turns off this option. +.Pp +.It -m3900 +.It -no-m3900 +.It -m4100 +.It -no-m4100 +For each option +.Li -m Va nnnn , +generate code for the MIPS r +.Va nnnn +chip. This tells the assembler to accept instructions specific to that chip, +and to schedule for that chip's hazards. +.Pp +.It -march= Va cpu +Generate code for a particular MIPS cpu. It is exactly equivalent to +.Li -m Va cpu , +except that there are more value of +.Va cpu +understood. Valid +.Va cpu +value are: +.Pp +.Qo +2000, 3000, 3900, 4000, 4010, 4100, 4111, vr4120, vr4130, vr4181, 4300, 4400, +4600, 4650, 5000, rm5200, rm5230, rm5231, rm5261, rm5721, vr5400, vr5500, +6000, rm7000, 8000, rm9000, 10000, 12000, 4kc, 4km, 4kp, 4ksc, 4kec, 4kem, +4kep, 4ksd, m4k, m4kp, 24kc, 24kf, 24kx, 24kec, 24kef, 24kex, 34kc, 34kf, +34kx, 74kc, 74kf, 74kx, 5kc, 5kf, 20kc, 25kf, sb1, sb1a +.Qc +.Pp +.It -mtune= Va cpu +Schedule and tune for a particular MIPS cpu. Valid +.Va cpu +values are identical to +.Li -march= Va cpu . +.Pp +.It -mabi= Va abi +Record which ABI the source code uses. The recognized arguments are: +.Li 32 , +.Li n32 , +.Li o64 , +.Li 64 +and +.Li eabi . +.Pp +.It -msym32 +.It -mno-sym32 +Equivalent to adding +.Li .set sym32 +or +.Li .set nosym32 +to the beginning of the assembler input.See Section +.Dq MIPS symbol sizes . +.Pp +.It -nocpp +This option is ignored. It is accepted for command-line compatibility with +other assemblers, which use it to turn off C style preprocessing. With GNU +.Li as , +there is no need for +.Li -nocpp , +because the GNU assembler itself never runs the C preprocessor. +.Pp +.It --construct-floats +.It --no-construct-floats +The +.Li --no-construct-floats +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. This feature is useful +if the processor support the FR bit in its status register, and this bit is +known (by the programmer) to be set. This bit prevents the aliasing of the +double width register by the single width registers. +.Pp +By default +.Li --construct-floats +is selected, allowing construction of these floating point constants. +.Pp +.It --trap +.It --no-break +.Li as +automatically macro expands certain division and multiplication instructions +to check for overflow and division by zero. This option causes +.Li as +to generate code to take a trap exception rather than a break exception when +an error is detected. The trap instructions are only supported at Instruction +Set Architecture level 2 and higher. +.Pp +.It --break +.It --no-trap +Generate code to take a break exception rather than a trap exception when +an error is detected. This is the default. +.Pp +.It -mpdr +.It -mno-pdr +Control generation of +.Li .pdr +sections. Off by default on IRIX, on elsewhere. +.Pp +.It -mshared +.It -mno-shared +When generating code using the Unix calling conventions (selected by +.Li -KPIC +or +.Li -mcall_shared ) , +gas will normally generate code which can go into a shared library. The +.Li -mno-shared +option tells gas to generate code which uses the calling convention, but can +not go into a shared library. The resulting code is slightly more efficient. +This option only affects the handling of the +.Li .cpload +and +.Li .cpsetup +pseudo-ops. +.El +.Pp +.Ss MIPS ECOFF object code +Assembling for a mips ecoff target supports some additional sections besides +the usual +.Li .text , +.Li .data +and +.Li .bss . +The additional sections are +.Li .rdata , +used for read-only data, +.Li .sdata , +used for small data, and +.Li .sbss , +used for small common objects. +.Pp +When assembling for ecoff, the assembler uses the +.Li $gp +( +.Li $28 ) +register to form the address of a \(lqsmall object\(rq. Any object in the +.Li .sdata +or +.Li .sbss +sections is considered \(lqsmall\(rq in this sense. For external objects, or for objects +in the +.Li .bss +section, you can use the +.Li gcc +.Li -G +option to control the size of objects addressed via +.Li $gp ; +the default value is 8, meaning that a reference to any object eight bytes +or smaller uses +.Li $gp . +Passing +.Li -G 0 +to +.Li as +prevents it from using the +.Li $gp +register on the basis of object size (but the assembler uses +.Li $gp +for objects in +.Li .sdata +or +.Li sbss +in any case). The size of an object in the +.Li .bss +section is set by the +.Li .comm +or +.Li .lcomm +directive that defines it. The size of an external object may be set with +the +.Li .extern +directive. For example, +.Li .extern sym,4 +declares that the object at +.Li sym +is 4 bytes in length, whie leaving +.Li sym +otherwise undefined. +.Pp +Using small ecoff objects requires linker support, and assumes that the +.Li $gp +register is correctly initialized (normally done automatically by the startup +code). mips ecoff assembly code must not modify the +.Li $gp +register. +.Pp +.Ss Directives for debugging information +mips ecoff +.Li as +supports several directives used for generating debugging information which +are not support by traditional mips assemblers. These are +.Li .def , +.Li .endef , +.Li .dim , +.Li .file , +.Li .scl , +.Li .size , +.Li .tag , +.Li .type , +.Li .val , +.Li .stabd , +.Li .stabn , +and +.Li .stabs . +The debugging information generated by the three +.Li .stab +directives can only be read by gdb, not by traditional mips debuggers (this +enhancement is required to fully support C++ debugging). These directives +are primarily used by compilers, not assembly language programmers! +.Pp +.Ss Directives to override the size of symbols +The n64 ABI allows symbols to have any 64-bit value. Although this provides +a great deal of flexibility, it means that some macros have much longer expansions +than their 32-bit counterparts. For example, the non-PIC expansion of +.Li dla $4,sym +is usually: +.Pp +.Bd -literal -offset indent +lui $4,%highest(sym) +lui $1,%hi(sym) +daddiu $4,$4,%higher(sym) +daddiu $1,$1,%lo(sym) +dsll32 $4,$4,0 +daddu $4,$4,$1 +.Ed +.Pp +whereas the 32-bit expansion is simply: +.Pp +.Bd -literal -offset indent +lui $4,%hi(sym) +daddiu $4,$4,%lo(sym) +.Ed +.Pp +n64 code is sometimes constructed in such a way that all symbolic constants +are known to have 32-bit values, and in such cases, it's preferable to use +the 32-bit expansion instead of the 64-bit expansion. +.Pp +You can use the +.Li .set sym32 +directive to tell the assembler that, from this point on, all expressions +of the form +.Li Va symbol +or +.Li Va symbol + Va offset +have 32-bit values. For example: +.Pp +.Bd -literal -offset indent +\&.set sym32 +dla $4,sym +lw $4,sym+16 +sw $4,sym+0x8000($4) +.Ed +.Pp +will cause the assembler to treat +.Li sym , +.Li sym+16 +and +.Li sym+0x8000 +as 32-bit values. The handling of non-symbolic addresses is not affected. +.Pp +The directive +.Li .set nosym32 +ends a +.Li .set sym32 +block and reverts to the normal behavior. It is also possible to change the +symbol size using the command-line options +.Op -msym32 +and +.Op -mno-sym32 . +.Pp +These options and directives are always accepted, but at present, they have +no effect for anything other than n64. +.Pp +.Ss Directives to override the ISA level +GNU +.Li as +supports an additional directive to change the mips Instruction Set Architecture +level on the fly: +.Li .set mips Va n . +.Va n +should be a number from 0 to 5, or 32, 32r2, 64 or 64r2. The values other +than 0 make the assembler accept instructions for the corresponding isa level, +from that point on in the assembly. +.Li .set mips Va n +affects not only which instructions are permitted, but also how certain macros +are expanded. +.Li .set mips0 +restores the isa level to its original level: either the level you selected +with command line options, or the default for your configuration. You can +use this feature to permit specific mips3 instructions while assembling in +32 bit mode. Use this directive with care! +.Pp +The +.Li .set arch= Va cpu +directive provides even finer control. It changes the effective CPU target +and allows the assembler to use instructions specific to a particular CPU. +All CPUs supported by the +.Li -march +command line option are also selectable by this directive. The original value +is restored by +.Li .set arch=default . +.Pp +The directive +.Li .set mips16 +puts the assembler into MIPS 16 mode, in which it will assemble instructions +for the MIPS 16 processor. Use +.Li .set nomips16 +to return to normal 32 bit mode. +.Pp +Traditional mips assemblers do not support this directive. +.Pp +.Ss Directives for extending MIPS 16 bit instructions +By default, MIPS 16 instructions are automatically extended to 32 bits when +necessary. The directive +.Li .set noautoextend +will turn this off. When +.Li .set noautoextend +is in effect, any 32 bit instruction must be explicitly extended with the +.Li .e +modifier (e.g., +.Li li.e $4,1000 ) . +The directive +.Li .set autoextend +may be used to once again automatically extend instructions when necessary. +.Pp +This directive is only meaningful when in MIPS 16 mode. Traditional mips assemblers +do not support this directive. +.Pp +.Ss Directive to mark data as an instruction +The +.Li .insn +directive tells +.Li as +that the following data is actually instructions. This makes a difference +in MIPS 16 mode: when loading the address of a label which precedes instructions, +.Li as +automatically adds 1 to the value, so that jumping to the loaded address will +do the right thing. +.Pp +.Ss Directives to save and restore options +The directives +.Li .set push +and +.Li .set pop +may be used to save and restore the current settings for all the options which +are controlled by +.Li .set . +The +.Li .set push +directive saves the current settings on a stack. The +.Li .set pop +directive pops the stack and restores the settings. +.Pp +These directives can be useful inside an macro which must change an option +such as the ISA level or instruction reordering but does not want to change +the state of the code which invoked the macro. +.Pp +Traditional mips assemblers do not support these directives. +.Pp +.Ss Directives to control generation of MIPS ASE instructions +The directive +.Li .set mips3d +makes the assembler accept instructions from the MIPS-3D Application Specific +Extension from that point on in the assembly. The +.Li .set nomips3d +directive prevents MIPS-3D instructions from being accepted. +.Pp +The directive +.Li .set smartmips +makes the assembler accept instructions from the SmartMIPS Application Specific +Extension to the MIPS32 isa from that point on in the assembly. The +.Li .set nosmartmips +directive prevents SmartMIPS instructions from being accepted. +.Pp +The directive +.Li .set mdmx +makes the assembler accept instructions from the MDMX Application Specific +Extension from that point on in the assembly. The +.Li .set nomdmx +directive prevents MDMX instructions from being accepted. +.Pp +The directive +.Li .set dsp +makes the assembler accept instructions from the DSP Release 1 Application +Specific Extension from that point on in the assembly. The +.Li .set nodsp +directive prevents DSP Release 1 instructions from being accepted. +.Pp +The directive +.Li .set dspr2 +makes the assembler accept instructions from the DSP Release 2 Application +Specific Extension from that point on in the assembly. This dirctive implies +.Li .set dsp . +The +.Li .set nodspr2 +directive prevents DSP Release 2 instructions from being accepted. +.Pp +The directive +.Li .set mt +makes the assembler accept instructions from the MT Application Specific Extension +from that point on in the assembly. The +.Li .set nomt +directive prevents MT instructions from being accepted. +.Pp +Traditional mips assemblers do not support these directives. +.Pp +.Sh PowerPC Dependent Features +.Ss Options +The PowerPC chip family includes several successive levels, using the same +core instruction set, but including a few additional instructions at each +level. There are exceptions to this however. For details on what instructions +each variant supports, please see the chip's architecture reference manual. +.Pp +The following table lists all available PowerPC options. +.Pp +.Bl -tag -width Ds +.It -mpwrx | -mpwr2 +Generate code for POWER/2 (RIOS2). +.Pp +.It -mpwr +Generate code for POWER (RIOS1) +.Pp +.It -m601 +Generate code for PowerPC 601. +.Pp +.It -mppc, -mppc32, -m603, -m604 +Generate code for PowerPC 603/604. +.Pp +.It -m403, -m405 +Generate code for PowerPC 403/405. +.Pp +.It -m440 +Generate code for PowerPC 440. BookE and some 405 instructions. +.Pp +.It -m7400, -m7410, -m7450, -m7455 +Generate code for PowerPC 7400/7410/7450/7455. +.Pp +.It -mppc64, -m620 +Generate code for PowerPC 620/625/630. +.Pp +.It -me500, -me500x2 +Generate code for Motorola e500 core complex. +.Pp +.It -mspe +Generate code for Motorola SPE instructions. +.Pp +.It -mppc64bridge +Generate code for PowerPC 64, including bridge insns. +.Pp +.It -mbooke64 +Generate code for 64-bit BookE. +.Pp +.It -mbooke, mbooke32 +Generate code for 32-bit BookE. +.Pp +.It -me300 +Generate code for PowerPC e300 family. +.Pp +.It -maltivec +Generate code for processors with AltiVec instructions. +.Pp +.It -mpower4 +Generate code for Power4 architecture. +.Pp +.It -mpower5 +Generate code for Power5 architecture. +.Pp +.It -mpower6 +Generate code for Power6 architecture. +.Pp +.It -mcell +Generate code for Cell Broadband Engine architecture. +.Pp +.It -mcom +Generate code Power/PowerPC common instructions. +.Pp +.It -many +Generate code for any architecture (PWR/PWRX/PPC). +.Pp +.It -mregnames +Allow symbolic names for registers. +.Pp +.It -mno-regnames +Do not allow symbolic names for registers. +.Pp +.It -mrelocatable +Support for GCC's -mrelocatable option. +.Pp +.It -mrelocatable-lib +Support for GCC's -mrelocatable-lib option. +.Pp +.It -memb +Set PPC_EMB bit in ELF flags. +.Pp +.It -mlittle, -mlittle-endian +Generate code for a little endian machine. +.Pp +.It -mbig, -mbig-endian +Generate code for a big endian machine. +.Pp +.It -msolaris +Generate code for Solaris. +.Pp +.It -mno-solaris +Do not generate code for Solaris. +.El +.Pp +.Ss PowerPC Assembler Directives +A number of assembler directives are available for PowerPC. The following +table is far from complete. +.Pp +.Bl -tag -width Ds +.It .machine "string" +This directive allows you to change the machine for which code is generated. +.Li "string" +may be any of the -m cpu selection options (without the -m) enclosed in double +quotes, +.Li "push" , +or +.Li "pop" . +.Li .machine "push" +saves the currently selected cpu, which may be restored with +.Li .machine "pop" . +.El +.Pp +.Sh SPARC Dependent Features +.Ss Options +The SPARC chip family includes several successive levels, using the same core +instruction set, but including a few additional instructions at each level. +There are exceptions to this however. For details on what instructions each +variant supports, please see the chip's architecture reference manual. +.Pp +By default, +.Li as +assumes the core instruction set (SPARC v6), but \(lqbumps\(rq the architecture level +as needed: it switches to successively higher architectures as it encounters +instructions that only exist in the higher levels. +.Pp +If not configured for SPARC v9 ( +.Li sparc64-*-* ) +GAS will not bump passed sparclite by default, an option must be passed to +enable the v9 instructions. +.Pp +GAS treats sparclite as being compatible with v8, unless an architecture is +explicitly requested. SPARC v9 is always incompatible with sparclite. +.Pp +.Bl -tag -width Ds +.It -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite +.It -Av8plus | -Av8plusa | -Av9 | -Av9a +Use one of the +.Li -A +options to select one of the SPARC architectures explicitly. If you select +an architecture explicitly, +.Li as +reports a fatal error if it encounters an instruction or feature requiring +an incompatible or higher level. +.Pp +.Li -Av8plus +and +.Li -Av8plusa +select a 32 bit environment. +.Pp +.Li -Av9 +and +.Li -Av9a +select a 64 bit environment and are not available unless GAS is explicitly +configured with 64 bit environment support. +.Pp +.Li -Av8plusa +and +.Li -Av9a +enable the SPARC V9 instruction set with UltraSPARC extensions. +.Pp +.It -xarch=v8plus | -xarch=v8plusa +For compatibility with the Solaris v9 assembler. These options are equivalent +to -Av8plus and -Av8plusa, respectively. +.Pp +.It -bump +Warn whenever it is necessary to switch to another level. If an architecture +level is explicitly requested, GAS will not issue warnings until that level +is reached, and will then bump the level as required (except between incompatible +levels). +.Pp +.It -32 | -64 +Select the word size, either 32 bits or 64 bits. These options are only available +with the ELF object file format, and require that the necessary BFD support +has been included. +.El +.Pp +.Ss Enforcing aligned data +SPARC GAS normally permits data to be misaligned. For example, it permits +the +.Li .long +pseudo-op to be used on a byte boundary. However, the native SunOS and Solaris +assemblers issue an error when they see misaligned data. +.Pp +You can use the +.Li --enforce-aligned-data +option to make SPARC GAS also issue an error about misaligned data, just as +the SunOS and Solaris assemblers do. +.Pp +The +.Li --enforce-aligned-data +option is not the default because gcc issues misaligned data pseudo-ops when +it initializes certain packed data structures (structures defined using the +.Li packed +attribute). You may have to assemble with GAS in order to initialize packed +data structures in your own code. +.Pp +.Ss Floating Point +The Sparc uses ieee floating-point numbers. +.Pp +.Ss Sparc Machine Directives +The Sparc version of +.Li as +supports the following additional machine directives: +.Pp +.Bl -tag -width Ds +.It .align +This must be followed by the desired alignment in bytes. +.Pp +.It .common +This must be followed by a symbol name, a positive number, and +.Li "bss" . +This behaves somewhat like +.Li .comm , +but the syntax is different. +.Pp +.It .half +This is functionally identical to +.Li .short . +.Pp +.It .nword +On the Sparc, the +.Li .nword +directive produces native word sized value, ie. if assembling with -32 it +is equivalent to +.Li .word , +if assembling with -64 it is equivalent to +.Li .xword . +.Pp +.It .proc +This directive is ignored. Any text following it on the same line is also +ignored. +.Pp +.It .register +This directive declares use of a global application or system register. It +must be followed by a register name %g2, %g3, %g6 or %g7, comma and the symbol +name for that register. If symbol name is +.Li #scratch , +it is a scratch register, if it is +.Li #ignore , +it just suppresses any errors about using undeclared global register, but +does not emit any information about it into the object file. This can be useful +e.g. if you save the register before use and restore it after. +.Pp +.It .reserve +This must be followed by a symbol name, a positive number, and +.Li "bss" . +This behaves somewhat like +.Li .lcomm , +but the syntax is different. +.Pp +.It .seg +This must be followed by +.Li "text" , +.Li "data" , +or +.Li "data1" . +It behaves like +.Li .text , +.Li .data , +or +.Li .data 1 . +.Pp +.It .skip +This is functionally identical to the +.Li .space +directive. +.Pp +.It .word +On the Sparc, the +.Li .word +directive produces 32 bit values, instead of the 16 bit values it produces +on many other machines. +.Pp +.It .xword +On the Sparc V9 processor, the +.Li .xword +directive produces 64 bit values. +.El +.Pp +.Sh Reporting Bugs +Your bug reports play an essential role in making +.Xr as +reliable. +.Pp +Reporting a bug may help you by bringing a solution to your problem, or it +may not. But in any case the principal function of a bug report is to help +the entire community by making the next version of +.Xr as +work better. Bug reports are your contribution to the maintenance of +.Xr as . +.Pp +In order for a bug report to serve its purpose, you must include the information +that enables us to fix the bug. +.Pp +.Ss Have You Found a Bug? +If you are not sure whether you have found a bug, here are some guidelines: +.Pp +.Bl -bullet +.It +If the assembler gets a fatal signal, for any input whatever, that is a +.Xr as +bug. Reliable assemblers never crash. +.Pp +.It +If +.Xr as +produces an error message for valid input, that is a bug. +.Pp +.It +If +.Xr as +does not produce an error message for invalid input, that is a bug. However, +you should note that your idea of \(lqinvalid input\(rq might be our idea of \(lqan extension\(rq +or \(lqsupport for traditional practice\(rq. +.Pp +.It +If you are an experienced user of assemblers, your suggestions for improvement +of +.Xr as +are welcome in any case. +.El +.Pp +.Ss How to Report Bugs +A number of companies and individuals offer support for GNU products. If you +obtained +.Xr as +from a support organization, we recommend you contact that organization first. +.Pp +You can find contact information for many support companies and individuals +in the file +.Pa etc/SERVICE +in the GNU Emacs distribution. +.Pp +The fundamental principle of reporting bugs usefully is this: +.Sy report all the facts . +If you are not sure whether to state a fact or leave it out, state it! +.Pp +Often people omit facts because they think they know what causes the problem +and assume that some details do not matter. Thus, you might assume that the +name of a symbol you use in an example does not matter. Well, probably it +does not, but one cannot be sure. Perhaps the bug is a stray memory reference +which happens to fetch from the location where that name is stored in memory; +perhaps, if the name were different, the contents of that location would fool +the assembler into doing the right thing despite the bug. Play it safe and +give a specific, complete example. That is the easiest thing for you to do, +and the most helpful. +.Pp +Keep in mind that the purpose of a bug report is to enable us to fix the bug +if it is new to us. Therefore, always write your bug reports on the assumption +that the bug has not been reported previously. +.Pp +Sometimes people give a few sketchy facts and ask, \(lqDoes this ring a bell?\(rq +This cannot help us fix a bug, so it is basically useless. We respond by asking +for enough details to enable us to investigate. You might as well expedite +matters by sending them to begin with. +.Pp +To enable us to fix the bug, you should include all these things: +.Pp +.Bl -bullet +.It +The version of +.Xr as . +.Xr as +announces it if you start it with the +.Li --version +argument. +.Pp +Without this, we will not know whether there is any point in looking for the +bug in the current version of +.Xr as . +.Pp +.It +Any patches you may have applied to the +.Xr as +source. +.Pp +.It +The type of machine you are using, and the operating system name and version +number. +.Pp +.It +What compiler (and its version) was used to compile +.Xr as +---e.g. \(lq +.Li gcc-2.7 +\(rq\&. +.Pp +.It +The command arguments you gave the assembler to assemble your example and +observe the bug. To guarantee you will not omit something important, list +them all. A copy of the Makefile (or the output from make) is sufficient. +.Pp +If we were to try to guess the arguments, we would probably guess wrong and +then we might not encounter the bug. +.Pp +.It +A complete input file that will reproduce the bug. If the bug is observed +when the assembler is invoked via a compiler, send the assembler source, not +the high level language source. Most compilers will produce the assembler +source when run with the +.Li -S +option. If you are using +.Li gcc , +use the options +.Li -v --save-temps ; +this will save the assembler source in a file with an extension of +.Pa .s , +and also show you exactly how +.Xr as +is being run. +.Pp +.It +A description of what behavior you observe that you believe is incorrect. +For example, \(lqIt gets a fatal signal.\(rq +.Pp +Of course, if the bug is that +.Xr as +gets a fatal signal, then we will certainly notice it. But if the bug is incorrect +output, we might not notice unless it is glaringly wrong. You might as well +not give us a chance to make a mistake. +.Pp +Even if the problem you experience is a fatal signal, you should still say +so explicitly. Suppose something strange is going on, such as, your copy of +.Xr as +is out of sync, or you have encountered a bug in the C library on your system. +(This has happened!) Your copy might crash and ours would not. If you told +us to expect a crash, then when ours fails to crash, we would know that the +bug was not happening for us. If you had not told us to expect a crash, then +we would not be able to draw any conclusion from our observations. +.Pp +.It +If you wish to suggest changes to the +.Xr as +source, send us context diffs, as generated by +.Li diff +with the +.Li -u , +.Li -c , +or +.Li -p +option. Always send diffs from the old file to the new file. If you even discuss +something in the +.Xr as +source, refer to it by context, not by line number. +.Pp +The line numbers in our development sources will not match those in your sources. +Your line numbers would convey no useful information to us. +.El +.Pp +Here are some things that are not necessary: +.Pp +.Bl -bullet +.It +A description of the envelope of the bug. +.Pp +Often people who encounter a bug spend a lot of time investigating which changes +to the input file will make the bug go away and which changes will not affect +it. +.Pp +This is often time consuming and not very useful, because the way we will +find the bug is by running a single example under the debugger with breakpoints, +not by pure deduction from a series of examples. We recommend that you save +your time for something else. +.Pp +Of course, if you can find a simpler example to report +.Em instead +of the original one, that is a convenience for us. Errors in the output will +be easier to spot, running under the debugger will take less time, and so +on. +.Pp +However, simplification is not vital; if you do not want to do this, report +the bug anyway and send us the entire test case you used. +.Pp +.It +A patch for the bug. +.Pp +A patch for the bug does help us if it is a good one. But do not omit the +necessary information, such as the test case, on the assumption that a patch +is all we need. We might see problems with your patch and decide to fix the +problem another way, or we might not understand it at all. +.Pp +Sometimes with a program as complicated as +.Xr as +it is very hard to construct an example that will make the program follow +a certain path through the code. If you do not send us the example, we will +not be able to construct one, so we will not be able to verify that the bug +is fixed. +.Pp +And if we cannot understand what bug you are trying to fix, or why your patch +should be an improvement, we will not install it. A test case will help us +to understand. +.Pp +.It +A guess about what the bug is or what it depends on. +.Pp +Such guesses are usually wrong. Even we cannot guess right about such things +without first using the debugger to find the facts. +.El +.Pp +.Sh Acknowledgements +If you have contributed to GAS and your name isn't listed here, it is not +meant as a slight. We just don't know about it. Send mail to the maintainer, +and we'll correct the situation. Currently the maintainer is Ken Raeburn (email +address +.Li raeburn@cyGNUs.com ) . +.Pp +Dean Elsner wrote the original GNU assembler for the VAX. +.Pp +Jay Fenlason maintained GAS for a while, adding support for GDB-specific debug +information and the 68k series machines, most of the preprocessing pass, and +extensive changes in +.Pa messages.c , +.Pa input-file.c , +.Pa write.c . +.Pp +K. Richard Pixley maintained GAS for a while, adding various enhancements +and many bug fixes, including merging support for several processors, breaking +GAS up to handle multiple object file format back ends (including heavy rewrite, +testing, an integration of the coff and b.out back ends), adding configuration +including heavy testing and verification of cross assemblers and file splits +and renaming, converted GAS to strictly ANSI C including full prototypes, +added support for m680[34]0 and cpu32, did considerable work on i960 including +a COFF port (including considerable amounts of reverse engineering), a SPARC +opcode file rewrite, DECstation, rs6000, and hp300hpux host ports, updated +\(lqknow\(rq assertions and made them work, much other reorganization, cleanup, and +lint. +.Pp +Ken Raeburn wrote the high-level BFD interface code to replace most of the +code in format-specific I/O modules. +.Pp +The original VMS support was contributed by David L. Kashtan. Eric Youngdale +has done much work with it since. +.Pp +The Intel 80386 machine description was written by Eliot Dresselhaus. +.Pp +Minh Tran-Le at IntelliCorp contributed some AIX 386 support. +.Pp +The Motorola 88k machine description was contributed by Devon Bowen of Buffalo +University and Torbjorn Granlund of the Swedish Institute of Computer Science. +.Pp +Keith Knowles at the Open Software Foundation wrote the original MIPS back +end ( +.Pa tc-mips.c , +.Pa tc-mips.h ) , +and contributed Rose format support (which hasn't been merged in yet). Ralph +Campbell worked with the MIPS code to support a.out format. +.Pp +Support for the Zilog Z8k and Renesas H8/300 processors (tc-z8k, tc-h8300), +and IEEE 695 object file format (obj-ieee), was written by Steve Chamberlain +of CyGNUs Support. Steve also modified the COFF back end to use BFD for some +low-level operations, for use with the H8/300 and AMD 29k targets. +.Pp +John Gilmore built the AMD 29000 support, added +.Li .include +support, and simplified the configuration of which versions accept which directives. +He updated the 68k machine description so that Motorola's opcodes always produced +fixed-size instructions (e.g., +.Li jsr ) , +while synthetic instructions remained shrinkable ( +.Li jbsr ) . +John fixed many bugs, including true tested cross-compilation support, and +one bug in relaxation that took a week and required the proverbial one-bit +fix. +.Pp +Ian Lance Taylor of CyGNUs Support merged the Motorola and MIT syntax for +the 68k, completed support for some COFF targets (68k, i386 SVR3, and SCO +Unix), added support for MIPS ECOFF and ELF targets, wrote the initial RS/6000 +and PowerPC assembler, and made a few other minor patches. +.Pp +Steve Chamberlain made GAS able to generate listings. +.Pp +Hewlett-Packard contributed support for the HP9000/300. +.Pp +Jeff Law wrote GAS and BFD support for the native HPPA object format (SOM) +along with a fairly extensive HPPA testsuite (for both SOM and ELF object +formats). This work was supported by both the Center for Software Science +at the University of Utah and CyGNUs Support. +.Pp +Support for ELF format files has been worked on by Mark Eichin of CyGNUs Support +(original, incomplete implementation for SPARC), Pete Hoogenboom and Jeff +Law at the University of Utah (HPPA mainly), Michael Meissner of the Open +Software Foundation (i386 mainly), and Ken Raeburn of CyGNUs Support (sparc, +and some initial 64-bit support). +.Pp +Linas Vepstas added GAS support for the ESA/390 \(lqIBM 370\(rq architecture. +.Pp +Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote GAS and +BFD support for openVMS/Alpha. +.Pp +Timothy Wall, Michael Hayes, and Greg Smart contributed to the various tic* +flavors. +.Pp +David Heine, Sterling Augustine, Bob Wilson and John Ruttenberg from Tensilica, +Inc. added support for Xtensa processors. +.Pp +Several engineers at CyGNUs Support have also provided many small bug fixes +and configuration enhancements. +.Pp +Many others have contributed large or small bugfixes and enhancements. If +you have contributed significant work and are not mentioned on this list, +and want to be, let us know. Some of the history has been lost; we are not +intentionally leaving anyone out. +.Pp +.Sh GNU Free Documentation License +.Bd -filled -offset indent +Copyright (C) 2000, 2003 Free Software Foundation, Inc. 51 Franklin Street, +Fifth Floor, Boston, MA 02110-1301 USA +.Pp +Everyone is permitted to copy and distribute verbatim copies of this license +document, but changing it is not allowed. +.Ed +.Pp +.Bl -enum +.It +PREAMBLE +.Pp +The purpose of this License is to make a manual, textbook, or other written +document \(lqfree\(rq in the sense of freedom: to assure everyone the effective freedom +to copy and redistribute it, with or without modifying it, either commercially +or noncommercially. Secondarily, this License preserves for the author and +publisher a way to get credit for their work, while not being considered responsible +for modifications made by others. +.Pp +This License is a kind of \(lqcopyleft\(rq, which means that derivative works of the +document must themselves be free in the same sense. It complements the GNU +General Public License, which is a copyleft license designed for free software. +.Pp +We have designed this License in order to use it for manuals for free software, +because free software needs free documentation: a free program should come +with manuals providing the same freedoms that the software does. But this +License is not limited to software manuals; it can be used for any textual +work, regardless of subject matter or whether it is published as a printed +book. We recommend this License principally for works whose purpose is instruction +or reference. +.Pp +.It +APPLICABILITY AND DEFINITIONS +.Pp +This License applies to any manual or other work that contains a notice placed +by the copyright holder saying it can be distributed under the terms of this +License. The \(lqDocument\(rq, below, refers to any such manual or work. Any member +of the public is a licensee, and is addressed as \(lqyou.\(rq +.Pp +A \(lqModified Version\(rq of the Document means any work containing the Document +or a portion of it, either copied verbatim, or with modifications and/or translated +into another language. +.Pp +A \(lqSecondary Section\(rq is a named appendix or a front-matter section of the Document +that deals exclusively with the relationship of the publishers or authors +of the Document to the Document's overall subject (or to related matters) +and contains nothing that could fall directly within that overall subject. +(For example, if the Document is in part a textbook of mathematics, a Secondary +Section may not explain any mathematics.) The relationship could be a matter +of historical connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding them. +.Pp +The \(lqInvariant Sections\(rq are certain Secondary Sections whose titles are designated, +as being those of Invariant Sections, in the notice that says that the Document +is released under this License. +.Pp +The \(lqCover Texts\(rq are certain short passages of text that are listed, as Front-Cover +Texts or Back-Cover Texts, in the notice that says that the Document is released +under this License. +.Pp +A \(lqTransparent\(rq copy of the Document means a machine-readable copy, represented +in a format whose specification is available to the general public, whose +contents can be viewed and edited directly and straightforwardly with generic +text editors or (for images composed of pixels) generic paint programs or +(for drawings) some widely available drawing editor, and that is suitable +for input to text formatters or for automatic translation to a variety of +formats suitable for input to text formatters. A copy made in an otherwise +Transparent file format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is not +\(lqTransparent\(rq is called \(lqOpaque.\(rq +.Pp +Examples of suitable formats for Transparent copies include plain ASCII without +markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly +available DTD, and standard-conforming simple HTML designed for human modification. +Opaque formats include PostScript, PDF, proprietary formats that can be read +and edited only by proprietary word processors, SGML or XML for which the +DTD and/or processing tools are not generally available, and the machine-generated +HTML produced by some word processors for output purposes only. +.Pp +The \(lqTitle Page\(rq means, for a printed book, the title page itself, plus such +following pages as are needed to hold, legibly, the material this License +requires to appear in the title page. For works in formats which do not have +any title page as such, \(lqTitle Page\(rq means the text near the most prominent +appearance of the work's title, preceding the beginning of the body of the +text. +.Pp +.It +VERBATIM COPYING +.Pp +You may copy and distribute the Document in any medium, either commercially +or noncommercially, provided that this License, the copyright notices, and +the license notice saying this License applies to the Document are reproduced +in all copies, and that you add no other conditions whatsoever to those of +this License. You may not use technical measures to obstruct or control the +reading or further copying of the copies you make or distribute. However, +you may accept compensation in exchange for copies. If you distribute a large +enough number of copies you must also follow the conditions in section 3. +.Pp +You may also lend copies, under the same conditions stated above, and you +may publicly display copies. +.Pp +.It +COPYING IN QUANTITY +.Pp +If you publish printed copies of the Document numbering more than 100, and +the Document's license notice requires Cover Texts, you must enclose the copies +in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover +Texts on the front cover, and Back-Cover Texts on the back cover. Both covers +must also clearly and legibly identify you as the publisher of these copies. +The front cover must present the full title with all words of the title equally +prominent and visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve the title +of the Document and satisfy these conditions, can be treated as verbatim copying +in other respects. +.Pp +If the required texts for either cover are too voluminous to fit legibly, +you should put the first ones listed (as many as fit reasonably) on the actual +cover, and continue the rest onto adjacent pages. +.Pp +If you publish or distribute Opaque copies of the Document numbering more +than 100, you must either include a machine-readable Transparent copy along +with each Opaque copy, or state in or with each Opaque copy a publicly-accessible +computer-network location containing a complete Transparent copy of the Document, +free of added material, which the general network-using public has access +to download anonymously at no charge using public-standard network protocols. +If you use the latter option, you must take reasonably prudent steps, when +you begin distribution of Opaque copies in quantity, to ensure that this Transparent +copy will remain thus accessible at the stated location until at least one +year after the last time you distribute an Opaque copy (directly or through +your agents or retailers) of that edition to the public. +.Pp +It is requested, but not required, that you contact the authors of the Document +well before redistributing any large number of copies, to give them a chance +to provide you with an updated version of the Document. +.Pp +.It +MODIFICATIONS +.Pp +You may copy and distribute a Modified Version of the Document under the conditions +of sections 2 and 3 above, provided that you release the Modified Version +under precisely this License, with the Modified Version filling the role of +the Document, thus licensing distribution and modification of the Modified +Version to whoever possesses a copy of it. In addition, you must do these +things in the Modified Version: +.Pp +A. Use in the Title Page (and on the covers, if any) a title distinct from +that of the Document, and from those of previous versions (which should, if +there were any, be listed in the History section of the Document). You may +use the same title as a previous version if the original publisher of that +version gives permission. B. List on the Title Page, as authors, one or more +persons or entities responsible for authorship of the modifications in the +Modified Version, together with at least five of the principal authors of +the Document (all of its principal authors, if it has less than five). C. +State on the Title page the name of the publisher of the Modified Version, +as the publisher. D. Preserve all the copyright notices of the Document. +E. Add an appropriate copyright notice for your modifications adjacent to +the other copyright notices. F. Include, immediately after the copyright +notices, a license notice giving the public permission to use the Modified +Version under the terms of this License, in the form shown in the Addendum +below. G. Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. H. Include +an unaltered copy of this License. I. Preserve the section entitled \(lqHistory\(rq, +and its title, and add to it an item stating at least the title, year, new +authors, and publisher of the Modified Version as given on the Title Page. +If there is no section entitled \(lqHistory\(rq in the Document, create one stating +the title, year, authors, and publisher of the Document as given on its Title +Page, then add an item describing the Modified Version as stated in the previous +sentence. J. Preserve the network location, if any, given in the Document +for public access to a Transparent copy of the Document, and likewise the +network locations given in the Document for previous versions it was based +on. These may be placed in the \(lqHistory\(rq section. You may omit a network location +for a work that was published at least four years before the Document itself, +or if the original publisher of the version it refers to gives permission. +K. In any section entitled \(lqAcknowledgements\(rq or \(lqDedications\(rq, preserve the section's +title, and preserve in the section all the substance and tone of each of the +contributor acknowledgements and/or dedications given therein. L. Preserve +all the Invariant Sections of the Document, unaltered in their text and in +their titles. Section numbers or the equivalent are not considered part of +the section titles. M. Delete any section entitled \(lqEndorsements.\(rq Such a section +may not be included in the Modified Version. N. Do not retitle any existing +section as \(lqEndorsements\(rq or to conflict in title with any Invariant Section. +.Pp +If the Modified Version includes new front-matter sections or appendices that +qualify as Secondary Sections and contain no material copied from the Document, +you may at your option designate some or all of these sections as invariant. +To do this, add their titles to the list of Invariant Sections in the Modified +Version's license notice. These titles must be distinct from any other section +titles. +.Pp +You may add a section entitled \(lqEndorsements\(rq, provided it contains nothing +but endorsements of your Modified Version by various parties--for example, +statements of peer review or that the text has been approved by an organization +as the authoritative definition of a standard. +.Pp +You may add a passage of up to five words as a Front-Cover Text, and a passage +of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts +in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover +Text may be added by (or through arrangements made by) any one entity. If +the Document already includes a cover text for the same cover, previously +added by you or by arrangement made by the same entity you are acting on behalf +of, you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. +.Pp +The author(s) and publisher(s) of the Document do not by this License give +permission to use their names for publicity for or to assert or imply endorsement +of any Modified Version. +.Pp +.It +COMBINING DOCUMENTS +.Pp +You may combine the Document with other documents released under this License, +under the terms defined in section 4 above for modified versions, provided +that you include in the combination all of the Invariant Sections of all of +the original documents, unmodified, and list them all as Invariant Sections +of your combined work in its license notice. +.Pp +The combined work need only contain one copy of this License, and multiple +identical Invariant Sections may be replaced with a single copy. If there +are multiple Invariant Sections with the same name but different contents, +make the title of each such section unique by adding at the end of it, in +parentheses, the name of the original author or publisher of that section +if known, or else a unique number. Make the same adjustment to the section +titles in the list of Invariant Sections in the license notice of the combined +work. +.Pp +In the combination, you must combine any sections entitled \(lqHistory\(rq in the +various original documents, forming one section entitled \(lqHistory\(rq; likewise +combine any sections entitled \(lqAcknowledgements\(rq, and any sections entitled +\(lqDedications.\(rq You must delete all sections entitled \(lqEndorsements.\(rq +.Pp +.It +COLLECTIONS OF DOCUMENTS +.Pp +You may make a collection consisting of the Document and other documents released +under this License, and replace the individual copies of this License in the +various documents with a single copy that is included in the collection, provided +that you follow the rules of this License for verbatim copying of each of +the documents in all other respects. +.Pp +You may extract a single document from such a collection, and distribute it +individually under this License, provided you insert a copy of this License +into the extracted document, and follow this License in all other respects +regarding verbatim copying of that document. +.Pp +.It +AGGREGATION WITH INDEPENDENT WORKS +.Pp +A compilation of the Document or its derivatives with other separate and independent +documents or works, in or on a volume of a storage or distribution medium, +does not as a whole count as a Modified Version of the Document, provided +no compilation copyright is claimed for the compilation. Such a compilation +is called an \(lqaggregate\(rq, and this License does not apply to the other self-contained +works thus compiled with the Document, on account of their being thus compiled, +if they are not themselves derivative works of the Document. +.Pp +If the Cover Text requirement of section 3 is applicable to these copies of +the Document, then if the Document is less than one quarter of the entire +aggregate, the Document's Cover Texts may be placed on covers that surround +only the Document within the aggregate. Otherwise they must appear on covers +around the whole aggregate. +.Pp +.It +TRANSLATION +.Pp +Translation is considered a kind of modification, so you may distribute translations +of the Document under the terms of section 4. Replacing Invariant Sections +with translations requires special permission from their copyright holders, +but you may include translations of some or all Invariant Sections in addition +to the original versions of these Invariant Sections. You may include a translation +of this License provided that you also include the original English version +of this License. In case of a disagreement between the translation and the +original English version of this License, the original English version will +prevail. +.Pp +.It +TERMINATION +.Pp +You may not copy, modify, sublicense, or distribute the Document except as +expressly provided for under this License. Any other attempt to copy, modify, +sublicense or distribute the Document is void, and will automatically terminate +your rights under this License. However, parties who have received copies, +or rights, from you under this License will not have their licenses terminated +so long as such parties remain in full compliance. +.Pp +.It +FUTURE REVISIONS OF THIS LICENSE +.Pp +The Free Software Foundation may publish new, revised versions of the GNU +Free Documentation License from time to time. Such new versions will be similar +in spirit to the present version, but may differ in detail to address new +problems or concerns. See http://www.gnu.org/copyleft/. +.Pp +Each version of the License is given a distinguishing version number. If the +Document specifies that a particular numbered version of this License \(lqor any +later version\(rq applies to it, you have the option of following the terms and +conditions either of that specified version or of any later version that has +been published (not as a draft) by the Free Software Foundation. If the Document +does not specify a version number of this License, you may choose any version +ever published (not as a draft) by the Free Software Foundation. +.Pp +.El +.Ss ADDENDUM: How to use this License for your documents +To use this License in a document you have written, include a copy of the +License in the document and put the following copyright and license notices +just after the title page: +.Pp +.Bd -literal -offset indent + +Copyright (C) year your name. +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 +or any later version published by the Free Software Foundation; +with the Invariant Sections being list their titles, with the +Front-Cover Texts being list, and with the Back-Cover Texts being list. +A copy of the license is included in the section entitled "GNU +Free Documentation License." + +.Ed +.Pp +If you have no Invariant Sections, write \(lqwith no Invariant Sections\(rq instead +of saying which ones are invariant. If you have no Front-Cover Texts, write +\(lqno Front-Cover Texts\(rq instead of \(lqFront-Cover Texts being +.Va list +\(rq; likewise for Back-Cover Texts. +.Pp +If your document contains nontrivial examples of program code, we recommend +releasing these examples in parallel under your choice of free software license, +such as the GNU General Public License, to permit their use in free software. +.Pp +.Sh AS Index diff --git a/contrib/binutils/ld/ld.7 b/contrib/binutils/ld/ld.7 new file mode 100644 index 0000000..8ac5573 --- /dev/null +++ b/contrib/binutils/ld/ld.7 @@ -0,0 +1,7819 @@ +.Dd 2015-03-02 +.Dt LD 7 +.Os +.Sh NAME +.Nm ld +.Nd The GNU Linker +.Sh LD +This file documents the GNU linker ld version "2.17.50 [FreeBSD] 2007-07-03". +.Pp +This document is distributed under the terms of the GNU Free Documentation +License. A copy of the license is included in the section entitled \(lqGNU Free +Documentation License\(rq. +.Pp +.Sh Overview +.Xr ld +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 +.Xr ld . +.Pp +.Xr ld +accepts Linker Command Language files written in a superset of AT&T's Link +Editor Command Language syntax, to provide explicit and total control over +the linking process. +.Pp +This version of +.Xr ld +uses the general purpose BFD libraries to operate on object files. This allows +.Xr ld +to read, combine, and write object files in many different formats---for example, +COFF or +.Li a.out . +Different formats may be linked together to produce any available kind of +object file.See Section +.Dq BFD , +for more information. +.Pp +Aside from its flexibility, the GNU linker is more helpful than other linkers +in providing diagnostic information. Many linkers abandon execution immediately +upon encountering an error; whenever possible, +.Xr ld +continues executing, allowing you to identify other errors (or, in some cases, +to get an output file in spite of the error). +.Pp +.Sh Invocation +The GNU linker +.Xr ld +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. +.Pp +.Ss Command Line 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 +.Xr ld +is to link standard Unix object files on a standard, supported Unix system. +On such a system, to link a file +.Li hello.o : +.Pp +.Bd -literal -offset indent +ld -o output /lib/crt0.o hello.o -lc +.Ed +.Pp +This tells +.Xr ld +to produce a file called +.Va output +as the result of linking the file +.Li /lib/crt0.o +with +.Li hello.o +and the library +.Li libc.a , +which will come from the standard search directories. (See the discussion +of the +.Li -l +option below.) +.Pp +Some of the command-line options to +.Xr ld +may be specified at any point in the command line. However, options which +refer to files, such as +.Li -l +or +.Li -T , +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 +.Li -l , +.Li -R , +and the script command language. If +.Em no +binary input files at all are specified, the linker does not produce any output, +and issues the message +.Li No input files . +.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 +.Li -T ) . +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 +.Li INPUT +or +.Li GROUP +to load other objects. Note that specifying a script in this way merely augments +the main linker script; use the +.Li -T +option to replace the default linker script entirely.See Section +.Dq Scripts . +.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, +.Li -trace-symbol +and +.Li --trace-symbol +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 +.Li -o +option. So for example +.Li -omagic +sets the output file name to +.Li magic +whereas +.Li --omagic +sets the NMAGIC 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, +.Li --trace-symbol foo +and +.Li --trace-symbol=foo +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. +.Li gcc ) +then all the linker command line options should be prefixed by +.Li -Wl, +(or whatever is appropriate for the particular compiler driver) like this: +.Pp +.Bd -literal -offset indent + gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup +.Ed +.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 GNU linker: +.Pp +.Bl -tag -width Ds +.It @ Va file +Read command-line options from +.Va file . +The options read are inserted in place of the original @ +.Va file +option. If +.Va file +does not exist, or cannot be read, then the option will be treated literally, +and not removed. +.Pp +Options in +.Va file +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 +.Va file +may itself contain additional @ +.Va file +options; any such options will be processed recursively. +.Pp +.It -a Va keyword +This option is supported for HP/UX compatibility. The +.Va keyword +argument must be one of the strings +.Li archive , +.Li shared , +or +.Li default . +.Li -aarchive +is functionally equivalent to +.Li -Bstatic , +and the other two keywords are functionally equivalent to +.Li -Bdynamic . +This option may be used any number of times. +.Pp +.It -A Va architecture +.It --architecture= Va architecture +In the current release of +.Xr ld , +this option is useful only for the Intel 960 family of architectures. In that +.Xr ld +configuration, the +.Va architecture +argument identifies the particular architecture in the 960 family, enabling +some safeguards and modifying the archive-library search path.See Section +.Dq i960 , +for details. +.Pp +Future releases of +.Xr ld +may support similar functionality for other architecture families. +.Pp +.It -b Va input-format +.It --format= Va input-format +.Xr ld +may be configured to support more than one kind of object file. If your +.Xr ld +is configured this way, you can use the +.Li -b +option to specify the binary format for input object files that follow this +option on the command line. Even when +.Xr ld +is configured to support alternative object formats, you don't usually need +to specify this, as +.Xr ld +should be configured to expect as a default input format the most usual format +on each machine. +.Va input-format +is a text string, the name of a particular format supported by the BFD libraries. +(You can list the available binary formats with +.Li objdump -i . ) +See Section.Dq BFD . +.Pp +You may want to use this option if you are linking files with an unusual binary +format. You can also use +.Li -b +to switch formats explicitly (when linking object files of different formats), +by including +.Li -b Va input-format +before each group of object files in a particular format. +.Pp +The default format is taken from the environment variable +.Li GNUTARGET . +See Section.Dq Environment . +You can also define the input format from a script, using the command +.Li TARGET ; +see Format Commands. +.Pp +.It -c Va MRI-commandfile +.It --mri-script= Va MRI-commandfile +For compatibility with linkers produced by MRI, +.Xr ld +accepts script files written in an alternate, restricted command language, +described in MRI,,MRI Compatible Script Files. Introduce MRI script files +with the option +.Li -c ; +use the +.Li -T +option to run linker scripts written in the general-purpose +.Xr ld +scripting language. If +.Va MRI-cmdfile +does not exist, +.Xr ld +looks for it in the directories specified by any +.Li -L +options. +.Pp +.It -d +.It -dc +.It -dp +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 +.Li -r ) . +The script command +.Li FORCE_COMMON_ALLOCATION +has the same effect.See Section +.Dq Miscellaneous Commands . +.Pp +.It -e Va entry +.It --entry= Va entry +Use +.Va entry +as the explicit symbol for beginning execution of your program, rather than +the default entry point. If there is no symbol named +.Va entry , +the linker will try to parse +.Va entry +as a number, and use that as the entry address (the number will be interpreted +in base 10; you may use a leading +.Li 0x +for base 16, or a leading +.Li 0 +for base 8).See Section +.Dq Entry Point , +for a discussion of defaults and other ways of specifying the entry point. +.Pp +.It --exclude-libs Va lib, Va 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 +.Li --exclude-libs ALL +excludes symbols in all archive libraries from automatic export. This option +is available only for the i386 PE targeted port of the linker and for ELF +targeted ports. For i386 PE, symbols explicitly listed in a .def file are +still exported, regardless of this option. For ELF targeted ports, symbols +affected by this option will be treated as hidden. +.Pp +.It -E +.It --export-dynamic +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. +.Pp +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. +.Pp +If you use +.Li dlopen +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. +.Pp +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 +.Li --dynamic-list . +.Pp +.It -EB +Link big-endian objects. This affects the default output format. +.Pp +.It -EL +Link little-endian objects. This affects the default output format. +.Pp +.It -f +.It --auxiliary Va name +When creating an ELF shared object, set the internal DT_AUXILIARY 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 +.Va name . +.Pp +If you later link a program against this filter object, then, when you run +the program, the dynamic linker will see the DT_AUXILIARY 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 +.Va name . +If there is one, it will be used instead of the definition in the filter object. +The shared object +.Va name +need not exist. Thus the shared object +.Va name +may be used to provide an alternative implementation of certain functions, +perhaps for debugging or for machine specific performance. +.Pp +This option may be specified more than once. The DT_AUXILIARY entries will +be created in the order in which they appear on the command line. +.Pp +.It -F Va name +.It --filter Va name +When creating an ELF shared object, set the internal DT_FILTER 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 +.Va name . +.Pp +If you later link a program against this filter object, then, when you run +the program, the dynamic linker will see the DT_FILTER 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 +.Va name . +Thus the filter object can be used to select a subset of the symbols provided +by the object +.Va name . +.Pp +Some older linkers used the +.Op -F +option throughout a compilation toolchain for specifying object-file format +for both input and output object files. The GNU linker uses other mechanisms +for this purpose: the +.Op -b , +.Op --format , +.Op --oformat +options, the +.Li TARGET +command in linker scripts, and the +.Li GNUTARGET +environment variable. The GNU linker will ignore the +.Op -F +option when not creating an ELF shared object. +.Pp +.It -fini Va name +When creating an ELF executable or shared object, call NAME when the executable +or shared object is unloaded, by setting DT_FINI to the address of the function. +By default, the linker uses +.Li _fini +as the function to call. +.Pp +.It -g +Ignored. Provided for compatibility with other tools. +.Pp +.It -G Va value +.It --gpsize= Va value +Set the maximum size of objects to be optimized using the GP register to +.Va size . +This is only meaningful for object file formats such as MIPS ECOFF which supports +putting large and small objects into different sections. This is ignored for +other object file formats. +.Pp +.It -h Va name +.It -soname= Va name +When creating an ELF shared object, set the internal DT_SONAME field to the +specified name. When an executable is linked with a shared object which has +a DT_SONAME field, then when the executable is run the dynamic linker will +attempt to load the shared object specified by the DT_SONAME field rather +than the using the file name given to the linker. +.Pp +.It -i +Perform an incremental link (same as option +.Li -r ) . +.Pp +.It -init Va name +When creating an ELF executable or shared object, call NAME when the executable +or shared object is loaded, by setting DT_INIT to the address of the function. +By default, the linker uses +.Li _init +as the function to call. +.Pp +.It -l Va namespec +.It --library= Va namespec +Add the archive or object file specified by +.Va namespec +to the list of files to link. This option may be used any number of times. +If +.Va namespec +is of the form +.Pa : Va filename , +.Xr ld +will search the library path for a file called +.Va filename , +otherise it will search the library path for a file called +.Pa lib Va namespec.a . +.Pp +On systems which support shared libraries, +.Xr ld +may also search for files other than +.Pa lib Va namespec.a . +Specifically, on ELF and SunOS systems, +.Xr ld +will search a directory for a library called +.Pa lib Va namespec.so +before searching for one called +.Pa lib Va namespec.a . +(By convention, a +.Li .so +extension indicates a shared library.) Note that this behavior does not apply +to +.Pa : Va filename , +which always specifies a file called +.Va filename . +.Pp +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. +.Pp +See the +.Op -( +option for a way to force the linker to search archives multiple times. +.Pp +You may list the same archive multiple times on the command line. +.Pp +This type of archive searching is standard for Unix linkers. However, if you +are using +.Xr ld +on AIX, note that it is different from the behaviour of the AIX linker. +.Pp +.It -L Va searchdir +.It --library-path= Va searchdir +Add path +.Va searchdir +to the list of paths that +.Xr ld +will search for archive libraries and +.Xr ld +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 +.Op -L +options apply to all +.Op -l +options, regardless of the order in which the options appear. +.Pp +If +.Va searchdir +begins with +.Li = , +then the +.Li = +will be replaced by the +.Em sysroot prefix , +a path specified when the linker is configured. +.Pp +The default set of paths searched (without being specified with +.Li -L ) +depends on which emulation mode +.Xr ld +is using, and in some cases also on how it was configured.See Section +.Dq Environment . +.Pp +The paths can also be specified in a link script with the +.Li SEARCH_DIR +command. Directories specified this way are searched at the point in which +the linker script appears in the command line. +.Pp +.It -m Va emulation +Emulate the +.Va emulation +linker. You can list the available emulations with the +.Li --verbose +or +.Li -V +options. +.Pp +If the +.Li -m +option is not used, the emulation is taken from the +.Li LDEMULATION +environment variable, if that is defined. +.Pp +Otherwise, the default emulation depends upon how the linker was configured. +.Pp +.It -M +.It --print-map +Print a link map to the standard output. A link map provides information about +the link, including the following: +.Pp +.Bl -bullet +.It +Where object files are mapped into memory. +.It +How common symbols are allocated. +.It +All archive members included in the link, with a mention of the symbol which +caused the archive member to be brought in. +.It +The values assigned to symbols. +.Pp +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: +.Pp +.Bd -literal -offset indent + foo = 1 + foo = foo * 4 + foo = foo + 8 +.Ed +.Pp +will produce the following output in the link map if the +.Op -M +option is used: +.Pp +.Bd -literal -offset indent + 0x00000001 foo = 0x1 + [0x0000000c] foo = (foo * 0x4) + [0x0000000c] foo = (foo + 0x8) +.Ed +.Pp +See Expressions for more information about expressions in linker scripts. +.El +.Pp +.It -n +.It --nmagic +Turn off page alignment of sections, and mark the output as +.Li NMAGIC +if possible. +.Pp +.It -N +.It --omagic +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 +.Li OMAGIC . +Note: Although a writable text section is allowed for PE-COFF targets, it +does not conform to the format specification published by Microsoft. +.Pp +.It --no-omagic +This option negates most of the effects of the +.Op -N +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 +.Op -Bdynamic +for this. +.Pp +.It -o Va output +.It --output= Va output +Use +.Va output +as the name for the program produced by +.Xr ld ; +if this option is not specified, the name +.Pa a.out +is used by default. The script command +.Li OUTPUT +can also specify the output file name. +.Pp +.It -O Va level +If +.Va level +is a numeric values greater than zero +.Xr ld +optimizes the output. This might take significantly longer and therefore probably +should only be enabled for the final binary. +.Pp +.It -q +.It --emit-relocs +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. +.Pp +This option is currently only supported on ELF platforms. +.Pp +.It --force-dynamic +Force the output file to have dynamic sections. This option is specific to +VxWorks targets. +.Pp +.It -r +.It --relocatable +Generate relocatable output---i.e., generate an output file that can in turn +serve as input to +.Xr ld . +This is often called +.Em partial linking . +As a side effect, in environments that support standard Unix magic numbers, +this option also sets the output file's magic number to +.Li OMAGIC . +If this option is not specified, an absolute file is produced. When linking +C++ programs, this option +.Em will not +resolve references to constructors; to do that, use +.Li -Ur . +.Pp +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 +.Li a.out +-based formats do not support partial linking with input files in other formats +at all. +.Pp +This option does the same thing as +.Li -i . +.Pp +.It -R Va filename +.It --just-symbols= Va filename +Read symbol names and their addresses from +.Va filename , +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. +.Pp +For compatibility with other ELF linkers, if the +.Op -R +option is followed by a directory name, rather than a file name, it is treated +as the +.Op -rpath +option. +.Pp +.It -s +.It --strip-all +Omit all symbol information from the output file. +.Pp +.It -S +.It --strip-debug +Omit debugger symbol information (but not all symbols) from the output file. +.Pp +.It -t +.It --trace +Print the names of the input files as +.Xr ld +processes them. +.Pp +.It -T Va scriptfile +.It --script= Va scriptfile +Use +.Va scriptfile +as the linker script. This script replaces +.Xr ld +\&'s default linker script (rather than adding to it), so +.Va commandfile +must specify everything necessary to describe the output file.See Section +.Dq Scripts . +If +.Va scriptfile +does not exist in the current directory, +.Li ld +looks for it in the directories specified by any preceding +.Li -L +options. Multiple +.Li -T +options accumulate. +.Pp +.It -dT Va scriptfile +.It --default-script= Va scriptfile +Use +.Va scriptfile +as the default linker script.See Section +.Dq Scripts . +.Pp +This option is similar to the +.Op --script +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 +.Op --default-script +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 +.Li gcc ) . +.Pp +.It -u Va symbol +.It --undefined= Va symbol +Force +.Va symbol +to be entered in the output file as an undefined symbol. Doing this may, for +example, trigger linking of additional modules from standard libraries. +.Li -u +may be repeated with different option arguments to enter additional undefined +symbols. This option is equivalent to the +.Li EXTERN +linker script command. +.Pp +.It -Ur +For anything other than C++ programs, this option is equivalent to +.Li -r : +it generates relocatable output---i.e., an output file that can in turn serve +as input to +.Xr ld . +When linking C++ programs, +.Li -Ur +.Em does +resolve references to constructors, unlike +.Li -r . +It does not work to use +.Li -Ur +on files that were themselves linked with +.Li -Ur ; +once the constructor table has been built, it cannot be added to. Use +.Li -Ur +only for the last partial link, and +.Li -r +for the others. +.Pp +.It --unique[= Va SECTION] +Creates a separate output section for every input section matching +.Va SECTION , +or if the optional wildcard +.Va SECTION +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. +.Pp +.It -v +.It --version +.It -V +Display the version number for +.Xr ld . +The +.Op -V +option also lists the supported emulations. +.Pp +.It -x +.It --discard-all +Delete all local symbols. +.Pp +.It -X +.It --discard-locals +Delete all temporary local symbols. (These symbols start with system-specific +local label prefixes, typically +.Li .L +for ELF systems or +.Li L +for traditional a.out systems.) +.Pp +.It -y Va symbol +.It --trace-symbol= Va symbol +Print the name of each linked file in which +.Va symbol +appears. This option may be given any number of times. On many systems it +is necessary to prepend an underscore. +.Pp +This option is useful when you have an undefined symbol in your link but don't +know where the reference is coming from. +.Pp +.It -Y Va path +Add +.Va path +to the default library search path. This option exists for Solaris compatibility. +.Pp +.It -z Va keyword +The recognized keywords are: +.Bl -tag -width Ds +.It combreloc +Combines multiple reloc sections and sorts them to make dynamic symbol lookup +caching possible. +.Pp +.It defs +Disallows undefined symbols in object files. Undefined symbols in shared libraries +are still allowed. +.Pp +.It execstack +Marks the object as requiring executable stack. +.Pp +.It 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. +.Pp +.It interpose +Marks the object that its symbol table interposes before all symbols but the +primary executable. +.Pp +.It 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. +.Pp +.It loadfltr +Marks the object that its filters be processed immediately at runtime. +.Pp +.It muldefs +Allows multiple definitions. +.Pp +.It nocombreloc +Disables multiple reloc sections combining. +.Pp +.It nocopyreloc +Disables production of copy relocs. +.Pp +.It nodefaultlib +Marks the object that the search for dependencies of this object will ignore +any default library search paths. +.Pp +.It nodelete +Marks the object shouldn't be unloaded at runtime. +.Pp +.It nodlopen +Marks the object not available to +.Li dlopen . +.Pp +.It nodump +Marks the object can not be dumped by +.Li dldump . +.Pp +.It noexecstack +Marks the object as not requiring executable stack. +.Pp +.It norelro +Don't create an ELF +.Li PT_GNU_RELRO +segment header in the object. +.Pp +.It 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. +.Pp +.It origin +Marks the object may contain $ORIGIN. +.Pp +.It relro +Create an ELF +.Li PT_GNU_RELRO +segment header in the object. +.Pp +.It max-page-size= Va value +Set the emulation maximum page size to +.Va value . +.Pp +.It common-page-size= Va value +Set the emulation common page size to +.Va value . +.Pp +.El +Other keywords are ignored for Solaris compatibility. +.Pp +.It -( Va archives -) +.It --start-group Va archives --end-group +The +.Va archives +should be a list of archive files. They may be either explicit file names, +or +.Li -l +options. +.Pp +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. +.Pp +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. +.Pp +.It --accept-unknown-input-arch +.It --no-accept-unknown-input-arch +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 +.Li --accept-unknown-input-arch +option has been added to restore the old behaviour. +.Pp +.It --as-needed +.It --no-as-needed +This option affects ELF DT_NEEDED tags for dynamic libraries mentioned on +the command line after the +.Op --as-needed +option. Normally, the linker will add a DT_NEEDED tag for each dynamic library +mentioned on the command line, regardless of whether the library is actually +needed. +.Op --as-needed +causes DT_NEEDED 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. +.Op --no-as-needed +restores the default behaviour. +.Pp +.It --add-needed +.It --no-add-needed +This option affects the treatment of dynamic libraries from ELF DT_NEEDED +tags in dynamic libraries mentioned on the command line after the +.Op --no-add-needed +option. Normally, the linker will add a DT_NEEDED tag for each dynamic library +from DT_NEEDED tags. +.Op --no-add-needed +causes DT_NEEDED tags will never be emitted for those libraries from DT_NEEDED +tags. +.Op --add-needed +restores the default behaviour. +.Pp +.It -assert Va keyword +This option is ignored for SunOS compatibility. +.Pp +.It -Bdynamic +.It -dy +.It -call_shared +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 +.Op -l +options which follow it. +.Pp +.It -Bgroup +Set the +.Li DF_1_GROUP +flag in the +.Li DT_FLAGS_1 +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. +.Op --unresolved-symbols=report-all +is implied. This option is only meaningful on ELF platforms which support +shared libraries. +.Pp +.It -Bstatic +.It -dn +.It -non_shared +.It -static +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 +.Op -l +options which follow it. This option also implies +.Op --unresolved-symbols=report-all . +This option can be used with +.Op -shared . +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. +.Pp +.It -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 ELF platforms which support shared +libraries. +.Pp +.It -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 ELF platforms which support shared libraries. +.Pp +.It --dynamic-list= Va 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 ELF platforms which support shared libraries. +.Pp +The format of the dynamic list is the same as the version node without scope +and node name. See VERSION for more information. +.Pp +.It --dynamic-list-data +Include all global data symbols to the dynamic list. +.Pp +.It --dynamic-list-cpp-new +Provide the builtin dynamic list for C++ operator new and delete. It is mainly +useful for building shared libstdc++. +.Pp +.It --dynamic-list-cpp-typeinfo +Provide the builtin dynamic list for C++ runtime type identification. +.Pp +.It --check-sections +.It --no-check-sections +Asks the linker +.Em not +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 +.Op --check-sections . +.Pp +.It --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. +.Pp +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. +.Pp +.It --no-define-common +This option inhibits the assignment of addresses to common symbols. The script +command +.Li INHIBIT_COMMON_ALLOCATION +has the same effect.See Section +.Dq Miscellaneous Commands . +.Pp +The +.Li --no-define-common +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 +.Li --no-define-common +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. +.Pp +.It --defsym Va symbol= Va expression +Create a global symbol in the output file, containing the absolute address +given by +.Va expression . +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 +.Va expression +in this context: you may give a hexadecimal constant or the name of an existing +symbol, or use +.Li + +and +.Li - +to add or subtract hexadecimal constants or symbols. If you need more elaborate +expressions, consider using the linker command language from a script (see Section +.Dq Assignments ) . +.Em Note: +there should be no white space between +.Va symbol , +the equals sign (\(lq=\(rq), and +.Va expression . +.Pp +.It --demangle[= Va style] +.It --no-demangle +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 +.Li COLLECT_NO_DEMANGLE +is set. These options may be used to override the default. +.Pp +.It --dynamic-linker Va file +Set the name of the dynamic linker. This is only meaningful when generating +dynamically linked ELF executables. The default dynamic linker is normally +correct; don't use this unless you know what you are doing. +.Pp +.It --fatal-warnings +Treat all warnings as errors. +.Pp +.It --force-exe-suffix +Make sure that an output file has a .exe suffix. +.Pp +If a successfully built fully linked output file does not have a +.Li .exe +or +.Li .dll +suffix, this option forces the linker to copy the output file to one of the +same name with a +.Li .exe +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 +.Li .exe +suffix. +.Pp +.It --gc-sections +.It --no-gc-sections +Enable garbage collection of unused input sections. It is ignored on targets +that do not support this option. This option is not compatible with +.Li -r +or +.Li --emit-relocs . +The default behaviour (of not performing this garbage collection) can be restored +by specifying +.Li --no-gc-sections +on the command line. +.Pp +.It --print-gc-sections +.It --no-print-gc-sections +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 +.Li --gc-sections ) +option. The default behaviour (of not listing the sections that are removed) +can be restored by specifying +.Li --no-print-gc-sections +on the command line. +.Pp +.It --help +Print a summary of the command-line options on the standard output and exit. +.Pp +.It --target-help +Print a summary of all target specific options on the standard output and +exit. +.Pp +.It -Map Va mapfile +Print a link map to the file +.Va mapfile . +See the description of the +.Op -M +option, above. +.Pp +.It --no-keep-memory +.Xr ld +normally optimizes for speed over memory usage by caching the symbol tables +of input files in memory. This option tells +.Xr ld +to instead optimize for memory usage, by rereading the symbol tables as necessary. +This may be required if +.Xr ld +runs out of memory space while linking a large executable. +.Pp +.It --no-undefined +.It -z defs +Report unresolved symbol references from regular object files. This is done +even if the linker is creating a non-symbolic shared library. The switch +.Op --[no-]allow-shlib-undefined +controls the behaviour for reporting unresolved references found in shared +libraries being linked in. +.Pp +.It --allow-multiple-definition +.It -z muldefs +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. +.Pp +.It --allow-shlib-undefined +.It --no-allow-shlib-undefined +Allows (the default) or disallows undefined symbols in shared libraries. This +switch is similar to +.Op --no-undefined +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. +.Pp +The reason that +.Op --allow-shlib-undefined +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 HPPA shared libraries to +have undefined symbols. +.Pp +.It --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. +.Pp +.It --default-symver +Create and use a default symbol version (the soname) for unversioned exported +symbols. +.Pp +.It --default-imported-symver +Create and use a default symbol version (the soname) for unversioned imported +symbols. +.Pp +.It --no-warn-mismatch +Normally +.Xr ld +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 +.Xr ld +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. +.Pp +.It --no-warn-search-mismatch +Normally +.Xr ld +will give a warning if it finds an incompatible library during a library search. +This option silences the warning. +.Pp +.It --no-whole-archive +Turn off the effect of the +.Op --whole-archive +option for subsequent archive files. +.Pp +.It --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. +.Pp +.It -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. +.Pp +.It --oformat Va output-format +.Xr ld +may be configured to support more than one kind of object file. If your +.Xr ld +is configured this way, you can use the +.Li --oformat +option to specify the binary format for the output object file. Even when +.Xr ld +is configured to support alternative object formats, you don't usually need +to specify this, as +.Xr ld +should be configured to produce as a default output format the most usual +format on each machine. +.Va output-format +is a text string, the name of a particular format supported by the BFD libraries. +(You can list the available binary formats with +.Li objdump -i . ) +The script command +.Li OUTPUT_FORMAT +can also specify the output format, but this option overrides it.See Section +.Dq BFD . +.Pp +.It -pie +.It --pic-executable +Create a position independent executable. This is currently only supported +on ELF platforms. Position independent executables are similar to shared libraries +in that they are relocated by the dynamic linker to the virtual address the +OS 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. +.Pp +.It -qmagic +This option is ignored for Linux compatibility. +.Pp +.It -Qy +This option is ignored for SVR4 compatibility. +.Pp +.It --relax +An option with machine dependent effects. This option is only supported on +a few targets.See Section +.Dq H8/300 . +See Section.Dq i960 . +See Section.Dq Xtensa . +See Section.Dq M68HC11/68HC12 . +See Section.Dq PowerPC ELF32 . +.Pp +On some platforms, the +.Li --relax +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. +.Pp +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 MN10200 and MN10300 family of processors. +.Pp +On platforms where this is not supported, +.Li --relax +is accepted, but ignored. +.Pp +.It --retain-symbols-file Va filename +Retain +.Em only +the symbols listed in the file +.Va filename , +discarding all others. +.Va filename +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. +.Pp +.Li --retain-symbols-file +does +.Em not +discard undefined symbols, or symbols needed for relocations. +.Pp +You may only specify +.Li --retain-symbols-file +once in the command line. It overrides +.Li -s +and +.Li -S . +.Pp +.It -rpath Va dir +Add a directory to the runtime library search path. This is used when linking +an ELF executable with shared objects. All +.Op -rpath +arguments are concatenated and passed to the runtime linker, which uses them +to locate shared objects at runtime. The +.Op -rpath +option is also used when locating shared objects which are needed by shared +objects explicitly included in the link; see the description of the +.Op -rpath-link +option. If +.Op -rpath +is not used when linking an ELF executable, the contents of the environment +variable +.Li LD_RUN_PATH +will be used if it is defined. +.Pp +The +.Op -rpath +option may also be used on SunOS. By default, on SunOS, the linker will form +a runtime search patch out of all the +.Op -L +options it is given. If a +.Op -rpath +option is used, the runtime search path will be formed exclusively using the +.Op -rpath +options, ignoring the +.Op -L +options. This can be useful when using gcc, which adds many +.Op -L +options which may be on NFS mounted file systems. +.Pp +For compatibility with other ELF linkers, if the +.Op -R +option is followed by a directory name, rather than a file name, it is treated +as the +.Op -rpath +option. +.Pp +.It -rpath-link Va DIR +When using ELF or SunOS, one shared library may require another. This happens +when an +.Li ld -shared +link includes a shared library as one of the input files. +.Pp +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 +.Op -rpath-link +option specifies the first set of directories to search. The +.Op -rpath-link +option may specify a sequence of directory names either by specifying a list +of names separated by colons, or by appearing multiple times. +.Pp +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. +.Pp +The linker uses the following search paths to locate required shared libraries: +.Bl -enum +.It +Any directories specified by +.Op -rpath-link +options. +.It +Any directories specified by +.Op -rpath +options. The difference between +.Op -rpath +and +.Op -rpath-link +is that directories specified by +.Op -rpath +options are included in the executable and used at runtime, whereas the +.Op -rpath-link +option is only effective at link time. Searching +.Op -rpath +in this way is only supported by native linkers and cross linkers which have +been configured with the +.Op --with-sysroot +option. +.It +On an ELF system, if the +.Op -rpath +and +.Li rpath-link +options were not used, search the contents of the environment variable +.Li LD_RUN_PATH . +It is for the native linker only. +.It +On SunOS, if the +.Op -rpath +option was not used, search any directories specified using +.Op -L +options. +.It +For a native linker, the contents of the environment variable +.Li LD_LIBRARY_PATH . +.It +For a native ELF linker, the directories in +.Li DT_RUNPATH +or +.Li DT_RPATH +of a shared library are searched for shared libraries needed by it. The +.Li DT_RPATH +entries are ignored if +.Li DT_RUNPATH +entries exist. +.It +The default directories, normally +.Pa /lib +and +.Pa /usr/lib . +.It +For a native linker on an ELF system, if the file +.Pa /etc/ld.so.conf +exists, the list of directories found in that file. +.El +.Pp +If the required shared library is not found, the linker will issue a warning +and continue with the link. +.Pp +.It -shared +.It -Bshareable +Create a shared library. This is currently only supported on ELF, XCOFF and +SunOS platforms. On SunOS, the linker will automatically create a shared library +if the +.Op -e +option is not used and there are undefined symbols in the link. +.Pp +.It --sort-common +This option tells +.Xr ld +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. +.Pp +.It --sort-section name +This option will apply +.Li SORT_BY_NAME +to all wildcard section patterns in the linker script. +.Pp +.It --sort-section alignment +This option will apply +.Li SORT_BY_ALIGNMENT +to all wildcard section patterns in the linker script. +.Pp +.It --split-by-file [ Va size] +Similar to +.Op --split-by-reloc +but creates a new output section for each input file when +.Va size +is reached. +.Va size +defaults to a size of 1 if not given. +.Pp +.It --split-by-reloc [ Va count] +Tries to creates extra sections in the output file so that no single output +section in the file contains more than +.Va count +relocations. This is useful when generating huge relocatable files for downloading +into certain real time kernels with the COFF object file format; since COFF +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 +.Va count +relocations one output section will contain that many relocations. +.Va count +defaults to a value of 32768. +.Pp +.It --stats +Compute and display statistics about the operation of the linker, such as +execution time and memory usage. +.Pp +.It --sysroot= Va directory +Use +.Va directory +as the location of the sysroot, overriding the configure-time default. This +option is only supported by linkers that were configured using +.Op --with-sysroot . +.Pp +.It --traditional-format +For some targets, the output of +.Xr ld +is different in some ways from the output of some existing linker. This switch +requests +.Xr ld +to use the traditional format instead. +.Pp +For example, on SunOS, +.Xr ld +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 +.Li dbx +program can not read the resulting program ( +.Li gdb +has no trouble). The +.Li --traditional-format +switch tells +.Xr ld +to not combine duplicate entries. +.Pp +.It --section-start Va sectionname= Va org +Locate a section in the output file at the absolute address given by +.Va org . +You may use this option as many times as necessary to locate multiple sections +in the command line. +.Va org +must be a single hexadecimal integer; for compatibility with other linkers, +you may omit the leading +.Li 0x +usually associated with hexadecimal values. +.Em Note: +there should be no white space between +.Va sectionname , +the equals sign (\(lq=\(rq), and +.Va org . +.Pp +.It -Tbss Va org +.It -Tdata Va org +.It -Ttext Va org +Same as --section-start, with +.Li .bss , +.Li .data +or +.Li .text +as the +.Va sectionname . +.Pp +.It --unresolved-symbols= Va method +Determine how to handle unresolved symbols. There are four possible values +for +.Li method : +.Pp +.Bl -tag -width Ds +.It ignore-all +Do not report any unresolved symbols. +.Pp +.It report-all +Report all unresolved symbols. This is the default. +.Pp +.It ignore-in-object-files +Report unresolved symbols that are contained in shared libraries, but ignore +them if they come from regular object files. +.Pp +.It 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. +.El +.Pp +The behaviour for shared libraries on their own can also be controlled by +the +.Op --[no-]allow-shlib-undefined +option. +.Pp +Normally the linker will generate an error message for each reported unresolved +symbol but the option +.Op --warn-unresolved-symbols +can change this to a warning. +.Pp +.It --dll-verbose +.It --verbose +Display the version number for +.Xr ld +and list the linker emulations supported. Display which input files can and +cannot be opened. Display the linker script being used by the linker. +.Pp +.It --version-script= Va 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 ELF platforms which support shared libraries.See Section +.Dq VERSION . +.Pp +.It --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. +.Pp +There are three kinds of global symbols, illustrated here by C examples: +.Pp +.Bl -tag -width Ds +.It int i = 1; +A definition, which goes in the initialized data section of the output file. +.Pp +.It 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. +.Pp +.It 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. +.El +.Pp +The +.Li --warn-common +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. +.Pp +.Bl -enum +.It +Turning a common symbol into a reference, because there is already a definition +for the symbol. +.Bd -literal -offset indent +file(section): warning: common of `symbol' + overridden by definition +file(section): warning: defined here +.Ed +.Pp +.It +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. +.Bd -literal -offset indent +file(section): warning: definition of `symbol' + overriding common +file(section): warning: common is here +.Ed +.Pp +.It +Merging a common symbol with a previous same-sized common symbol. +.Bd -literal -offset indent +file(section): warning: multiple common + of `symbol' +file(section): warning: previous common is here +.Ed +.Pp +.It +Merging a common symbol with a previous larger common symbol. +.Bd -literal -offset indent +file(section): warning: common of `symbol' + overridden by larger common +file(section): warning: larger common is here +.Ed +.Pp +.It +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. +.Bd -literal -offset indent +file(section): warning: common of `symbol' + overriding smaller common +file(section): warning: smaller common is here +.Ed +.El +.Pp +.It --warn-constructors +Warn if any global constructors are used. This is only useful for a few object +file formats. For formats like COFF or ELF, the linker can not detect the +use of global constructors. +.Pp +.It --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. +.Pp +.It --warn-once +Only warn once for each undefined symbol, rather than once per module which +refers to it. +.Pp +.It --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 +.Li SECTIONS +command does not specify a start address for the section (see Section +.Dq SECTIONS ) . +.Pp +.It --warn-shared-textrel +Warn if the linker adds a DT_TEXTREL to a shared object. +.Pp +.It --warn-unresolved-symbols +If the linker is going to report an unresolved symbol (see the option +.Op --unresolved-symbols ) +it will normally generate an error. This option makes it generate a warning +instead. +.Pp +.It --error-unresolved-symbols +This restores the linker's default behaviour of generating errors when it +is reporting unresolved symbols. +.Pp +.It --whole-archive +For each archive mentioned on the command line after the +.Op --whole-archive +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. +.Pp +Two notes when using this option from gcc: First, gcc doesn't know about this +option, so you have to use +.Op -Wl,-whole-archive . +Second, don't forget to use +.Op -Wl,-no-whole-archive +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. +.Pp +.It --wrap Va symbol +Use a wrapper function for +.Va symbol . +Any undefined reference to +.Va symbol +will be resolved to +.Li __wrap_ Va symbol . +Any undefined reference to +.Li __real_ Va symbol +will be resolved to +.Va symbol . +.Pp +This can be used to provide a wrapper for a system function. The wrapper function +should be called +.Li __wrap_ Va symbol . +If it wishes to call the system function, it should call +.Li __real_ Va symbol . +.Pp +Here is a trivial example: +.Pp +.Bd -literal -offset indent +void * +__wrap_malloc (size_t c) +{ + printf ("malloc called with %zu\en", c); + return __real_malloc (c); +} +.Ed +.Pp +If you link other code with this file using +.Op --wrap malloc , +then all calls to +.Li malloc +will call the function +.Li __wrap_malloc +instead. The call to +.Li __real_malloc +in +.Li __wrap_malloc +will call the real +.Li malloc +function. +.Pp +You may wish to provide a +.Li __real_malloc +function as well, so that links without the +.Op --wrap +option will succeed. If you do this, you should not put the definition of +.Li __real_malloc +in the same file as +.Li __wrap_malloc ; +if you do, the assembler may resolve the call before the linker has a chance +to wrap it to +.Li malloc . +.Pp +.It --eh-frame-hdr +Request creation of +.Li .eh_frame_hdr +section and ELF +.Li PT_GNU_EH_FRAME +segment header. +.Pp +.It --enable-new-dtags +.It --disable-new-dtags +This linker can create the new dynamic tags in ELF. But the older ELF systems +may not understand them. If you specify +.Op --enable-new-dtags , +the dynamic tags will be created as needed. If you specify +.Op --disable-new-dtags , +no new dynamic tags will be created. By default, the new dynamic tags are +not created. Note that those options are only available for ELF systems. +.Pp +.It --hash-size= Va number +Set the default size of the linker's hash tables to a prime number close to +.Va number . +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. +.Pp +.It --hash-style= Va style +Set the type of linker's hash table(s). +.Va style +can be either +.Li sysv +for classic ELF +.Li .hash +section, +.Li GNU +for new style GNU +.Li .GNU.hash +section or +.Li both +for both the classic ELF +.Li .hash +and new style GNU +.Li .GNU.hash +hash tables. The default is +.Li sysv . +.Pp +.It --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. +.Pp +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 +.Op --hash-size +switch has been used. +.Pp +The +.Op --reduce-memory-overheads +switch may be also be used to enable other tradeoffs in future versions of +the linker. +.Pp +.El +.Em Options Specific to i386 PE Targets +.Pp +The i386 PE linker supports the +.Op -shared +option, which causes the output to be a dynamically linked library (DLL) instead +of a normal executable. You should name the output +.Li *.dll +when you use this option. In addition, the linker fully supports the standard +.Li *.def +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 PE linker support +additional command line options that are specific to the i386 PE target. Options +that take values may be separated from their values by either a space or an +equals sign. +.Pp +.Bl -tag -width Ds +.It --add-stdcall-alias +If given, symbols with a stdcall suffix (@ +.Va nn ) +will be exported as-is and also with the suffix stripped. [This option is +specific to the i386 PE targeted port of the linker] +.Pp +.It --base-file Va file +Use +.Va file +as the name of a file in which to save the base addresses of all the relocations +needed for generating DLLs with +.Pa dlltool . +[This is an i386 PE specific option] +.Pp +.It --dll +Create a DLL instead of a regular executable. You may also use +.Op -shared +or specify a +.Li LIBRARY +in a given +.Li .def +file. [This option is specific to the i386 PE targeted port of the linker] +.Pp +.It --enable-stdcall-fixup +.It --disable-stdcall-fixup +If the link finds a symbol that it cannot resolve, it will attempt to do \(lqfuzzy +linking\(rq 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 +.Li _foo +might be linked to the function +.Li _foo@12 , +or the undefined symbol +.Li _bar@16 +might be linked to the function +.Li _bar . +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 +.Op --enable-stdcall-fixup , +this feature is fully enabled and warnings are not printed. If you specify +.Op --disable-stdcall-fixup , +this feature is disabled and such mismatches are considered to be errors. +[This option is specific to the i386 PE targeted port of the linker] +.Pp +.It --export-all-symbols +If given, all global symbols in the objects used to build a DLL will be exported +by the DLL. Note that this is the default if there otherwise wouldn't be any +exported symbols. When symbols are explicitly exported via DEF files or implicitly +exported via function attributes, the default is to not export anything else +unless this option is given. Note that the symbols +.Li DllMain@12 , +.Li DllEntryPoint@0 , +.Li DllMainCRTStartup@12 , +and +.Li impure_ptr +will not be automatically exported. Also, symbols imported from other DLLs +will not be re-exported, nor will symbols specifying the DLL's internal layout +such as those beginning with +.Li _head_ +or ending with +.Li _iname . +In addition, no symbols from +.Li libgcc , +.Li libstd++ , +.Li libmingw32 , +or +.Li crtX.o +will be exported. Symbols whose names begin with +.Li __rtti_ +or +.Li __builtin_ +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: +.Li _cygwin_dll_entry@12 , +.Li _cygwin_crt0_common@8 , +.Li _cygwin_noncygwin_dll_entry@12 , +.Li _fmode , +.Li _impure_ptr , +.Li cygwin_attach_dll , +.Li cygwin_premain0 , +.Li cygwin_premain1 , +.Li cygwin_premain2 , +.Li cygwin_premain3 , +and +.Li environ . +[This option is specific to the i386 PE targeted port of the linker] +.Pp +.It --exclude-symbols Va symbol, Va 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 PE targeted port of the linker] +.Pp +.It --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 PE targeted port of the linker] +.Pp +.It --heap Va reserve +.It --heap Va reserve, Va commit +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 PE targeted port of the linker] +.Pp +.It --image-base Va value +Use +.Va value +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 PE targeted +port of the linker] +.Pp +.It --kill-at +If given, the stdcall suffixes (@ +.Va nn ) +will be stripped from symbols before they are exported. [This option is specific +to the i386 PE targeted port of the linker] +.Pp +.It --large-address-aware +If given, the appropriate bit in the \(lqCharacteristics\(rq field of the COFF 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= +.Va value +megabytes switch in the \(lq[operating systems]\(rq section of the BOOT.INI. Otherwise, +this bit has no effect. [This option is specific to PE targeted ports of the +linker] +.Pp +.It --major-image-version Va value +Sets the major number of the \(lqimage version\(rq. Defaults to 1. [This option is +specific to the i386 PE targeted port of the linker] +.Pp +.It --major-os-version Va value +Sets the major number of the \(lqos version\(rq. Defaults to 4. [This option is specific +to the i386 PE targeted port of the linker] +.Pp +.It --major-subsystem-version Va value +Sets the major number of the \(lqsubsystem version\(rq. Defaults to 4. [This option +is specific to the i386 PE targeted port of the linker] +.Pp +.It --minor-image-version Va value +Sets the minor number of the \(lqimage version\(rq. Defaults to 0. [This option is +specific to the i386 PE targeted port of the linker] +.Pp +.It --minor-os-version Va value +Sets the minor number of the \(lqos version\(rq. Defaults to 0. [This option is specific +to the i386 PE targeted port of the linker] +.Pp +.It --minor-subsystem-version Va value +Sets the minor number of the \(lqsubsystem version\(rq. Defaults to 0. [This option +is specific to the i386 PE targeted port of the linker] +.Pp +.It --output-def Va file +The linker will create the file +.Va file +which will contain a DEF file corresponding to the DLL the linker is generating. +This DEF file (which should be called +.Li *.def ) +may be used to create an import library with +.Li dlltool +or may be used as a reference to automatically or implicitly exported symbols. +[This option is specific to the i386 PE targeted port of the linker] +.Pp +.It --out-implib Va file +The linker will create the file +.Va file +which will contain an import lib corresponding to the DLL the linker is generating. +This import lib (which should be called +.Li *.dll.a +or +.Li *.a +may be used to link clients against the generated DLL; this behaviour makes +it possible to skip a separate +.Li dlltool +import library creation step. [This option is specific to the i386 PE targeted +port of the linker] +.Pp +.It --enable-auto-image-base +Automatically choose the image base for DLLs, unless one is specified using +the +.Li --image-base +argument. By using a hash generated from the dllname to create unique image +bases for each DLL, in-memory collisions and relocations which can delay program +execution are avoided. [This option is specific to the i386 PE targeted port +of the linker] +.Pp +.It --disable-auto-image-base +Do not automatically generate a unique image base. If there is no user-specified +image base ( +.Li --image-base ) +then use the platform default. [This option is specific to the i386 PE targeted +port of the linker] +.Pp +.It --dll-search-prefix Va string +When linking dynamically to a dll without an import library, search for +.Li <string><basename>.dll +in preference to +.Li lib<basename>.dll . +This behaviour allows easy distinction between DLLs built for the various +"subplatforms": native, cygwin, uwin, pw, etc. For instance, cygwin DLLs typically +use +.Li --dll-search-prefix=cyg . +[This option is specific to the i386 PE targeted port of the linker] +.Pp +.It --enable-auto-import +Do sophisticated linking of +.Li _symbol +to +.Li __imp__symbol +for DATA imports from DLLs, and create the necessary thunking symbols when +building the import libraries with those DATA 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. +.Pp +Using 'auto-import' generally will 'just work' -- but sometimes you may see +this message: +.Pp +"variable '<var>' can't be auto-imported. Please read the documentation for +ld's +.Li --enable-auto-import +for details." +.Pp +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 DLL, as well as using a constant index into an array variable +imported from a DLL. 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. +.Pp +There are several ways to address this difficulty, regardless of the data +type of the exported variable: +.Pp +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. +.Pp +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: +.Pp +.Bd -literal -offset indent +extern type extern_array[]; +extern_array[1] --> + { volatile type *t=extern_array; t[1] } +.Ed +.Pp +or +.Pp +.Bd -literal -offset indent +extern type extern_array[]; +extern_array[1] --> + { volatile int t=1; extern_array[t] } +.Ed +.Pp +For structs (and most other multiword data types) the only option is to make +the struct itself (or the long long, or the ...) variable: +.Pp +.Bd -literal -offset indent +extern struct s extern_struct; +extern_struct.field --> + { volatile struct s *t=&extern_struct; t->field } +.Ed +.Pp +or +.Pp +.Bd -literal -offset indent +extern long long extern_ll; +extern_ll --> + { volatile long long * local_ll=&extern_ll; *local_ll } +.Ed +.Pp +A third method of dealing with this difficulty is to abandon 'auto-import' +for the offending symbol and mark it with +.Li __declspec(dllimport) . +However, in practise that requires using compile-time #defines to indicate +whether you are building a DLL, building client code that will link to the +DLL, 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: +.Pp +Original: +.Bd -literal -offset indent +--foo.h +extern int arr[]; +--foo.c +#include "foo.h" +void main(int argc, char **argv){ + printf("%d\en",arr[1]); +} +.Ed +.Pp +Solution 1: +.Bd -literal -offset indent +--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]); +} +.Ed +.Pp +Solution 2: +.Bd -literal -offset indent +--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]); +} +.Ed +.Pp +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. set_foo() +and get_foo() accessor functions). [This option is specific to the i386 PE +targeted port of the linker] +.Pp +.It --disable-auto-import +Do not attempt to do sophisticated linking of +.Li _symbol +to +.Li __imp__symbol +for DATA imports from DLLs. [This option is specific to the i386 PE targeted +port of the linker] +.Pp +.It --enable-runtime-pseudo-reloc +If your code contains expressions described in --enable-auto-import section, +that is, DATA imports from DLL 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 PE targeted port of the linker] +.Pp +.It --disable-runtime-pseudo-reloc +Do not create pseudo relocations for non-zero offset DATA imports from DLLs. +This is the default. [This option is specific to the i386 PE targeted port +of the linker] +.Pp +.It --enable-extra-pe-debug +Show additional debug info related to auto-import symbol thunking. [This option +is specific to the i386 PE targeted port of the linker] +.Pp +.It --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 PE targeted port of the linker] +.Pp +.It --stack Va reserve +.It --stack Va reserve, Va commit +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 PE targeted port of the linker] +.Pp +.It --subsystem Va which +.It --subsystem Va which: Va major +.It --subsystem Va which: Va major. Va minor +Specifies the subsystem under which your program will execute. The legal values +for +.Va which +are +.Li native , +.Li windows , +.Li console , +.Li posix , +and +.Li xbox . +You may optionally set the subsystem version also. Numeric values are also +accepted for +.Va which . +[This option is specific to the i386 PE targeted port of the linker] +.Pp +.El +.Em Options specific to Motorola 68HC11 and 68HC12 targets +.Pp +The 68HC11 and 68HC12 linkers support specific options to control the memory +bank switching mapping and trampoline code generation. +.Pp +.Bl -tag -width Ds +.It --no-trampoline +This option disables the generation of trampoline. By default a trampoline +is generated for each far function which is called using a +.Li jsr +instruction (this happens when a pointer to a far function is taken). +.Pp +.It --bank-window Va name +This option indicates to the linker the name of the memory region in the +.Li MEMORY +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. +.Pp +.El +.Ss Environment Variables +You can change the behaviour of +.Xr ld +with the environment variables +.Li GNUTARGET , +.Li LDEMULATION +and +.Li COLLECT_NO_DEMANGLE . +.Pp +.Li GNUTARGET +determines the input-file object format if you don't use +.Li -b +(or its synonym +.Li --format ) . +Its value should be one of the BFD names for an input format (see Section +.Dq BFD ) . +If there is no +.Li GNUTARGET +in the environment, +.Xr ld +uses the natural format of the target. If +.Li GNUTARGET +is set to +.Li default +then BFD 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 BFD on each system +places the conventional format for that system first in the search-list, so +ambiguities are resolved in favor of convention. +.Pp +.Li LDEMULATION +determines the default emulation if you don't use the +.Li -m +option. The emulation can affect various aspects of linker behaviour, particularly +the default linker script. You can list the available emulations with the +.Li --verbose +or +.Li -V +options. If the +.Li -m +option is not used, and the +.Li LDEMULATION +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 +.Li COLLECT_NO_DEMANGLE +is set in the environment, then it will default to not demangling symbols. +This environment variable is used in a similar fashion by the +.Li gcc +linker wrapper program. The default may be overridden by the +.Li --demangle +and +.Li --no-demangle +options. +.Pp +.Sh Linker Scripts +Every link is controlled by a +.Em linker script . +This script is written in the linker command language. +.Pp +The main purpose of the linker script is to describe how the sections in the +input files should be mapped into the output file, and to control the memory +layout of the output file. Most linker scripts do nothing more than this. +However, when necessary, the linker script can also direct the linker to perform +many other operations, using the commands described below. +.Pp +The linker always uses a linker script. If you do not supply one yourself, +the linker will use a default script that is compiled into the linker executable. +You can use the +.Li --verbose +command line option to display the default linker script. Certain command +line options, such as +.Li -r +or +.Li -N , +will affect the default linker script. +.Pp +You may supply your own linker script by using the +.Li -T +command line option. When you do this, your linker script will replace the +default linker script. +.Pp +You may also use linker scripts implicitly by naming them as input files to +the linker, as though they were files to be linked.See Section +.Dq Implicit Linker Scripts . +.Pp +.Ss Basic Linker Script Concepts +We need to define some basic concepts and vocabulary in order to describe +the linker script language. +.Pp +The linker combines input files into a single output file. The output file +and each input file are in a special data format known as an +.Em object file format . +Each file is called an +.Em object file . +The output file is often called an +.Em executable , +but for our purposes we will also call it an object file. Each object file +has, among other things, a list of +.Em sections . +We sometimes refer to a section in an input file as an +.Em input section ; +similarly, a section in the output file is an +.Em output section . +.Pp +Each section in an object file has a name and a size. Most sections also have +an associated block of data, known as the +.Em section contents . +A section may be marked as +.Em loadable , +which mean that the contents should be loaded into memory when the output +file is run. A section with no contents may be +.Em allocatable , +which means that an area in memory should be set aside, but nothing in particular +should be loaded there (in some cases this memory must be zeroed out). A section +which is neither loadable nor allocatable typically contains some sort of +debugging information. +.Pp +Every loadable or allocatable output section has two addresses. The first +is the +.Em VMA , +or virtual memory address. This is the address the section will have when +the output file is run. The second is the +.Em LMA , +or load memory address. This is the address at which the section will be loaded. +In most cases the two addresses will be the same. An example of when they +might be different is when a data section is loaded into ROM, and then copied +into RAM when the program starts up (this technique is often used to initialize +global variables in a ROM based system). In this case the ROM address would +be the LMA, and the RAM address would be the VMA. +.Pp +You can see the sections in an object file by using the +.Li objdump +program with the +.Li -h +option. +.Pp +Every object file also has a list of +.Em symbols , +known as the +.Em symbol table . +A symbol may be defined or undefined. Each symbol has a name, and each defined +symbol has an address, among other information. If you compile a C or C++ +program into an object file, you will get a defined symbol for every defined +function and global or static variable. Every undefined function or global +variable which is referenced in the input file will become an undefined symbol. +.Pp +You can see the symbols in an object file by using the +.Li nm +program, or by using the +.Li objdump +program with the +.Li -t +option. +.Pp +.Ss Linker Script Format +Linker scripts are text files. +.Pp +You write a linker script as a series of commands. Each command is either +a keyword, possibly followed by arguments, or an assignment to a symbol. You +may separate commands using semicolons. Whitespace is generally ignored. +.Pp +Strings such as file or format names can normally be entered directly. If +the file name contains a character such as a comma which would otherwise serve +to separate file names, you may put the file name in double quotes. There +is no way to use a double quote character in a file name. +.Pp +You may include comments in linker scripts just as in C, delimited by +.Li /* +and +.Li */ . +As in C, comments are syntactically equivalent to whitespace. +.Pp +.Ss Simple Linker Script Example +Many linker scripts are fairly simple. +.Pp +The simplest possible linker script has just one command: +.Li SECTIONS . +You use the +.Li SECTIONS +command to describe the memory layout of the output file. +.Pp +The +.Li SECTIONS +command is a powerful command. Here we will describe a simple use of it. Let's +assume your program consists only of code, initialized data, and uninitialized +data. These will be in the +.Li .text , +.Li .data , +and +.Li .bss +sections, respectively. Let's assume further that these are the only sections +which appear in your input files. +.Pp +For this example, let's say that the code should be loaded at address 0x10000, +and that the data should start at address 0x8000000. Here is a linker script +which will do that: +.Bd -literal -offset indent +SECTIONS +{ + . = 0x10000; + .text : { *(.text) } + . = 0x8000000; + .data : { *(.data) } + .bss : { *(.bss) } +} +.Ed +.Pp +You write the +.Li SECTIONS +command as the keyword +.Li SECTIONS , +followed by a series of symbol assignments and output section descriptions +enclosed in curly braces. +.Pp +The first line inside the +.Li SECTIONS +command of the above example sets the value of the special symbol +.Li . , +which is the location counter. If you do not specify the address of an output +section in some other way (other ways are described later), the address is +set from the current value of the location counter. The location counter is +then incremented by the size of the output section. At the start of the +.Li SECTIONS +command, the location counter has the value +.Li 0 . +.Pp +The second line defines an output section, +.Li .text . +The colon is required syntax which may be ignored for now. Within the curly +braces after the output section name, you list the names of the input sections +which should be placed into this output section. The +.Li * +is a wildcard which matches any file name. The expression +.Li *(.text) +means all +.Li .text +input sections in all input files. +.Pp +Since the location counter is +.Li 0x10000 +when the output section +.Li .text +is defined, the linker will set the address of the +.Li .text +section in the output file to be +.Li 0x10000 . +.Pp +The remaining lines define the +.Li .data +and +.Li .bss +sections in the output file. The linker will place the +.Li .data +output section at address +.Li 0x8000000 . +After the linker places the +.Li .data +output section, the value of the location counter will be +.Li 0x8000000 +plus the size of the +.Li .data +output section. The effect is that the linker will place the +.Li .bss +output section immediately after the +.Li .data +output section in memory. +.Pp +The linker will ensure that each output section has the required alignment, +by increasing the location counter if necessary. In this example, the specified +addresses for the +.Li .text +and +.Li .data +sections will probably satisfy any alignment constraints, but the linker may +have to create a small gap between the +.Li .data +and +.Li .bss +sections. +.Pp +That's it! That's a simple and complete linker script. +.Pp +.Ss Simple Linker Script Commands +In this section we describe the simple linker script commands. +.Pp +.Em Setting the Entry Point +.Pp +The first instruction to execute in a program is called the +.Em entry point . +You can use the +.Li ENTRY +linker script command to set the entry point. The argument is a symbol name: +.Bd -literal -offset indent +ENTRY(symbol) +.Ed +.Pp +There are several ways to set the entry point. The linker will set the entry +point by trying each of the following methods in order, and stopping when +one of them succeeds: +.Bl -bullet +.It +the +.Li -e +.Va entry +command-line option; +.It +the +.Li ENTRY( Va symbol) +command in a linker script; +.It +the value of the symbol +.Li start , +if defined; +.It +the address of the first byte of the +.Li .text +section, if present; +.It +The address +.Li 0 . +.El +.Pp +.Em Commands Dealing with Files +.Pp +Several linker script commands deal with files. +.Pp +.Bl -tag -width Ds +.It INCLUDE Va filename +Include the linker script +.Va filename +at this point. The file will be searched for in the current directory, and +in any directory specified with the +.Op -L +option. You can nest calls to +.Li INCLUDE +up to 10 levels deep. +.Pp +.It INPUT( Va file, Va file, ...) +.It INPUT( Va file Va file ...) +The +.Li INPUT +command directs the linker to include the named files in the link, as though +they were named on the command line. +.Pp +For example, if you always want to include +.Pa subr.o +any time you do a link, but you can't be bothered to put it on every link +command line, then you can put +.Li INPUT (subr.o) +in your linker script. +.Pp +In fact, if you like, you can list all of your input files in the linker script, +and then invoke the linker with nothing but a +.Li -T +option. +.Pp +In case a +.Em sysroot prefix +is configured, and the filename starts with the +.Li / +character, and the script being processed was located inside the +.Em sysroot prefix , +the filename will be looked for in the +.Em sysroot prefix . +Otherwise, the linker will try to open the file in the current directory. +If it is not found, the linker will search through the archive library search +path. See the description of +.Li -L +in Options,,Command Line Options. +.Pp +If you use +.Li INPUT (-l Va file) , +.Xr ld +will transform the name to +.Li lib Va file.a , +as with the command line argument +.Li -l . +.Pp +When you use the +.Li INPUT +command in an implicit linker script, the files will be included in the link +at the point at which the linker script file is included. This can affect +archive searching. +.Pp +.It GROUP( Va file, Va file, ...) +.It GROUP( Va file Va file ...) +The +.Li GROUP +command is like +.Li INPUT , +except that the named files should all be archives, and they are searched +repeatedly until no new undefined references are created. See the description +of +.Li -( +in Options,,Command Line Options. +.Pp +.It AS_NEEDED( Va file, Va file, ...) +.It AS_NEEDED( Va file Va file ...) +This construct can appear only inside of the +.Li INPUT +or +.Li GROUP +commands, among other filenames. The files listed will be handled as if they +appear directly in the +.Li INPUT +or +.Li GROUP +commands, with the exception of ELF shared libraries, that will be added only +when they are actually needed. This construct essentially enables +.Op --as-needed +option for all the files listed inside of it and restores previous +.Op --as-needed +resp. +.Op --no-as-needed +setting afterwards. +.Pp +.It OUTPUT( Va filename) +The +.Li OUTPUT +command names the output file. Using +.Li OUTPUT( Va filename) +in the linker script is exactly like using +.Li -o Va filename +on the command line (see Section +.Dq Options ) . +If both are used, the command line option takes precedence. +.Pp +You can use the +.Li OUTPUT +command to define a default name for the output file other than the usual +default of +.Pa a.out . +.Pp +.It SEARCH_DIR( Va path) +The +.Li SEARCH_DIR +command adds +.Va path +to the list of paths where +.Xr ld +looks for archive libraries. Using +.Li SEARCH_DIR( Va path) +is exactly like using +.Li -L Va path +on the command line (see Section +.Dq Options ) . +If both are used, then the linker will search both paths. Paths specified +using the command line option are searched first. +.Pp +.It STARTUP( Va filename) +The +.Li STARTUP +command is just like the +.Li INPUT +command, except that +.Va filename +will become the first input file to be linked, as though it were specified +first on the command line. This may be useful when using a system in which +the entry point is always the start of the first file. +.El +.Pp +.Em Commands Dealing with Object File Formats +.Pp +A couple of linker script commands deal with object file formats. +.Pp +.Bl -tag -width Ds +.It OUTPUT_FORMAT( Va bfdname) +.It OUTPUT_FORMAT( Va default, Va big, Va little) +The +.Li OUTPUT_FORMAT +command names the BFD format to use for the output file (see Section +.Dq BFD ) . +Using +.Li OUTPUT_FORMAT( Va bfdname) +is exactly like using +.Li --oformat Va bfdname +on the command line (see Section +.Dq Options ) . +If both are used, the command line option takes precedence. +.Pp +You can use +.Li OUTPUT_FORMAT +with three arguments to use different formats based on the +.Li -EB +and +.Li -EL +command line options. This permits the linker script to set the output format +based on the desired endianness. +.Pp +If neither +.Li -EB +nor +.Li -EL +are used, then the output format will be the first argument, +.Va default . +If +.Li -EB +is used, the output format will be the second argument, +.Va big . +If +.Li -EL +is used, the output format will be the third argument, +.Va little . +.Pp +For example, the default linker script for the MIPS ELF target uses this command: +.Bd -literal -offset indent +OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips) +.Ed +This says that the default format for the output file is +.Li elf32-bigmips , +but if the user uses the +.Li -EL +command line option, the output file will be created in the +.Li elf32-littlemips +format. +.Pp +.It TARGET( Va bfdname) +The +.Li TARGET +command names the BFD format to use when reading input files. It affects subsequent +.Li INPUT +and +.Li GROUP +commands. This command is like using +.Li -b Va bfdname +on the command line (see Section +.Dq Options ) . +If the +.Li TARGET +command is used but +.Li OUTPUT_FORMAT +is not, then the last +.Li TARGET +command is also used to set the format for the output file.See Section +.Dq BFD . +.El +.Pp +.Em Other Linker Script Commands +.Pp +There are a few other linker scripts commands. +.Pp +.Bl -tag -width Ds +.It ASSERT( Va exp, Va message) +Ensure that +.Va exp +is non-zero. If it is zero, then exit the linker with an error code, and print +.Va message . +.Pp +.It EXTERN( Va symbol Va symbol ...) +Force +.Va symbol +to be entered in the output file as an undefined symbol. Doing this may, for +example, trigger linking of additional modules from standard libraries. You +may list several +.Va symbol +s for each +.Li EXTERN , +and you may use +.Li EXTERN +multiple times. This command has the same effect as the +.Li -u +command-line option. +.Pp +.It FORCE_COMMON_ALLOCATION +This command has the same effect as the +.Li -d +command-line option: to make +.Xr ld +assign space to common symbols even if a relocatable output file is specified +( +.Li -r ) . +.Pp +.It INHIBIT_COMMON_ALLOCATION +This command has the same effect as the +.Li --no-define-common +command-line option: to make +.Li ld +omit the assignment of addresses to common symbols even for a non-relocatable +output file. +.Pp +.It NOCROSSREFS( Va section Va section ...) +This command may be used to tell +.Xr ld +to issue an error about any references among certain output sections. +.Pp +In certain types of programs, particularly on embedded systems when using +overlays, when one section is loaded into memory, another section will not +be. Any direct references between the two sections would be errors. For example, +it would be an error if code in one section called a function defined in the +other section. +.Pp +The +.Li NOCROSSREFS +command takes a list of output section names. If +.Xr ld +detects any cross references between the sections, it reports an error and +returns a non-zero exit status. Note that the +.Li NOCROSSREFS +command uses output section names, not input section names. +.Pp +.It OUTPUT_ARCH( Va bfdarch) +Specify a particular output machine architecture. The argument is one of the +names used by the BFD library (see Section +.Dq BFD ) . +You can see the architecture of an object file by using the +.Li objdump +program with the +.Li -f +option. +.El +.Pp +.Ss Assigning Values to Symbols +You may assign a value to a symbol in a linker script. This will define the +symbol and place it into the symbol table with a global scope. +.Pp +.Em Simple Assignments +.Pp +You may assign to a symbol using any of the C assignment operators: +.Pp +.Bl -tag -width Ds +.It Va symbol = Va expression ; +.It Va symbol += Va expression ; +.It Va symbol -= Va expression ; +.It Va symbol *= Va expression ; +.It Va symbol /= Va expression ; +.It Va symbol <<= Va expression ; +.It Va symbol >>= Va expression ; +.It Va symbol &= Va expression ; +.It Va symbol |= Va expression ; +.El +.Pp +The first case will define +.Va symbol +to the value of +.Va expression . +In the other cases, +.Va symbol +must already be defined, and the value will be adjusted accordingly. +.Pp +The special symbol name +.Li . +indicates the location counter. You may only use this within a +.Li SECTIONS +command.See Section +.Dq Location Counter . +.Pp +The semicolon after +.Va expression +is required. +.Pp +Expressions are defined below; see Expressions. +.Pp +You may write symbol assignments as commands in their own right, or as statements +within a +.Li SECTIONS +command, or as part of an output section description in a +.Li SECTIONS +command. +.Pp +The section of the symbol will be set from the section of the expression; +for more information, see Expression Section. +.Pp +Here is an example showing the three different places that symbol assignments +may be used: +.Pp +.Bd -literal -offset indent +floating_point = 0; +SECTIONS +{ + .text : + { + *(.text) + _etext = .; + } + _bdata = (. + 3) & ~ 3; + .data : { *(.data) } +} +.Ed +In this example, the symbol +.Li floating_point +will be defined as zero. The symbol +.Li _etext +will be defined as the address following the last +.Li .text +input section. The symbol +.Li _bdata +will be defined as the address following the +.Li .text +output section aligned upward to a 4 byte boundary. +.Pp +.Em PROVIDE +.Pp +In some cases, it is desirable for a linker script to define a symbol only +if it is referenced and is not defined by any object included in the link. +For example, traditional linkers defined the symbol +.Li etext . +However, ANSI C requires that the user be able to use +.Li etext +as a function name without encountering an error. The +.Li PROVIDE +keyword may be used to define a symbol, such as +.Li etext , +only if it is referenced but not defined. The syntax is +.Li PROVIDE( Va symbol = Va expression) . +.Pp +Here is an example of using +.Li PROVIDE +to define +.Li etext : +.Bd -literal -offset indent +SECTIONS +{ + .text : + { + *(.text) + _etext = .; + PROVIDE(etext = .); + } +} +.Ed +.Pp +In this example, if the program defines +.Li _etext +(with a leading underscore), the linker will give a multiple definition error. +If, on the other hand, the program defines +.Li etext +(with no leading underscore), the linker will silently use the definition +in the program. If the program references +.Li etext +but does not define it, the linker will use the definition in the linker script. +.Pp +.Em PROVIDE_HIDDEN +.Pp +Similar to +.Li PROVIDE . +For ELF targeted ports, the symbol will be hidden and won't be exported. +.Pp +.Em Source Code Reference +.Pp +Accessing a linker script defined variable from source code is not intuitive. +In particular a linker script symbol is not equivalent to a variable declaration +in a high level language, it is instead a symbol that does not have a value. +.Pp +Before going further, it is important to note that compilers often transform +names in the source code into different names when they are stored in the +symbol table. For example, Fortran compilers commonly prepend or append an +underscore, and C++ performs extensive +.Li name mangling . +Therefore there might be a discrepancy between the name of a variable as it +is used in source code and the name of the same variable as it is defined +in a linker script. For example in C a linker script variable might be referred +to as: +.Pp +.Bd -literal -offset indent + extern int foo; +.Ed +.Pp +But in the linker script it might be defined as: +.Pp +.Bd -literal -offset indent + _foo = 1000; +.Ed +.Pp +In the remaining examples however it is assumed that no name transformation +has taken place. +.Pp +When a symbol is declared in a high level language such as C, two things happen. +The first is that the compiler reserves enough space in the program's memory +to hold the +.Em value +of the symbol. The second is that the compiler creates an entry in the program's +symbol table which holds the symbol's +.Em address . +ie the symbol table contains the address of the block of memory holding the +symbol's value. So for example the following C declaration, at file scope: +.Pp +.Bd -literal -offset indent + int foo = 1000; +.Ed +.Pp +creates a entry called +.Li foo +in the symbol table. This entry holds the address of an +.Li int +sized block of memory where the number 1000 is initially stored. +.Pp +When a program references a symbol the compiler generates code that first +accesses the symbol table to find the address of the symbol's memory block +and then code to read the value from that memory block. So: +.Pp +.Bd -literal -offset indent + foo = 1; +.Ed +.Pp +looks up the symbol +.Li foo +in the symbol table, gets the address associated with this symbol and then +writes the value 1 into that address. Whereas: +.Pp +.Bd -literal -offset indent + int * a = & foo; +.Ed +.Pp +looks up the symbol +.Li foo +in the symbol table, gets it address and then copies this address into the +block of memory associated with the variable +.Li a . +.Pp +Linker scripts symbol declarations, by contrast, create an entry in the symbol +table but do not assign any memory to them. Thus they are an address without +a value. So for example the linker script definition: +.Pp +.Bd -literal -offset indent + foo = 1000; +.Ed +.Pp +creates an entry in the symbol table called +.Li foo +which holds the address of memory location 1000, but nothing special is stored +at address 1000. This means that you cannot access the +.Em value +of a linker script defined symbol - it has no value - all you can do is access +the +.Em address +of a linker script defined symbol. +.Pp +Hence when you are using a linker script defined symbol in source code you +should always take the address of the symbol, and never attempt to use its +value. For example suppose you want to copy the contents of a section of memory +called .ROM into a section called .FLASH and the linker script contains these +declarations: +.Pp +.Bd -literal -offset indent + + start_of_ROM = .ROM; + end_of_ROM = .ROM + sizeof (.ROM) - 1; + start_of_FLASH = .FLASH; + +.Ed +.Pp +Then the C source code to perform the copy would be: +.Pp +.Bd -literal -offset indent + + extern char start_of_ROM, end_of_ROM, start_of_FLASH; + + memcpy (& start_of_FLASH, & start_of_ROM, & end_of_ROM - & start_of_ROM); + +.Ed +.Pp +Note the use of the +.Li & +operators. These are correct. +.Pp +.Ss SECTIONS Command +The +.Li SECTIONS +command tells the linker how to map input sections into output sections, and +how to place the output sections in memory. +.Pp +The format of the +.Li SECTIONS +command is: +.Bd -literal -offset indent +SECTIONS +{ + sections-command + sections-command + ... +} +.Ed +.Pp +Each +.Va sections-command +may of be one of the following: +.Pp +.Bl -bullet +.It +an +.Li ENTRY +command (see Section +.Dq Entry Point ) +.It +a symbol assignment (see Section +.Dq Assignments ) +.It +an output section description +.It +an overlay description +.El +.Pp +The +.Li ENTRY +command and symbol assignments are permitted inside the +.Li SECTIONS +command for convenience in using the location counter in those commands. This +can also make the linker script easier to understand because you can use those +commands at meaningful points in the layout of the output file. +.Pp +Output section descriptions and overlay descriptions are described below. +.Pp +If you do not use a +.Li SECTIONS +command in your linker script, the linker will place each input section into +an identically named output section in the order that the sections are first +encountered in the input files. If all input sections are present in the first +file, for example, the order of sections in the output file will match the +order in the first input file. The first section will be at address zero. +.Pp +.Em Output Section Description +.Pp +The full description of an output section looks like this: +.Bd -literal -offset indent + +section [address] [(type)] : + [AT(lma)] [ALIGN(section_align)] [SUBALIGN(subsection_align)] + { + output-section-command + output-section-command + ... + } [>region] [AT>lma_region] [:phdr :phdr ...] [=fillexp] + +.Ed +.Pp +Most output sections do not use most of the optional section attributes. +.Pp +The whitespace around +.Va section +is required, so that the section name is unambiguous. The colon and the curly +braces are also required. The line breaks and other white space are optional. +.Pp +Each +.Va output-section-command +may be one of the following: +.Pp +.Bl -bullet +.It +a symbol assignment (see Section +.Dq Assignments ) +.It +an input section description (see Section +.Dq Input Section ) +.It +data values to include directly (see Section +.Dq Output Section Data ) +.It +a special output section keyword (see Section +.Dq Output Section Keywords ) +.El +.Pp +.Em Output Section Name +.Pp +The name of the output section is +.Va section . +.Va section +must meet the constraints of your output format. In formats which only support +a limited number of sections, such as +.Li a.out , +the name must be one of the names supported by the format ( +.Li a.out , +for example, allows only +.Li .text , +.Li .data +or +.Li .bss ) . +If the output format supports any number of sections, but with numbers and +not names (as is the case for Oasys), the name should be supplied as a quoted +numeric string. A section name may consist of any sequence of characters, +but a name which contains any unusual characters such as commas must be quoted. +.Pp +The output section name +.Li /DISCARD/ +is special; Output Section Discarding. +.Pp +.Em Output Section Address +.Pp +The +.Va address +is an expression for the VMA (the virtual memory address) of the output section. +If you do not provide +.Va address , +the linker will set it based on +.Va region +if present, or otherwise based on the current value of the location counter. +.Pp +If you provide +.Va address , +the address of the output section will be set to precisely that. If you provide +neither +.Va address +nor +.Va region , +then the address of the output section will be set to the current value of +the location counter aligned to the alignment requirements of the output section. +The alignment requirement of the output section is the strictest alignment +of any input section contained within the output section. +.Pp +For example, +.Bd -literal -offset indent +\&.text . : { *(.text) } +.Ed +and +.Bd -literal -offset indent +\&.text : { *(.text) } +.Ed +are subtly different. The first will set the address of the +.Li .text +output section to the current value of the location counter. The second will +set it to the current value of the location counter aligned to the strictest +alignment of a +.Li .text +input section. +.Pp +The +.Va address +may be an arbitrary expression; Expressions. For example, if you want to align +the section on a 0x10 byte boundary, so that the lowest four bits of the section +address are zero, you could do something like this: +.Bd -literal -offset indent +\&.text ALIGN(0x10) : { *(.text) } +.Ed +This works because +.Li ALIGN +returns the current location counter aligned upward to the specified value. +.Pp +Specifying +.Va address +for a section will change the value of the location counter. +.Pp +.Em Input Section Description +.Pp +The most common output section command is an input section description. +.Pp +The input section description is the most basic linker script operation. You +use output sections to tell the linker how to lay out your program in memory. +You use input section descriptions to tell the linker how to map the input +files into your memory layout. +.Pp +.No Input Section Basics +.Pp +An input section description consists of a file name optionally followed by +a list of section names in parentheses. +.Pp +The file name and the section name may be wildcard patterns, which we describe +further below (see Section +.Dq Input Section Wildcards ) . +.Pp +The most common input section description is to include all input sections +with a particular name in the output section. For example, to include all +input +.Li .text +sections, you would write: +.Bd -literal -offset indent +*(.text) +.Ed +Here the +.Li * +is a wildcard which matches any file name. To exclude a list of files from +matching the file name wildcard, EXCLUDE_FILE may be used to match all files +except the ones specified in the EXCLUDE_FILE list. For example: +.Bd -literal -offset indent +(*(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors)) +.Ed +will cause all .ctors sections from all files except +.Pa crtend.o +and +.Pa otherfile.o +to be included. +.Pp +There are two ways to include more than one section: +.Bd -literal -offset indent +*(.text .rdata) +*(.text) *(.rdata) +.Ed +The difference between these is the order in which the +.Li .text +and +.Li .rdata +input sections will appear in the output section. In the first example, they +will be intermingled, appearing in the same order as they are found in the +linker input. In the second example, all +.Li .text +input sections will appear first, followed by all +.Li .rdata +input sections. +.Pp +You can specify a file name to include sections from a particular file. You +would do this if one or more of your files contain special data that needs +to be at a particular location in memory. For example: +.Bd -literal -offset indent +data.o(.data) +.Ed +.Pp +If you use a file name without a list of sections, then all sections in the +input file will be included in the output section. This is not commonly done, +but it may by useful on occasion. For example: +.Bd -literal -offset indent +data.o +.Ed +.Pp +When you use a file name which does not contain any wild card characters, +the linker will first see if you also specified the file name on the linker +command line or in an +.Li INPUT +command. If you did not, the linker will attempt to open the file as an input +file, as though it appeared on the command line. Note that this differs from +an +.Li INPUT +command, because the linker will not search for the file in the archive search +path. +.Pp +.No Input Section Wildcard Patterns +.Pp +In an input section description, either the file name or the section name +or both may be wildcard patterns. +.Pp +The file name of +.Li * +seen in many examples is a simple wildcard pattern for the file name. +.Pp +The wildcard patterns are like those used by the Unix shell. +.Pp +.Bl -tag -width Ds +.It * +matches any number of characters +.It ? +matches any single character +.It [ Va chars] +matches a single instance of any of the +.Va chars ; +the +.Li - +character may be used to specify a range of characters, as in +.Li [a-z] +to match any lower case letter +.It \e +quotes the following character +.El +.Pp +When a file name is matched with a wildcard, the wildcard characters will +not match a +.Li / +character (used to separate directory names on Unix). A pattern consisting +of a single +.Li * +character is an exception; it will always match any file name, whether it +contains a +.Li / +or not. In a section name, the wildcard characters will match a +.Li / +character. +.Pp +File name wildcard patterns only match files which are explicitly specified +on the command line or in an +.Li INPUT +command. The linker does not search directories to expand wildcards. +.Pp +If a file name matches more than one wildcard pattern, or if a file name appears +explicitly and is also matched by a wildcard pattern, the linker will use +the first match in the linker script. For example, this sequence of input +section descriptions is probably in error, because the +.Pa data.o +rule will not be used: +.Bd -literal -offset indent +\&.data : { *(.data) } +\&.data1 : { data.o(.data) } +.Ed +.Pp +Normally, the linker will place files and sections matched by wildcards in +the order in which they are seen during the link. You can change this by using +the +.Li SORT_BY_NAME +keyword, which appears before a wildcard pattern in parentheses (e.g., +.Li SORT_BY_NAME(.text*) ) . +When the +.Li SORT_BY_NAME +keyword is used, the linker will sort the files or sections into ascending +order by name before placing them in the output file. +.Pp +.Li SORT_BY_ALIGNMENT +is very similar to +.Li SORT_BY_NAME . +The difference is +.Li SORT_BY_ALIGNMENT +will sort sections into ascending order by alignment before placing them in +the output file. +.Pp +.Li SORT +is an alias for +.Li SORT_BY_NAME . +.Pp +When there are nested section sorting commands in linker script, there can +be at most 1 level of nesting for section sorting commands. +.Pp +.Bl -enum +.It +.Li SORT_BY_NAME +( +.Li SORT_BY_ALIGNMENT +(wildcard section pattern)). It will sort the input sections by name first, +then by alignment if 2 sections have the same name. +.It +.Li SORT_BY_ALIGNMENT +( +.Li SORT_BY_NAME +(wildcard section pattern)). It will sort the input sections by alignment +first, then by name if 2 sections have the same alignment. +.It +.Li SORT_BY_NAME +( +.Li SORT_BY_NAME +(wildcard section pattern)) is treated the same as +.Li SORT_BY_NAME +(wildcard section pattern). +.It +.Li SORT_BY_ALIGNMENT +( +.Li SORT_BY_ALIGNMENT +(wildcard section pattern)) is treated the same as +.Li SORT_BY_ALIGNMENT +(wildcard section pattern). +.It +All other nested section sorting commands are invalid. +.El +.Pp +When both command line section sorting option and linker script section sorting +command are used, section sorting command always takes precedence over the +command line option. +.Pp +If the section sorting command in linker script isn't nested, the command +line option will make the section sorting command to be treated as nested +sorting command. +.Pp +.Bl -enum +.It +.Li SORT_BY_NAME +(wildcard section pattern ) with +.Op --sort-sections alignment +is equivalent to +.Li SORT_BY_NAME +( +.Li SORT_BY_ALIGNMENT +(wildcard section pattern)). +.It +.Li SORT_BY_ALIGNMENT +(wildcard section pattern) with +.Op --sort-section name +is equivalent to +.Li SORT_BY_ALIGNMENT +( +.Li SORT_BY_NAME +(wildcard section pattern)). +.El +.Pp +If the section sorting command in linker script is nested, the command line +option will be ignored. +.Pp +If you ever get confused about where input sections are going, use the +.Li -M +linker option to generate a map file. The map file shows precisely how input +sections are mapped to output sections. +.Pp +This example shows how wildcard patterns might be used to partition files. +This linker script directs the linker to place all +.Li .text +sections in +.Li .text +and all +.Li .bss +sections in +.Li .bss . +The linker will place the +.Li .data +section from all files beginning with an upper case character in +.Li .DATA ; +for all other files, the linker will place the +.Li .data +section in +.Li .data . +.Bd -literal -offset indent + +SECTIONS { + .text : { *(.text) } + .DATA : { [A-Z]*(.data) } + .data : { *(.data) } + .bss : { *(.bss) } +} + +.Ed +.Pp +.No Input Section for Common Symbols +.Pp +A special notation is needed for common symbols, because in many object file +formats common symbols do not have a particular input section. The linker +treats common symbols as though they are in an input section named +.Li COMMON . +.Pp +You may use file names with the +.Li COMMON +section just as with any other input sections. You can use this to place common +symbols from a particular input file in one section while common symbols from +other input files are placed in another section. +.Pp +In most cases, common symbols in input files will be placed in the +.Li .bss +section in the output file. For example: +.Bd -literal -offset indent +\&.bss { *(.bss) *(COMMON) } +.Ed +.Pp +Some object file formats have more than one type of common symbol. For example, +the MIPS ELF object file format distinguishes standard common symbols and +small common symbols. In this case, the linker will use a different special +section name for other types of common symbols. In the case of MIPS ELF, the +linker uses +.Li COMMON +for standard common symbols and +.Li .scommon +for small common symbols. This permits you to map the different types of common +symbols into memory at different locations. +.Pp +You will sometimes see +.Li [COMMON] +in old linker scripts. This notation is now considered obsolete. It is equivalent +to +.Li *(COMMON) . +.Pp +.No Input Section and Garbage Collection +.Pp +When link-time garbage collection is in use ( +.Li --gc-sections ) , +it is often useful to mark sections that should not be eliminated. This is +accomplished by surrounding an input section's wildcard entry with +.Li KEEP() , +as in +.Li KEEP(*(.init)) +or +.Li KEEP(SORT_BY_NAME(*)(.ctors)) . +.Pp +.No Input Section Example +.Pp +The following example is a complete linker script. It tells the linker to +read all of the sections from file +.Pa all.o +and place them at the start of output section +.Li outputa +which starts at location +.Li 0x10000 . +All of section +.Li .input1 +from file +.Pa foo.o +follows immediately, in the same output section. All of section +.Li .input2 +from +.Pa foo.o +goes into output section +.Li outputb , +followed by section +.Li .input1 +from +.Pa foo1.o . +All of the remaining +.Li .input1 +and +.Li .input2 +sections from any files are written to output section +.Li outputc . +.Pp +.Bd -literal -offset indent + +SECTIONS { + outputa 0x10000 : + { + all.o + foo.o (.input1) + } + + + outputb : + { + foo.o (.input2) + foo1.o (.input1) + } + + + outputc : + { + *(.input1) + *(.input2) + } +} + +.Ed +.Pp +.Em Output Section Data +.Pp +You can include explicit bytes of data in an output section by using +.Li BYTE , +.Li SHORT , +.Li LONG , +.Li QUAD , +or +.Li SQUAD +as an output section command. Each keyword is followed by an expression in +parentheses providing the value to store (see Section +.Dq Expressions ) . +The value of the expression is stored at the current value of the location +counter. +.Pp +The +.Li BYTE , +.Li SHORT , +.Li LONG , +and +.Li QUAD +commands store one, two, four, and eight bytes (respectively). After storing +the bytes, the location counter is incremented by the number of bytes stored. +.Pp +For example, this will store the byte 1 followed by the four byte value of +the symbol +.Li addr : +.Bd -literal -offset indent +BYTE(1) +LONG(addr) +.Ed +.Pp +When using a 64 bit host or target, +.Li QUAD +and +.Li SQUAD +are the same; they both store an 8 byte, or 64 bit, value. When both host +and target are 32 bits, an expression is computed as 32 bits. In this case +.Li QUAD +stores a 32 bit value zero extended to 64 bits, and +.Li SQUAD +stores a 32 bit value sign extended to 64 bits. +.Pp +If the object file format of the output file has an explicit endianness, which +is the normal case, the value will be stored in that endianness. When the +object file format does not have an explicit endianness, as is true of, for +example, S-records, the value will be stored in the endianness of the first +input object file. +.Pp +Note---these commands only work inside a section description and not between +them, so the following will produce an error from the linker: +.Bd -literal -offset indent +SECTIONS { .text : { *(.text) } LONG(1) .data : { *(.data) } } +.Ed +whereas this will work: +.Bd -literal -offset indent +SECTIONS { .text : { *(.text) ; LONG(1) } .data : { *(.data) } } +.Ed +.Pp +You may use the +.Li FILL +command to set the fill pattern for the current section. It is followed by +an expression in parentheses. Any otherwise unspecified regions of memory +within the section (for example, gaps left due to the required alignment of +input sections) are filled with the value of the expression, repeated as necessary. +A +.Li FILL +statement covers memory locations after the point at which it occurs in the +section definition; by including more than one +.Li FILL +statement, you can have different fill patterns in different parts of an output +section. +.Pp +This example shows how to fill unspecified regions of memory with the value +.Li 0x90 : +.Bd -literal -offset indent +FILL(0x90909090) +.Ed +.Pp +The +.Li FILL +command is similar to the +.Li = Va fillexp +output section attribute, but it only affects the part of the section following +the +.Li FILL +command, rather than the entire section. If both are used, the +.Li FILL +command takes precedence.See Section +.Dq Output Section Fill , +for details on the fill expression. +.Pp +.Em Output Section Keywords +.Pp +There are a couple of keywords which can appear as output section commands. +.Pp +.Bl -tag -width Ds +.It CREATE_OBJECT_SYMBOLS +The command tells the linker to create a symbol for each input file. The name +of each symbol will be the name of the corresponding input file. The section +of each symbol will be the output section in which the +.Li CREATE_OBJECT_SYMBOLS +command appears. +.Pp +This is conventional for the a.out object file format. It is not normally +used for any other object file format. +.Pp +.It CONSTRUCTORS +When linking using the a.out object file format, the linker uses an unusual +set construct to support C++ global constructors and destructors. When linking +object file formats which do not support arbitrary sections, such as ECOFF +and XCOFF, the linker will automatically recognize C++ global constructors +and destructors by name. For these object file formats, the +.Li CONSTRUCTORS +command tells the linker to place constructor information in the output section +where the +.Li CONSTRUCTORS +command appears. The +.Li CONSTRUCTORS +command is ignored for other object file formats. +.Pp +The symbol +.Li __CTOR_LIST__ +marks the start of the global constructors, and the symbol +.Li __CTOR_END__ +marks the end. Similarly, +.Li __DTOR_LIST__ +and +.Li __DTOR_END__ +mark the start and end of the global destructors. The first word in the list +is the number of entries, followed by the address of each constructor or destructor, +followed by a zero word. The compiler must arrange to actually run the code. +For these object file formats GNU C++ normally calls constructors from a subroutine +.Li __main ; +a call to +.Li __main +is automatically inserted into the startup code for +.Li main . +GNU C++ normally runs destructors either by using +.Li atexit , +or directly from the function +.Li exit . +.Pp +For object file formats such as +.Li COFF +or +.Li ELF +which support arbitrary section names, GNU C++ will normally arrange to put +the addresses of global constructors and destructors into the +.Li .ctors +and +.Li .dtors +sections. Placing the following sequence into your linker script will build +the sort of table which the GNU C++ runtime code expects to see. +.Pp +.Bd -literal -offset indent + __CTOR_LIST__ = .; + LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2) + *(.ctors) + LONG(0) + __CTOR_END__ = .; + __DTOR_LIST__ = .; + LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2) + *(.dtors) + LONG(0) + __DTOR_END__ = .; +.Ed +.Pp +If you are using the GNU C++ support for initialization priority, which provides +some control over the order in which global constructors are run, you must +sort the constructors at link time to ensure that they are executed in the +correct order. When using the +.Li CONSTRUCTORS +command, use +.Li SORT_BY_NAME(CONSTRUCTORS) +instead. When using the +.Li .ctors +and +.Li .dtors +sections, use +.Li *(SORT_BY_NAME(.ctors)) +and +.Li *(SORT_BY_NAME(.dtors)) +instead of just +.Li *(.ctors) +and +.Li *(.dtors) . +.Pp +Normally the compiler and linker will handle these issues automatically, and +you will not need to concern yourself with them. However, you may need to +consider this if you are using C++ and writing your own linker scripts. +.Pp +.El +.Em Output Section Discarding +.Pp +The linker will not create output sections with no contents. This is for convenience +when referring to input sections that may or may not be present in any of +the input files. For example: +.Bd -literal -offset indent +\&.foo : { *(.foo) } +.Ed +will only create a +.Li .foo +section in the output file if there is a +.Li .foo +section in at least one input file, and if the input sections are not all +empty. Other link script directives that allocate space in an output section +will also create the output section. +.Pp +The linker will ignore address assignments (see Section +.Dq Output Section Address ) +on discarded output sections, except when the linker script defines symbols +in the output section. In that case the linker will obey the address assignments, +possibly advancing dot even though the section is discarded. +.Pp +The special output section name +.Li /DISCARD/ +may be used to discard input sections. Any input sections which are assigned +to an output section named +.Li /DISCARD/ +are not included in the output file. +.Pp +.Em Output Section Attributes +.Pp +We showed above that the full description of an output section looked like +this: +.Bd -literal -offset indent + +section [address] [(type)] : + [AT(lma)] [ALIGN(section_align)] [SUBALIGN(subsection_align)] + { + output-section-command + output-section-command + ... + } [>region] [AT>lma_region] [:phdr :phdr ...] [=fillexp] + +.Ed +We've already described +.Va section , +.Va address , +and +.Va output-section-command . +In this section we will describe the remaining section attributes. +.Pp +.No Output Section Type +.Pp +Each output section may have a type. The type is a keyword in parentheses. +The following types are defined: +.Pp +.Bl -tag -width Ds +.It NOLOAD +The section should be marked as not loadable, so that it will not be loaded +into memory when the program is run. +.It DSECT +.It COPY +.It INFO +.It OVERLAY +These type names are supported for backward compatibility, and are rarely +used. They all have the same effect: the section should be marked as not allocatable, +so that no memory is allocated for the section when the program is run. +.El +.Pp +The linker normally sets the attributes of an output section based on the +input sections which map into it. You can override this by using the section +type. For example, in the script sample below, the +.Li ROM +section is addressed at memory location +.Li 0 +and does not need to be loaded when the program is run. The contents of the +.Li ROM +section will appear in the linker output file as usual. +.Bd -literal -offset indent + +SECTIONS { + ROM 0 (NOLOAD) : { ... } + ... +} + +.Ed +.Pp +.No Output Section LMA +.Pp +Every section has a virtual address (VMA) and a load address (LMA); see Basic +Script Concepts. The address expression which may appear in an output section +description sets the VMA (see Section +.Dq Output Section Address ) . +.Pp +The expression +.Va lma +that follows the +.Li AT +keyword specifies the load address of the section. +.Pp +Alternatively, with +.Li AT> Va lma_region +expression, you may specify a memory region for the section's load address.See Section +.Dq MEMORY . +Note that if the section has not had a VMA assigned to it then the linker +will use the +.Va lma_region +as the VMA region as well. +.Pp +If neither +.Li AT +nor +.Li AT> +is specified for an allocatable section, the linker will set the LMA such +that the difference between VMA and LMA for the section is the same as the +preceding output section in the same region. If there is no preceding output +section or the section is not allocatable, the linker will set the LMA equal +to the VMA.See Section +.Dq Output Section Region . +.Pp +This feature is designed to make it easy to build a ROM image. For example, +the following linker script creates three output sections: one called +.Li .text , +which starts at +.Li 0x1000 , +one called +.Li .mdata , +which is loaded at the end of the +.Li .text +section even though its VMA is +.Li 0x2000 , +and one called +.Li .bss +to hold uninitialized data at address +.Li 0x3000 . +The symbol +.Li _data +is defined with the value +.Li 0x2000 , +which shows that the location counter holds the VMA value, not the LMA value. +.Pp +.Bd -literal -offset indent + +SECTIONS + { + .text 0x1000 : { *(.text) _etext = . ; } + .mdata 0x2000 : + AT ( ADDR (.text) + SIZEOF (.text) ) + { _data = . ; *(.data); _edata = . ; } + .bss 0x3000 : + { _bstart = . ; *(.bss) *(COMMON) ; _bend = . ;} +} + +.Ed +.Pp +The run-time initialization code for use with a program generated with this +linker script would include something like the following, to copy the initialized +data from the ROM image to its runtime address. Notice how this code takes +advantage of the symbols defined by the linker script. +.Pp +.Bd -literal -offset indent + +extern char _etext, _data, _edata, _bstart, _bend; +char *src = &_etext; +char *dst = &_data; + +/* ROM has data at end of text; copy it. */ +while (dst < &_edata) { + *dst++ = *src++; +} + +/* Zero bss */ +for (dst = &_bstart; dst< &_bend; dst++) + *dst = 0; + +.Ed +.Pp +.No Forced Output Alignment +.Pp +You can increase an output section's alignment by using ALIGN. +.Pp +.No Forced Input Alignment +.Pp +You can force input section alignment within an output section by using SUBALIGN. +The value specified overrides any alignment given by input sections, whether +larger or smaller. +.Pp +.No Output Section Region +.Pp +You can assign a section to a previously defined region of memory by using +.Li > Va region . +See Section.Dq MEMORY . +.Pp +Here is a simple example: +.Bd -literal -offset indent + +MEMORY { rom : ORIGIN = 0x1000, LENGTH = 0x1000 } +SECTIONS { ROM : { *(.text) } >rom } + +.Ed +.Pp +.No Output Section Phdr +.Pp +You can assign a section to a previously defined program segment by using +.Li : Va phdr . +See Section.Dq PHDRS . +If a section is assigned to one or more segments, then all subsequent allocated +sections will be assigned to those segments as well, unless they use an explicitly +.Li : Va phdr +modifier. You can use +.Li :NONE +to tell the linker to not put the section in any segment at all. +.Pp +Here is a simple example: +.Bd -literal -offset indent + +PHDRS { text PT_LOAD ; } +SECTIONS { .text : { *(.text) } :text } + +.Ed +.Pp +.No Output Section Fill +.Pp +You can set the fill pattern for an entire section by using +.Li = Va fillexp . +.Va fillexp +is an expression (see Section +.Dq Expressions ) . +Any otherwise unspecified regions of memory within the output section (for +example, gaps left due to the required alignment of input sections) will be +filled with the value, repeated as necessary. If the fill expression is a +simple hex number, ie. a string of hex digit starting with +.Li 0x +and without a trailing +.Li k +or +.Li M , +then an arbitrarily long sequence of hex digits can be used to specify the +fill pattern; Leading zeros become part of the pattern too. For all other +cases, including extra parentheses or a unary +.Li + , +the fill pattern is the four least significant bytes of the value of the expression. +In all cases, the number is big-endian. +.Pp +You can also change the fill value with a +.Li FILL +command in the output section commands; (see Section +.Dq Output Section Data ) . +.Pp +Here is a simple example: +.Bd -literal -offset indent + +SECTIONS { .text : { *(.text) } =0x90909090 } + +.Ed +.Pp +.Em Overlay Description +.Pp +An overlay description provides an easy way to describe sections which are +to be loaded as part of a single memory image but are to be run at the same +memory address. At run time, some sort of overlay manager will copy the overlaid +sections in and out of the runtime memory address as required, perhaps by +simply manipulating addressing bits. This approach can be useful, for example, +when a certain region of memory is faster than another. +.Pp +Overlays are described using the +.Li OVERLAY +command. The +.Li OVERLAY +command is used within a +.Li SECTIONS +command, like an output section description. The full syntax of the +.Li OVERLAY +command is as follows: +.Bd -literal -offset indent + +OVERLAY [start] : [NOCROSSREFS] [AT ( ldaddr )] + { + secname1 + { + output-section-command + output-section-command + ... + } [:phdr...] [=fill] + secname2 + { + output-section-command + output-section-command + ... + } [:phdr...] [=fill] + ... + } [>region] [:phdr...] [=fill] + +.Ed +.Pp +Everything is optional except +.Li OVERLAY +(a keyword), and each section must have a name ( +.Va secname1 +and +.Va secname2 +above). The section definitions within the +.Li OVERLAY +construct are identical to those within the general +.Li SECTIONS +contruct (see Section +.Dq SECTIONS ) , +except that no addresses and no memory regions may be defined for sections +within an +.Li OVERLAY . +.Pp +The sections are all defined with the same starting address. The load addresses +of the sections are arranged such that they are consecutive in memory starting +at the load address used for the +.Li OVERLAY +as a whole (as with normal section definitions, the load address is optional, +and defaults to the start address; the start address is also optional, and +defaults to the current value of the location counter). +.Pp +If the +.Li NOCROSSREFS +keyword is used, and there any references among the sections, the linker will +report an error. Since the sections all run at the same address, it normally +does not make sense for one section to refer directly to another.See Section +.Dq Miscellaneous Commands . +.Pp +For each section within the +.Li OVERLAY , +the linker automatically provides two symbols. The symbol +.Li __load_start_ Va secname +is defined as the starting load address of the section. The symbol +.Li __load_stop_ Va secname +is defined as the final load address of the section. Any characters within +.Va secname +which are not legal within C identifiers are removed. C (or assembler) code +may use these symbols to move the overlaid sections around as necessary. +.Pp +At the end of the overlay, the value of the location counter is set to the +start address of the overlay plus the size of the largest section. +.Pp +Here is an example. Remember that this would appear inside a +.Li SECTIONS +construct. +.Bd -literal -offset indent + + OVERLAY 0x1000 : AT (0x4000) + { + .text0 { o1/*.o(.text) } + .text1 { o2/*.o(.text) } + } + +.Ed +This will define both +.Li .text0 +and +.Li .text1 +to start at address 0x1000. +.Li .text0 +will be loaded at address 0x4000, and +.Li .text1 +will be loaded immediately after +.Li .text0 . +The following symbols will be defined if referenced: +.Li __load_start_text0 , +.Li __load_stop_text0 , +.Li __load_start_text1 , +.Li __load_stop_text1 . +.Pp +C code to copy overlay +.Li .text1 +into the overlay area might look like the following. +.Pp +.Bd -literal -offset indent + + extern char __load_start_text1, __load_stop_text1; + memcpy ((char *) 0x1000, &__load_start_text1, + &__load_stop_text1 - &__load_start_text1); + +.Ed +.Pp +Note that the +.Li OVERLAY +command is just syntactic sugar, since everything it does can be done using +the more basic commands. The above example could have been written identically +as follows. +.Pp +.Bd -literal -offset indent + + .text0 0x1000 : AT (0x4000) { o1/*.o(.text) } + PROVIDE (__load_start_text0 = LOADADDR (.text0)); + PROVIDE (__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0)); + .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) { o2/*.o(.text) } + PROVIDE (__load_start_text1 = LOADADDR (.text1)); + PROVIDE (__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1)); + . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1)); + +.Ed +.Pp +.Ss MEMORY Command +The linker's default configuration permits allocation of all available memory. +You can override this by using the +.Li MEMORY +command. +.Pp +The +.Li MEMORY +command describes the location and size of blocks of memory in the target. +You can use it to describe which memory regions may be used by the linker, +and which memory regions it must avoid. You can then assign sections to particular +memory regions. The linker will set section addresses based on the memory +regions, and will warn about regions that become too full. The linker will +not shuffle sections around to fit into the available regions. +.Pp +A linker script may contain at most one use of the +.Li MEMORY +command. However, you can define as many blocks of memory within it as you +wish. The syntax is: +.Bd -literal -offset indent + +MEMORY + { + name [(attr)] : ORIGIN = origin, LENGTH = len + ... + } + +.Ed +.Pp +The +.Va name +is a name used in the linker script to refer to the region. The region name +has no meaning outside of the linker script. Region names are stored in a +separate name space, and will not conflict with symbol names, file names, +or section names. Each memory region must have a distinct name. +.Pp +The +.Va attr +string is an optional list of attributes that specify whether to use a particular +memory region for an input section which is not explicitly mapped in the linker +script. As described in SECTIONS, if you do not specify an output section +for some input section, the linker will create an output section with the +same name as the input section. If you define region attributes, the linker +will use them to select the memory region for the output section that it creates. +.Pp +The +.Va attr +string must consist only of the following characters: +.Bl -tag -width Ds +.It R +Read-only section +.It W +Read/write section +.It X +Executable section +.It A +Allocatable section +.It I +Initialized section +.It L +Same as +.Li I +.It ! +Invert the sense of any of the preceding attributes +.El +.Pp +If a unmapped section matches any of the listed attributes other than +.Li ! , +it will be placed in the memory region. The +.Li ! +attribute reverses this test, so that an unmapped section will be placed in +the memory region only if it does not match any of the listed attributes. +.Pp +The +.Va origin +is an numerical expression for the start address of the memory region. The +expression must evaluate to a constant and it cannot involve any symbols. +The keyword +.Li ORIGIN +may be abbreviated to +.Li org +or +.Li o +(but not, for example, +.Li ORG ) . +.Pp +The +.Va len +is an expression for the size in bytes of the memory region. As with the +.Va origin +expression, the expression must be numerical only and must evaluate to a constant. +The keyword +.Li LENGTH +may be abbreviated to +.Li len +or +.Li l . +.Pp +In the following example, we specify that there are two memory regions available +for allocation: one starting at +.Li 0 +for 256 kilobytes, and the other starting at +.Li 0x40000000 +for four megabytes. The linker will place into the +.Li rom +memory region every section which is not explicitly mapped into a memory region, +and is either read-only or executable. The linker will place other sections +which are not explicitly mapped into a memory region into the +.Li ram +memory region. +.Pp +.Bd -literal -offset indent + +MEMORY + { + rom (rx) : ORIGIN = 0, LENGTH = 256K + ram (!rx) : org = 0x40000000, l = 4M + } + +.Ed +.Pp +Once you define a memory region, you can direct the linker to place specific +output sections into that memory region by using the +.Li > Va region +output section attribute. For example, if you have a memory region named +.Li mem , +you would use +.Li >mem +in the output section definition.See Section +.Dq Output Section Region . +If no address was specified for the output section, the linker will set the +address to the next available address within the memory region. If the combined +output sections directed to a memory region are too large for the region, +the linker will issue an error message. +.Pp +It is possible to access the origin and length of a memory in an expression +via the +.Li ORIGIN( Va memory) +and +.Li LENGTH( Va memory) +functions: +.Pp +.Bd -literal -offset indent + + _fstack = ORIGIN(ram) + LENGTH(ram) - 4; + +.Ed +.Pp +.Ss PHDRS Command +The ELF object file format uses +.Em program headers , +also knows as +.Em segments . +The program headers describe how the program should be loaded into memory. +You can print them out by using the +.Li objdump +program with the +.Li -p +option. +.Pp +When you run an ELF program on a native ELF system, the system loader reads +the program headers in order to figure out how to load the program. This will +only work if the program headers are set correctly. This manual does not describe +the details of how the system loader interprets program headers; for more +information, see the ELF ABI. +.Pp +The linker will create reasonable program headers by default. However, in +some cases, you may need to specify the program headers more precisely. You +may use the +.Li PHDRS +command for this purpose. When the linker sees the +.Li PHDRS +command in the linker script, it will not create any program headers other +than the ones specified. +.Pp +The linker only pays attention to the +.Li PHDRS +command when generating an ELF output file. In other cases, the linker will +simply ignore +.Li PHDRS . +.Pp +This is the syntax of the +.Li PHDRS +command. The words +.Li PHDRS , +.Li FILEHDR , +.Li AT , +and +.Li FLAGS +are keywords. +.Pp +.Bd -literal -offset indent + +PHDRS +{ + name type [ FILEHDR ] [ PHDRS ] [ AT ( address ) ] + [ FLAGS ( flags ) ] ; +} + +.Ed +.Pp +The +.Va name +is used only for reference in the +.Li SECTIONS +command of the linker script. It is not put into the output file. Program +header names are stored in a separate name space, and will not conflict with +symbol names, file names, or section names. Each program header must have +a distinct name. +.Pp +Certain program header types describe segments of memory which the system +loader will load from the file. In the linker script, you specify the contents +of these segments by placing allocatable output sections in the segments. +You use the +.Li : Va phdr +output section attribute to place a section in a particular segment.See Section +.Dq Output Section Phdr . +.Pp +It is normal to put certain sections in more than one segment. This merely +implies that one segment of memory contains another. You may repeat +.Li : Va phdr , +using it once for each segment which should contain the section. +.Pp +If you place a section in one or more segments using +.Li : Va phdr , +then the linker will place all subsequent allocatable sections which do not +specify +.Li : Va phdr +in the same segments. This is for convenience, since generally a whole set +of contiguous sections will be placed in a single segment. You can use +.Li :NONE +to override the default segment and tell the linker to not put the section +in any segment at all. +.Pp +You may use the +.Li FILEHDR +and +.Li PHDRS +keywords appear after the program header type to further describe the contents +of the segment. The +.Li FILEHDR +keyword means that the segment should include the ELF file header. The +.Li PHDRS +keyword means that the segment should include the ELF program headers themselves. +.Pp +The +.Va type +may be one of the following. The numbers indicate the value of the keyword. +.Pp +.Bl -tag -width Ds +.It Li PT_NULL (0) +Indicates an unused program header. +.Pp +.It Li PT_LOAD (1) +Indicates that this program header describes a segment to be loaded from the +file. +.Pp +.It Li PT_DYNAMIC (2) +Indicates a segment where dynamic linking information can be found. +.Pp +.It Li PT_INTERP (3) +Indicates a segment where the name of the program interpreter may be found. +.Pp +.It Li PT_NOTE (4) +Indicates a segment holding note information. +.Pp +.It Li PT_SHLIB (5) +A reserved program header type, defined but not specified by the ELF ABI. +.Pp +.It Li PT_PHDR (6) +Indicates a segment where the program headers may be found. +.Pp +.It Va expression +An expression giving the numeric type of the program header. This may be used +for types not defined above. +.El +.Pp +You can specify that a segment should be loaded at a particular address in +memory by using an +.Li AT +expression. This is identical to the +.Li AT +command used as an output section attribute (see Section +.Dq Output Section LMA ) . +The +.Li AT +command for a program header overrides the output section attribute. +.Pp +The linker will normally set the segment flags based on the sections which +comprise the segment. You may use the +.Li FLAGS +keyword to explicitly specify the segment flags. The value of +.Va flags +must be an integer. It is used to set the +.Li p_flags +field of the program header. +.Pp +Here is an example of +.Li PHDRS . +This shows a typical set of program headers used on a native ELF system. +.Pp +.Bd -literal -offset indent + +PHDRS +{ + headers PT_PHDR PHDRS ; + interp PT_INTERP ; + text PT_LOAD FILEHDR PHDRS ; + data PT_LOAD ; + dynamic PT_DYNAMIC ; +} + +SECTIONS +{ + . = SIZEOF_HEADERS; + .interp : { *(.interp) } :text :interp + .text : { *(.text) } :text + .rodata : { *(.rodata) } /* defaults to :text */ + ... + . = . + 0x1000; /* move to a new page in memory */ + .data : { *(.data) } :data + .dynamic : { *(.dynamic) } :data :dynamic + ... +} + +.Ed +.Pp +.Ss VERSION Command +The linker supports symbol versions when using ELF. Symbol versions are only +useful when using shared libraries. The dynamic linker can use symbol versions +to select a specific version of a function when it runs a program that may +have been linked against an earlier version of the shared library. +.Pp +You can include a version script directly in the main linker script, or you +can supply the version script as an implicit linker script. You can also use +the +.Li --version-script +linker option. +.Pp +The syntax of the +.Li VERSION +command is simply +.Bd -literal -offset indent +VERSION { version-script-commands } +.Ed +.Pp +The format of the version script commands is identical to that used by Sun's +linker in Solaris 2.5. The version script defines a tree of version nodes. +You specify the node names and interdependencies in the version script. You +can specify which symbols are bound to which version nodes, and you can reduce +a specified set of symbols to local scope so that they are not globally visible +outside of the shared library. +.Pp +The easiest way to demonstrate the version script language is with a few examples. +.Pp +.Bd -literal -offset indent +VERS_1.1 { + global: + foo1; + local: + old*; + original*; + new*; +}; + +VERS_1.2 { + foo2; +} VERS_1.1; + +VERS_2.0 { + bar1; bar2; + extern "C++" { + ns::*; + "int f(int, double)"; + } +} VERS_1.2; +.Ed +.Pp +This example version script defines three version nodes. The first version +node defined is +.Li VERS_1.1 ; +it has no other dependencies. The script binds the symbol +.Li foo1 +to +.Li VERS_1.1 . +It reduces a number of symbols to local scope so that they are not visible +outside of the shared library; this is done using wildcard patterns, so that +any symbol whose name begins with +.Li old , +.Li original , +or +.Li new +is matched. The wildcard patterns available are the same as those used in +the shell when matching filenames (also known as \(lqglobbing\(rq). However, if you +specify the symbol name inside double quotes, then the name is treated as +literal, rather than as a glob pattern. +.Pp +Next, the version script defines node +.Li VERS_1.2 . +This node depends upon +.Li VERS_1.1 . +The script binds the symbol +.Li foo2 +to the version node +.Li VERS_1.2 . +.Pp +Finally, the version script defines node +.Li VERS_2.0 . +This node depends upon +.Li VERS_1.2 . +The scripts binds the symbols +.Li bar1 +and +.Li bar2 +are bound to the version node +.Li VERS_2.0 . +.Pp +When the linker finds a symbol defined in a library which is not specifically +bound to a version node, it will effectively bind it to an unspecified base +version of the library. You can bind all otherwise unspecified symbols to +a given version node by using +.Li global: *; +somewhere in the version script. +.Pp +The names of the version nodes have no specific meaning other than what they +might suggest to the person reading them. The +.Li 2.0 +version could just as well have appeared in between +.Li 1.1 +and +.Li 1.2 . +However, this would be a confusing way to write a version script. +.Pp +Node name can be omitted, provided it is the only version node in the version +script. Such version script doesn't assign any versions to symbols, only selects +which symbols will be globally visible out and which won't. +.Pp +.Bd -literal -offset indent +{ global: foo; bar; local: *; }; +.Ed +.Pp +When you link an application against a shared library that has versioned symbols, +the application itself knows which version of each symbol it requires, and +it also knows which version nodes it needs from each shared library it is +linked against. Thus at runtime, the dynamic loader can make a quick check +to make sure that the libraries you have linked against do in fact supply +all of the version nodes that the application will need to resolve all of +the dynamic symbols. In this way it is possible for the dynamic linker to +know with certainty that all external symbols that it needs will be resolvable +without having to search for each symbol reference. +.Pp +The symbol versioning is in effect a much more sophisticated way of doing +minor version checking that SunOS does. The fundamental problem that is being +addressed here is that typically references to external functions are bound +on an as-needed basis, and are not all bound when the application starts up. +If a shared library is out of date, a required interface may be missing; when +the application tries to use that interface, it may suddenly and unexpectedly +fail. With symbol versioning, the user will get a warning when they start +their program if the libraries being used with the application are too old. +.Pp +There are several GNU extensions to Sun's versioning approach. The first of +these is the ability to bind a symbol to a version node in the source file +where the symbol is defined instead of in the versioning script. This was +done mainly to reduce the burden on the library maintainer. You can do this +by putting something like: +.Bd -literal -offset indent +__asm__(".symver original_foo,foo@VERS_1.1"); +.Ed +in the C source file. This renames the function +.Li original_foo +to be an alias for +.Li foo +bound to the version node +.Li VERS_1.1 . +The +.Li local: +directive can be used to prevent the symbol +.Li original_foo +from being exported. A +.Li .symver +directive takes precedence over a version script. +.Pp +The second GNU extension is to allow multiple versions of the same function +to appear in a given shared library. In this way you can make an incompatible +change to an interface without increasing the major version number of the +shared library, while still allowing applications linked against the old interface +to continue to function. +.Pp +To do this, you must use multiple +.Li .symver +directives in the source file. Here is an example: +.Pp +.Bd -literal -offset indent +__asm__(".symver original_foo,foo@"); +__asm__(".symver old_foo,foo@VERS_1.1"); +__asm__(".symver old_foo1,foo@VERS_1.2"); +__asm__(".symver new_foo,foo@@VERS_2.0"); +.Ed +.Pp +In this example, +.Li foo@ +represents the symbol +.Li foo +bound to the unspecified base version of the symbol. The source file that +contains this example would define 4 C functions: +.Li original_foo , +.Li old_foo , +.Li old_foo1 , +and +.Li new_foo . +.Pp +When you have multiple definitions of a given symbol, there needs to be some +way to specify a default version to which external references to this symbol +will be bound. You can do this with the +.Li foo@@VERS_2.0 +type of +.Li .symver +directive. You can only declare one version of a symbol as the default in +this manner; otherwise you would effectively have multiple definitions of +the same symbol. +.Pp +If you wish to bind a reference to a specific version of the symbol within +the shared library, you can use the aliases of convenience (i.e., +.Li old_foo ) , +or you can use the +.Li .symver +directive to specifically bind to an external version of the function in question. +.Pp +You can also specify the language in the version script: +.Pp +.Bd -literal -offset indent +VERSION extern "lang" { version-script-commands } +.Ed +.Pp +The supported +.Li lang +s are +.Li C , +.Li C++ , +and +.Li Java . +The linker will iterate over the list of symbols at the link time and demangle +them according to +.Li lang +before matching them to the patterns specified in +.Li version-script-commands . +.Pp +Demangled names may contains spaces and other special characters. As described +above, you can use a glob pattern to match demangled names, or you can use +a double-quoted string to match the string exactly. In the latter case, be +aware that minor differences (such as differing whitespace) between the version +script and the demangler output will cause a mismatch. As the exact string +generated by the demangler might change in the future, even if the mangled +name does not, you should check that all of your version directives are behaving +as you expect when you upgrade. +.Pp +.Ss Expressions in Linker Scripts +The syntax for expressions in the linker script language is identical to that +of C expressions. All expressions are evaluated as integers. All expressions +are evaluated in the same size, which is 32 bits if both the host and target +are 32 bits, and is otherwise 64 bits. +.Pp +You can use and set symbol values in expressions. +.Pp +The linker defines several special purpose builtin functions for use in expressions. +.Pp +.Em Constants +.Pp +All constants are integers. +.Pp +As in C, the linker considers an integer beginning with +.Li 0 +to be octal, and an integer beginning with +.Li 0x +or +.Li 0X +to be hexadecimal. The linker considers other integers to be decimal. +.Pp +In addition, you can use the suffixes +.Li K +and +.Li M +to scale a constant by +.Li 1024 +or +.Li 1024*1024 +respectively. For example, the following all refer to the same quantity: +.Bd -literal -offset indent +_fourk_1 = 4K; +_fourk_2 = 4096; +_fourk_3 = 0x1000; +.Ed +.Pp +.Em Symbol Names +.Pp +Unless quoted, symbol names start with a letter, underscore, or period and +may include letters, digits, underscores, periods, and hyphens. Unquoted symbol +names must not conflict with any keywords. You can specify a symbol which +contains odd characters or has the same name as a keyword by surrounding the +symbol name in double quotes: +.Bd -literal -offset indent +"SECTION" = 9; +"with a space" = "also with a space" + 10; +.Ed +.Pp +Since symbols can contain many non-alphabetic characters, it is safest to +delimit symbols with spaces. For example, +.Li A-B +is one symbol, whereas +.Li A - B +is an expression involving subtraction. +.Pp +.Em Orphan Sections +.Pp +Orphan sections are sections present in the input files which are not explicitly +placed into the output file by the linker script. The linker will still copy +these sections into the output file, but it has to guess as to where they +should be placed. The linker uses a simple heuristic to do this. It attempts +to place orphan sections after non-orphan sections of the same attribute, +such as code vs data, loadable vs non-loadable, etc. If there is not enough +room to do this then it places at the end of the file. +.Pp +For ELF targets, the attribute of the section includes section type as well +as section flag. +.Pp +.Em The Location Counter +.Pp +The special linker variable +.Em dot +.Li . +always contains the current output location counter. Since the +.Li . +always refers to a location in an output section, it may only appear in an +expression within a +.Li SECTIONS +command. The +.Li . +symbol may appear anywhere that an ordinary symbol is allowed in an expression. +.Pp +Assigning a value to +.Li . +will cause the location counter to be moved. This may be used to create holes +in the output section. The location counter may not be moved backwards inside +an output section, and may not be moved backwards outside of an output section +if so doing creates areas with overlapping LMAs. +.Pp +.Bd -literal -offset indent +SECTIONS +{ + output : + { + file1(.text) + . = . + 1000; + file2(.text) + . += 1000; + file3(.text) + } = 0x12345678; +} +.Ed +In the previous example, the +.Li .text +section from +.Pa file1 +is located at the beginning of the output section +.Li output . +It is followed by a 1000 byte gap. Then the +.Li .text +section from +.Pa file2 +appears, also with a 1000 byte gap following before the +.Li .text +section from +.Pa file3 . +The notation +.Li = 0x12345678 +specifies what data to write in the gaps (see Section +.Dq Output Section Fill ) . +.Pp +Note: +.Li . +actually refers to the byte offset from the start of the current containing +object. Normally this is the +.Li SECTIONS +statement, whose start address is 0, hence +.Li . +can be used as an absolute address. If +.Li . +is used inside a section description however, it refers to the byte offset +from the start of that section, not an absolute address. Thus in a script +like this: +.Pp +.Bd -literal -offset indent +SECTIONS +{ + . = 0x100 + .text: { + *(.text) + . = 0x200 + } + . = 0x500 + .data: { + *(.data) + . += 0x600 + } +} +.Ed +.Pp +The +.Li .text +section will be assigned a starting address of 0x100 and a size of exactly +0x200 bytes, even if there is not enough data in the +.Li .text +input sections to fill this area. (If there is too much data, an error will +be produced because this would be an attempt to move +.Li . +backwards). The +.Li .data +section will start at 0x500 and it will have an extra 0x600 bytes worth of +space after the end of the values from the +.Li .data +input sections and before the end of the +.Li .data +output section itself. +.Pp +Setting symbols to the value of the location counter outside of an output +section statement can result in unexpected values if the linker needs to place +orphan sections. For example, given the following: +.Pp +.Bd -literal -offset indent +SECTIONS +{ + start_of_text = . ; + .text: { *(.text) } + end_of_text = . ; + + start_of_data = . ; + .data: { *(.data) } + end_of_data = . ; +} +.Ed +.Pp +If the linker needs to place some input section, e.g. +.Li .rodata , +not mentioned in the script, it might choose to place that section between +.Li .text +and +.Li .data . +You might think the linker should place +.Li .rodata +on the blank line in the above script, but blank lines are of no particular +significance to the linker. As well, the linker doesn't associate the above +symbol names with their sections. Instead, it assumes that all assignments +or other statements belong to the previous output section, except for the +special case of an assignment to +.Li . . +I.e., the linker will place the orphan +.Li .rodata +section as if the script was written as follows: +.Pp +.Bd -literal -offset indent +SECTIONS +{ + start_of_text = . ; + .text: { *(.text) } + end_of_text = . ; + + start_of_data = . ; + .rodata: { *(.rodata) } + .data: { *(.data) } + end_of_data = . ; +} +.Ed +.Pp +This may or may not be the script author's intention for the value of +.Li start_of_data . +One way to influence the orphan section placement is to assign the location +counter to itself, as the linker assumes that an assignment to +.Li . +is setting the start address of a following output section and thus should +be grouped with that section. So you could write: +.Pp +.Bd -literal -offset indent +SECTIONS +{ + start_of_text = . ; + .text: { *(.text) } + end_of_text = . ; + + . = . ; + start_of_data = . ; + .data: { *(.data) } + end_of_data = . ; +} +.Ed +.Pp +Now, the orphan +.Li .rodata +section will be placed between +.Li end_of_text +and +.Li start_of_data . +.Pp +.Em Operators +.Pp +The linker recognizes the standard C set of arithmetic operators, with the +standard bindings and precedence levels: +.Bd -literal -offset indent +precedence associativity Operators Notes +(highest) +1 left ! - ~ (1) +2 left * / % +3 left + - +4 left >> << +5 left == != > < <= >= +6 left & +7 left | +8 left && +9 left || +10 right ? : +11 right &= += -= *= /= (2) +(lowest) +.Ed +Notes: (1) Prefix operators (2)See Section +.Dq Assignments . +.Pp +.Em Evaluation +.Pp +The linker evaluates expressions lazily. It only computes the value of an +expression when absolutely necessary. +.Pp +The linker needs some information, such as the value of the start address +of the first section, and the origins and lengths of memory regions, in order +to do any linking at all. These values are computed as soon as possible when +the linker reads in the linker script. +.Pp +However, other values (such as symbol values) are not known or needed until +after storage allocation. Such values are evaluated later, when other information +(such as the sizes of output sections) is available for use in the symbol +assignment expression. +.Pp +The sizes of sections cannot be known until after allocation, so assignments +dependent upon these are not performed until after allocation. +.Pp +Some expressions, such as those depending upon the location counter +.Li . , +must be evaluated during section allocation. +.Pp +If the result of an expression is required, but the value is not available, +then an error results. For example, a script like the following +.Bd -literal -offset indent + +SECTIONS + { + .text 9+this_isnt_constant : + { *(.text) } + } + +.Ed +will cause the error message +.Li non constant expression for initial address . +.Pp +.Em The Section of an Expression +.Pp +When the linker evaluates an expression, the result is either absolute or +relative to some section. A relative expression is expressed as a fixed offset +from the base of a section. +.Pp +The position of the expression within the linker script determines whether +it is absolute or relative. An expression which appears within an output section +definition is relative to the base of the output section. An expression which +appears elsewhere will be absolute. +.Pp +A symbol set to a relative expression will be relocatable if you request relocatable +output using the +.Li -r +option. That means that a further link operation may change the value of the +symbol. The symbol's section will be the section of the relative expression. +.Pp +A symbol set to an absolute expression will retain the same value through +any further link operation. The symbol will be absolute, and will not have +any particular associated section. +.Pp +You can use the builtin function +.Li ABSOLUTE +to force an expression to be absolute when it would otherwise be relative. +For example, to create an absolute symbol set to the address of the end of +the output section +.Li .data : +.Bd -literal -offset indent +SECTIONS + { + .data : { *(.data) _edata = ABSOLUTE(.); } + } +.Ed +If +.Li ABSOLUTE +were not used, +.Li _edata +would be relative to the +.Li .data +section. +.Pp +.Em Builtin Functions +.Pp +The linker script language includes a number of builtin functions for use +in linker script expressions. +.Pp +.Bl -tag -width Ds +.It ABSOLUTE( Va exp) +Return the absolute (non-relocatable, as opposed to non-negative) value of +the expression +.Va exp . +Primarily useful to assign an absolute value to a symbol within a section +definition, where symbol values are normally section relative.See Section +.Dq Expression Section . +.Pp +.It ADDR( Va section) +Return the absolute address (the VMA) of the named +.Va section . +Your script must previously have defined the location of that section. In +the following example, +.Li symbol_1 +and +.Li symbol_2 +are assigned identical values: +.Bd -literal -offset indent + +SECTIONS { ... + .output1 : + { + start_of_output_1 = ABSOLUTE(.); + ... + } + .output : + { + symbol_1 = ADDR(.output1); + symbol_2 = start_of_output_1; + } +\&... } + +.Ed +.Pp +.It ALIGN( Va align) +.It ALIGN( Va exp, Va align) +Return the location counter ( +.Li . ) +or arbitrary expression aligned to the next +.Va align +boundary. The single operand +.Li ALIGN +doesn't change the value of the location counter---it just does arithmetic +on it. The two operand +.Li ALIGN +allows an arbitrary expression to be aligned upwards ( +.Li ALIGN( Va align) +is equivalent to +.Li ALIGN(., Va align) ) . +.Pp +Here is an example which aligns the output +.Li .data +section to the next +.Li 0x2000 +byte boundary after the preceding section and sets a variable within the section +to the next +.Li 0x8000 +boundary after the input sections: +.Bd -literal -offset indent + +SECTIONS { ... + .data ALIGN(0x2000): { + *(.data) + variable = ALIGN(0x8000); + } +\&... } + +.Ed +The first use of +.Li ALIGN +in this example specifies the location of a section because it is used as +the optional +.Va address +attribute of a section definition (see Section +.Dq Output Section Address ) . +The second use of +.Li ALIGN +is used to defines the value of a symbol. +.Pp +The builtin function +.Li NEXT +is closely related to +.Li ALIGN . +.Pp +.It ALIGNOF( Va section) +Return the alignment in bytes of the named +.Va section , +if that section has been allocated. If the section has not been allocated +when this is evaluated, the linker will report an error. In the following +example, the alignment of the +.Li .output +section is stored as the first value in that section. +.Bd -literal -offset indent + +SECTIONS{ ... + .output { + LONG (ALIGNOF (.output)) + ... + } +\&... } + +.Ed +.Pp +.It BLOCK( Va exp) +This is a synonym for +.Li ALIGN , +for compatibility with older linker scripts. It is most often seen when setting +the address of an output section. +.Pp +.It DATA_SEGMENT_ALIGN( Va maxpagesize, Va commonpagesize) +This is equivalent to either +.Bd -literal -offset indent +(ALIGN(maxpagesize) + (. & (maxpagesize - 1))) +.Ed +or +.Bd -literal -offset indent +(ALIGN(maxpagesize) + (. & (maxpagesize - commonpagesize))) +.Ed +depending on whether the latter uses fewer +.Va commonpagesize +sized pages for the data segment (area between the result of this expression +and +.Li DATA_SEGMENT_END ) +than the former or not. If the latter form is used, it means +.Va commonpagesize +bytes of runtime memory will be saved at the expense of up to +.Va commonpagesize +wasted bytes in the on-disk file. +.Pp +This expression can only be used directly in +.Li SECTIONS +commands, not in any output section descriptions and only once in the linker +script. +.Va commonpagesize +should be less or equal to +.Va maxpagesize +and should be the system page size the object wants to be optimized for (while +still working on system page sizes up to +.Va maxpagesize ) . +.Pp +Example: +.Bd -literal -offset indent + . = DATA_SEGMENT_ALIGN(0x10000, 0x2000); +.Ed +.Pp +.It DATA_SEGMENT_END( Va exp) +This defines the end of data segment for +.Li DATA_SEGMENT_ALIGN +evaluation purposes. +.Pp +.Bd -literal -offset indent + . = DATA_SEGMENT_END(.); +.Ed +.Pp +.It DATA_SEGMENT_RELRO_END( Va offset, Va exp) +This defines the end of the +.Li PT_GNU_RELRO +segment when +.Li -z relro +option is used. Second argument is returned. When +.Li -z relro +option is not present, +.Li DATA_SEGMENT_RELRO_END +does nothing, otherwise +.Li DATA_SEGMENT_ALIGN +is padded so that +.Va exp ++ +.Va offset +is aligned to the most commonly used page boundary for particular target. +If present in the linker script, it must always come in between +.Li DATA_SEGMENT_ALIGN +and +.Li DATA_SEGMENT_END . +.Pp +.Bd -literal -offset indent + . = DATA_SEGMENT_RELRO_END(24, .); +.Ed +.Pp +.It DEFINED( Va symbol) +Return 1 if +.Va symbol +is in the linker global symbol table and is defined before the statement using +DEFINED in the script, otherwise return 0. You can use this function to provide +default values for symbols. For example, the following script fragment shows +how to set a global symbol +.Li begin +to the first location in the +.Li .text +section---but if a symbol called +.Li begin +already existed, its value is preserved: +.Pp +.Bd -literal -offset indent + +SECTIONS { ... + .text : { + begin = DEFINED(begin) ? begin : . ; + ... + } + ... +} + +.Ed +.Pp +.It LENGTH( Va memory) +Return the length of the memory region named +.Va memory . +.Pp +.It LOADADDR( Va section) +Return the absolute LMA of the named +.Va section . +This is normally the same as +.Li ADDR , +but it may be different if the +.Li AT +attribute is used in the output section definition (see Section +.Dq Output Section LMA ) . +.Pp +.It MAX( Va exp1, Va exp2) +Returns the maximum of +.Va exp1 +and +.Va exp2 . +.Pp +.It MIN( Va exp1, Va exp2) +Returns the minimum of +.Va exp1 +and +.Va exp2 . +.Pp +.It NEXT( Va exp) +Return the next unallocated address that is a multiple of +.Va exp . +This function is closely related to +.Li ALIGN( Va exp) ; +unless you use the +.Li MEMORY +command to define discontinuous memory for the output file, the two functions +are equivalent. +.Pp +.It ORIGIN( Va memory) +Return the origin of the memory region named +.Va memory . +.Pp +.It SEGMENT_START( Va segment, Va default) +Return the base address of the named +.Va segment . +If an explicit value has been given for this segment (with a command-line +.Li -T +option) that value will be returned; otherwise the value will be +.Va default . +At present, the +.Li -T +command-line option can only be used to set the base address for the \(lqtext\(rq, +\(lqdata\(rq, and \(lqbss\(rq sections, but you use +.Li SEGMENT_START +with any segment name. +.Pp +.It SIZEOF( Va section) +Return the size in bytes of the named +.Va section , +if that section has been allocated. If the section has not been allocated +when this is evaluated, the linker will report an error. In the following +example, +.Li symbol_1 +and +.Li symbol_2 +are assigned identical values: +.Bd -literal -offset indent + +SECTIONS{ ... + .output { + .start = . ; + ... + .end = . ; + } + symbol_1 = .end - .start ; + symbol_2 = SIZEOF(.output); +\&... } + +.Ed +.Pp +.It SIZEOF_HEADERS +.It sizeof_headers +Return the size in bytes of the output file's headers. This is information +which appears at the start of the output file. You can use this number when +setting the start address of the first section, if you choose, to facilitate +paging. +.Pp +When producing an ELF output file, if the linker script uses the +.Li SIZEOF_HEADERS +builtin function, the linker must compute the number of program headers before +it has determined all the section addresses and sizes. If the linker later +discovers that it needs additional program headers, it will report an error +.Li not enough room for program headers . +To avoid this error, you must avoid using the +.Li SIZEOF_HEADERS +function, or you must rework your linker script to avoid forcing the linker +to use additional program headers, or you must define the program headers +yourself using the +.Li PHDRS +command (see Section +.Dq PHDRS ) . +.El +.Pp +.Ss Implicit Linker Scripts +If you specify a linker input file which the linker can not recognize as an +object file or an archive file, it will try to read the file as a linker script. +If the file can not be parsed as a linker script, the linker will report an +error. +.Pp +An implicit linker script will not replace the default linker script. +.Pp +Typically an implicit linker script would contain only symbol assignments, +or the +.Li INPUT , +.Li GROUP , +or +.Li VERSION +commands. +.Pp +Any input files read because of an implicit linker script will be read at +the position in the command line where the implicit linker script was read. +This can affect archive searching. +.Pp +.Sh Machine Dependent Features +.Xr ld +has additional features on some platforms; the following sections describe +them. Machines where +.Xr ld +has no additional functionality are not listed. +.Pp +.Ss Xr ld and the H8/300 +For the H8/300, +.Xr ld +can perform these global optimizations when you specify the +.Li --relax +command-line option. +.Pp +.Bl -tag -width Ds +.It relaxing address modes +.Xr ld +finds all +.Li jsr +and +.Li jmp +instructions whose targets are within eight bits, and turns them into eight-bit +program-counter relative +.Li bsr +and +.Li bra +instructions, respectively. +.Pp +.It synthesizing instructions +.Xr ld +finds all +.Li mov.b +instructions which use the sixteen-bit absolute address form, but refer to +the top page of memory, and changes them to use the eight-bit address form. +(That is: the linker turns +.Li mov.b Li @ Va aa:16 +into +.Li mov.b Li @ Va aa:8 +whenever the address +.Va aa +is in the top page of memory). +.Pp +.It bit manipulation instructions +.Xr ld +finds all bit manipulation instructions like +.Li band, bclr, biand, bild, bior, bist, bixor, bld, bnot, bor, bset, bst, btst, bxor +which use 32 bit and 16 bit absolute address form, but refer to the top page +of memory, and changes them to use the 8 bit address form. (That is: the linker +turns +.Li bset #xx:3, Li @ Va aa:32 +into +.Li bset #xx:3, Li @ Va aa:8 +whenever the address +.Va aa +is in the top page of memory). +.Pp +.It system control instructions +.Xr ld +finds all +.Li ldc.w, stc.w +instructions which use the 32 bit absolute address form, but refer to the +top page of memory, and changes them to use 16 bit address form. (That is: +the linker turns +.Li ldc.w Li @ Va aa:32,ccr +into +.Li ldc.w Li @ Va aa:16,ccr +whenever the address +.Va aa +is in the top page of memory). +.El +.Pp +.Ss Xr ld and the Intel 960 Family +You can use the +.Li -A Va architecture +command line option to specify one of the two-letter names identifying members +of the 960 family; the option specifies the desired output target, and warns +of any incompatible instructions in the input files. It also modifies the +linker's search strategy for archive libraries, to support the use of libraries +specific to each particular architecture, by including in the search loop +names suffixed with the string identifying the architecture. +.Pp +For example, if your +.Xr ld +command line included +.Li -ACA +as well as +.Li -ltry +, the linker would look (in its built-in search paths, and in any paths you +specify with +.Li -L ) +for a library with the names +.Pp +.Bd -literal -offset indent + +try +libtry.a +tryca +libtryca.a + +.Ed +.Pp +The first two possibilities would be considered in any event; the last two +are due to the use of +.Li -ACA +\&. +.Pp +You can meaningfully use +.Li -A +more than once on a command line, since the 960 architecture family allows +combination of target architectures; each use will add another pair of name +variants to search for when +.Li -l +specifies a library. +.Pp +.Xr ld +supports the +.Li --relax +option for the i960 family. If you specify +.Li --relax , +.Xr ld +finds all +.Li balx +and +.Li calx +instructions whose targets are within 24 bits, and turns them into 24-bit +program-counter relative +.Li bal +and +.Li cal +instructions, respectively. +.Xr ld +also turns +.Li cal +instructions into +.Li bal +instructions when it determines that the target subroutine is a leaf routine +(that is, the target subroutine does not itself call any subroutines). +.Pp +.Ss Xr ld and the Motorola 68HC11 and 68HC12 families +.Em Linker Relaxation +.Pp +For the Motorola 68HC11, +.Xr ld +can perform these global optimizations when you specify the +.Li --relax +command-line option. +.Pp +.Bl -tag -width Ds +.It relaxing address modes +.Xr ld +finds all +.Li jsr +and +.Li jmp +instructions whose targets are within eight bits, and turns them into eight-bit +program-counter relative +.Li bsr +and +.Li bra +instructions, respectively. +.Pp +.Xr ld +also looks at all 16-bit extended addressing modes and transforms them in +a direct addressing mode when the address is in page 0 (between 0 and 0x0ff). +.Pp +.It relaxing gcc instruction group +When +.Xr gcc +is called with +.Op -mrelax , +it can emit group of instructions that the linker can optimize to use a 68HC11 +direct addressing mode. These instructions consists of +.Li bclr +or +.Li bset +instructions. +.Pp +.El +.Em Trampoline Generation +.Pp +For 68HC11 and 68HC12, +.Xr ld +can generate trampoline code to call a far function using a normal +.Li jsr +instruction. The linker will also change the relocation to some far function +to use the trampoline address instead of the function address. This is typically +the case when a pointer to a function is taken. The pointer will in fact point +to the function trampoline. +.Pp +The +.Li --pic-veneer +switch makes the linker use PIC sequences for ARM/Thumb interworking veneers, +even if the rest of the binary is not PIC. This avoids problems on uClinux +targets where +.Li --emit-relocs +is used to generate relocatable binaries. +.Pp +.Ss Xr ld and the ARM family +For the ARM, +.Xr ld +will generate code stubs to allow functions calls between ARM and Thumb code. +These stubs only work with code that has been compiled and assembled with +the +.Li -mthumb-interwork +command line option. If it is necessary to link with old ARM object files +or libraries, which have not been compiled with the -mthumb-interwork option +then the +.Li --support-old-code +command line switch should be given to the linker. This will make it generate +larger stub functions which will work with non-interworking aware ARM code. +Note, however, the linker does not support generating stubs for function calls +to non-interworking aware Thumb code. +.Pp +The +.Li --thumb-entry +switch is a duplicate of the generic +.Li --entry +switch, in that it sets the program's starting address. But it also sets the +bottom bit of the address, so that it can be branched to using a BX instruction, +and the program will start executing in Thumb mode straight away. +.Pp +The +.Li --be8 +switch instructs +.Xr ld +to generate BE8 format executables. This option is only valid when linking +big-endian objects. The resulting image will contain big-endian data and little-endian +code. +.Pp +The +.Li R_ARM_TARGET1 +relocation is typically used for entries in the +.Li .init_array +section. It is interpreted as either +.Li R_ARM_REL32 +or +.Li R_ARM_ABS32 , +depending on the target. The +.Li --target1-rel +and +.Li --target1-abs +switches override the default. +.Pp +The +.Li --target2=type +switch overrides the default definition of the +.Li R_ARM_TARGET2 +relocation. Valid values for +.Li type , +their meanings, and target defaults are as follows: +.Bl -tag -width Ds +.It rel +.Li R_ARM_REL32 +(arm*-*-elf, arm*-*-eabi) +.It abs +.Li R_ARM_ABS32 +(arm*-*-symbianelf) +.It got-rel +.Li R_ARM_GOT_PREL +(arm*-*-linux, arm*-*-*bsd) +.El +.Pp +The +.Li R_ARM_V4BX +relocation (defined by the ARM AAELF specification) enables objects compiled +for the ARMv4 architecture to be interworking-safe when linked with other +objects compiled for ARMv4t, but also allows pure ARMv4 binaries to be built +from the same ARMv4 objects. +.Pp +In the latter case, the switch +.Op --fix-v4bx +must be passed to the linker, which causes v4t +.Li BX rM +instructions to be rewritten as +.Li MOV PC,rM , +since v4 processors do not have a +.Li BX +instruction. +.Pp +In the former case, the switch should not be used, and +.Li R_ARM_V4BX +relocations are ignored. +.Pp +The +.Li --use-blx +switch enables the linker to use ARM/Thumb BLX instructions (available on +ARMv5t and above) in various situations. Currently it is used to perform calls +via the PLT from Thumb code using BLX rather than using BX and a mode-switching +stub before each PLT entry. This should lead to such calls executing slightly +faster. +.Pp +This option is enabled implicitly for SymbianOS, so there is no need to specify +it if you are using that target. +.Pp +The +.Li --vfp11-denorm-fix +switch enables a link-time workaround for a bug in certain VFP11 coprocessor +hardware, which sometimes allows instructions with denorm operands (which +must be handled by support code) to have those operands overwritten by subsequent +instructions before the support code can read the intended values. +.Pp +The bug may be avoided in scalar mode if you allow at least one intervening +instruction between a VFP11 instruction which uses a register and another +instruction which writes to the same register, or at least two intervening +instructions if vector mode is in use. The bug only affects full-compliance +floating-point mode: you do not need this workaround if you are using "runfast" +mode. Please contact ARM for further details. +.Pp +If you know you are using buggy VFP11 hardware, you can enable this workaround +by specifying the linker option +.Li --vfp-denorm-fix=scalar +if you are using the VFP11 scalar mode only, or +.Li --vfp-denorm-fix=vector +if you are using vector mode (the latter also works for scalar code). The +default is +.Li --vfp-denorm-fix=none . +.Pp +If the workaround is enabled, instructions are scanned for potentially-troublesome +sequences, and a veneer is created for each such sequence which may trigger +the erratum. The veneer consists of the first instruction of the sequence +and a branch back to the subsequent instruction. The original instruction +is then replaced with a branch to the veneer. The extra cycles required to +call and return from the veneer are sufficient to avoid the erratum in both +the scalar and vector cases. +.Pp +The +.Li --no-enum-size-warning +switch prevents the linker from warning when linking object files that specify +incompatible EABI enumeration size attributes. For example, with this switch +enabled, linking of an object file using 32-bit enumeration values with another +using enumeration values fitted into the smallest possible space will not +be diagnosed. +.Pp +.Ss Xr ld and HPPA 32-bit ELF Support +When generating a shared library, +.Xr ld +will by default generate import stubs suitable for use with a single sub-space +application. The +.Li --multi-subspace +switch causes +.Xr ld +to generate export stubs, and different (larger) import stubs suitable for +use with multiple sub-spaces. +.Pp +Long branch stubs and import/export stubs are placed by +.Xr ld +in stub sections located between groups of input sections. +.Li --stub-group-size +specifies the maximum size of a group of input sections handled by one stub +section. Since branch offsets are signed, a stub section may serve two groups +of input sections, one group before the stub section, and one group after +it. However, when using conditional branches that require stubs, it may be +better (for branch prediction) that stub sections only serve one group of +input sections. A negative value for +.Li N +chooses this scheme, ensuring that branches to stubs always use a negative +offset. Two special values of +.Li N +are recognized, +.Li 1 +and +.Li -1 . +These both instruct +.Xr ld +to automatically size input section groups for the branch types detected, +with the same behaviour regarding stub placement as other positive or negative +values of +.Li N +respectively. +.Pp +Note that +.Li --stub-group-size +does not split input sections. A single input section larger than the group +size specified will of course create a larger group (of one section). If input +sections are too large, it may not be possible for a branch to reach its stub. +.Pp +.Ss Li ld and MMIX +For MMIX, there is a choice of generating +.Li ELF +object files or +.Li mmo +object files when linking. The simulator +.Li mmix +understands the +.Li mmo +format. The binutils +.Li objcopy +utility can translate between the two formats. +.Pp +There is one special section, the +.Li .MMIX.reg_contents +section. Contents in this section is assumed to correspond to that of global +registers, and symbols referring to it are translated to special symbols, +equal to registers. In a final link, the start address of the +.Li .MMIX.reg_contents +section corresponds to the first allocated global register multiplied by 8. +Register +.Li $255 +is not included in this section; it is always set to the program entry, which +is at the symbol +.Li Main +for +.Li mmo +files. +.Pp +Symbols with the prefix +.Li __.MMIX.start. , +for example +.Li __.MMIX.start..text +and +.Li __.MMIX.start..data +are special; there must be only one each, even if they are local. The default +linker script uses these to set the default start address of a section. +.Pp +Initial and trailing multiples of zero-valued 32-bit words in a section, are +left out from an mmo file. +.Pp +.Ss Li ld and MSP430 +For the MSP430 it is possible to select the MPU architecture. The flag +.Li -m [mpu type] +will select an appropriate linker script for selected MPU type. (To get a +list of known MPUs just pass +.Li -m help +option to the linker). +.Pp +The linker will recognize some extra sections which are MSP430 specific: +.Pp +.Bl -tag -width Ds +.It Li .vectors +Defines a portion of ROM where interrupt vectors located. +.Pp +.It Li .bootloader +Defines the bootloader portion of the ROM (if applicable). Any code in this +section will be uploaded to the MPU. +.Pp +.It Li .infomem +Defines an information memory section (if applicable). Any code in this section +will be uploaded to the MPU. +.Pp +.It Li .infomemnobits +This is the same as the +.Li .infomem +section except that any code in this section will not be uploaded to the MPU. +.Pp +.It Li .noinit +Denotes a portion of RAM located above +.Li .bss +section. +.Pp +The last two sections are used by gcc. +.El +.Pp +.Ss Xr ld and PowerPC 32-bit ELF Support +Branches on PowerPC processors are limited to a signed 26-bit displacement, +which may result in +.Xr ld +giving +.Li relocation truncated to fit +errors with very large programs. +.Li --relax +enables the generation of trampolines that can access the entire 32-bit address +space. These trampolines are inserted at section boundaries, so may not themselves +be reachable if an input section exceeds 33M in size. +.Pp +.Bl -tag -width Ds +.It --bss-plt +Current PowerPC GCC accepts a +.Li -msecure-plt +option that generates code capable of using a newer PLT and GOT layout that +has the security advantage of no executable section ever needing to be writable +and no writable section ever being executable. PowerPC +.Xr ld +will generate this layout, including stubs to access the PLT, if all input +files (including startup and static libraries) were compiled with +.Li -msecure-plt . +.Li --bss-plt +forces the old BSS PLT (and GOT layout) which can give slightly better performance. +.Pp +.It --secure-plt +.Xr ld +will use the new PLT and GOT layout if it is linking new +.Li -fpic +or +.Li -fPIC +code, but does not do so automatically when linking non-PIC code. This option +requests the new PLT and GOT layout. A warning will be given if some object +file requires the old style BSS PLT. +.Pp +.It --sdata-got +The new secure PLT and GOT are placed differently relative to other sections +compared to older BSS PLT and GOT placement. The location of +.Li .plt +must change because the new secure PLT is an initialized section while the +old PLT is uninitialized. The reason for the +.Li .got +change is more subtle: The new placement allows +.Li .got +to be read-only in applications linked with +.Li -z relro -z now . +However, this placement means that +.Li .sdata +cannot always be used in shared libraries, because the PowerPC ABI accesses +.Li .sdata +in shared libraries from the GOT pointer. +.Li --sdata-got +forces the old GOT placement. PowerPC GCC doesn't use +.Li .sdata +in shared libraries, so this option is really only useful for other compilers +that may do so. +.Pp +.It --emit-stub-syms +This option causes +.Xr ld +to label linker stubs with a local symbol that encodes the stub type and destination. +.Pp +.It --no-tls-optimize +PowerPC +.Xr ld +normally performs some optimization of code sequences used to access Thread-Local +Storage. Use this option to disable the optimization. +.El +.Pp +.Ss Xr ld and PowerPC64 64-bit ELF Support +.Bl -tag -width Ds +.It --stub-group-size +Long branch stubs, PLT call stubs and TOC adjusting stubs are placed by +.Xr ld +in stub sections located between groups of input sections. +.Li --stub-group-size +specifies the maximum size of a group of input sections handled by one stub +section. Since branch offsets are signed, a stub section may serve two groups +of input sections, one group before the stub section, and one group after +it. However, when using conditional branches that require stubs, it may be +better (for branch prediction) that stub sections only serve one group of +input sections. A negative value for +.Li N +chooses this scheme, ensuring that branches to stubs always use a negative +offset. Two special values of +.Li N +are recognized, +.Li 1 +and +.Li -1 . +These both instruct +.Xr ld +to automatically size input section groups for the branch types detected, +with the same behaviour regarding stub placement as other positive or negative +values of +.Li N +respectively. +.Pp +Note that +.Li --stub-group-size +does not split input sections. A single input section larger than the group +size specified will of course create a larger group (of one section). If input +sections are too large, it may not be possible for a branch to reach its stub. +.Pp +.It --emit-stub-syms +This option causes +.Xr ld +to label linker stubs with a local symbol that encodes the stub type and destination. +.Pp +.It --dotsyms, --no-dotsyms +These two options control how +.Xr ld +interprets version patterns in a version script. Older PowerPC64 compilers +emitted both a function descriptor symbol with the same name as the function, +and a code entry symbol with the name prefixed by a dot ( +.Li . ) . +To properly version a function +.Li foo , +the version script thus needs to control both +.Li foo +and +.Li .foo . +The option +.Li --dotsyms , +on by default, automatically adds the required dot-prefixed patterns. Use +.Li --no-dotsyms +to disable this feature. +.Pp +.It --no-tls-optimize +PowerPC64 +.Xr ld +normally performs some optimization of code sequences used to access Thread-Local +Storage. Use this option to disable the optimization. +.Pp +.It --no-opd-optimize +PowerPC64 +.Xr ld +normally removes +.Li .opd +section entries corresponding to deleted link-once functions, or functions +removed by the action of +.Li --gc-sections +or linker scrip +.Li /DISCARD/ . +Use this option to disable +.Li .opd +optimization. +.Pp +.It --non-overlapping-opd +Some PowerPC64 compilers have an option to generate compressed +.Li .opd +entries spaced 16 bytes apart, overlapping the third word, the static chain +pointer (unused in C) with the first word of the next entry. This option expands +such entries to the full 24 bytes. +.Pp +.It --no-toc-optimize +PowerPC64 +.Xr ld +normally removes unused +.Li .toc +section entries. Such entries are detected by examining relocations that reference +the TOC in code sections. A reloc in a deleted code section marks a TOC word +as unneeded, while a reloc in a kept code section marks a TOC word as needed. +Since the TOC may reference itself, TOC relocs are also examined. TOC words +marked as both needed and unneeded will of course be kept. TOC words without +any referencing reloc are assumed to be part of a multi-word entry, and are +kept or discarded as per the nearest marked preceding word. This works reliably +for compiler generated code, but may be incorrect if assembly code is used +to insert TOC entries. Use this option to disable the optimization. +.Pp +.It --no-multi-toc +By default, PowerPC64 GCC generates code for a TOC model where TOC entries +are accessed with a 16-bit offset from r2. This limits the total TOC size +to 64K. PowerPC64 +.Xr ld +extends this limit by grouping code sections such that each group uses less +than 64K for its TOC entries, then inserts r2 adjusting stubs between inter-group +calls. +.Xr ld +does not split apart input sections, so cannot help if a single input file +has a +.Li .toc +section that exceeds 64K, most likely from linking multiple files with +.Xr ld -r . +Use this option to turn off this feature. +.El +.Pp +.Ss Xr ld and SPU ELF Support +.Bl -tag -width Ds +.It --plugin +This option marks an executable as a PIC plugin module. +.Pp +.It --no-overlays +Normally, +.Xr ld +recognizes calls to functions within overlay regions, and redirects such calls +to an overlay manager via a stub. +.Xr ld +also provides a built-in overlay manager. This option turns off all this special +overlay handling. +.Pp +.It --emit-stub-syms +This option causes +.Xr ld +to label overlay stubs with a local symbol that encodes the stub type and +destination. +.Pp +.It --extra-overlay-stubs +This option causes +.Xr ld +to add overlay call stubs on all function calls out of overlay regions. Normally +stubs are not added on calls to non-overlay regions. +.Pp +.It --local-store=lo:hi +.Xr ld +usually checks that a final executable for SPU fits in the address range 0 +to 256k. This option may be used to change the range. Disable the check entirely +with +.Op --local-store=0:0 . +.Pp +.It --stack-analysis +SPU local store space is limited. Over-allocation of stack space unnecessarily +limits space available for code and data, while under-allocation results in +runtime failures. If given this option, +.Xr ld +will provide an estimate of maximum stack usage. +.Xr ld +does this by examining symbols in code sections to determine the extents of +functions, and looking at function prologues for stack adjusting instructions. +A call-graph is created by looking for relocations on branch instructions. +The graph is then searched for the maximum stack usage path. Note that this +analysis does not find calls made via function pointers, and does not handle +recursion and other cycles in the call graph. Stack usage may be under-estimated +if your code makes such calls. Also, stack usage for dynamic allocation, e.g. +alloca, will not be detected. If a link map is requested, detailed information +about each function's stack usage and calls will be given. +.Pp +.It --emit-stack-syms +This option, if given along with +.Op --stack-analysis +will result in +.Xr ld +emitting stack sizing symbols for each function. These take the form +.Li __stack_<function_name> +for global functions, and +.Li __stack_<number>_<function_name> +for static functions. +.Li <number> +is the section id in hex. The value of such symbols is the stack requirement +for the corresponding function. The symbol size will be zero, type +.Li STT_NOTYPE , +binding +.Li STB_LOCAL , +and section +.Li SHN_ABS . +.El +.Pp +.Ss Xr ld's Support for Various TI COFF Versions +The +.Li --format +switch allows selection of one of the various TI COFF versions. The latest +of this writing is 2; versions 0 and 1 are also supported. The TI COFF versions +also vary in header byte-order format; +.Xr ld +will read any version or byte order, but the output header format depends +on the default specified by the specific target. +.Pp +.Ss Xr ld and WIN32 (cygwin/mingw) +This section describes some of the win32 specific +.Xr ld +issues. See Options,,Command Line Options for detailed description of the +command line options mentioned here. +.Pp +.Bl -tag -width Ds +.It import libraries +The standard Windows linker creates and uses so-called import libraries, which +contains information for linking to dll's. They are regular static archives +and are handled as any other static archive. The cygwin and mingw ports of +.Xr ld +have specific support for creating such libraries provided with the +.Li --out-implib +command line option. +.Pp +.It exporting DLL symbols +The cygwin/mingw +.Xr ld +has several ways to export symbols for dll's. +.Pp +.Bl -tag -width Ds +.It using auto-export functionality +By default +.Xr ld +exports symbols with the auto-export functionality, which is controlled by +the following command line options: +.Pp +.Bl -bullet +.It +--export-all-symbols [This is the default] +.It +--exclude-symbols +.It +--exclude-libs +.El +.Pp +If, however, +.Li --export-all-symbols +is not given explicitly on the command line, then the default auto-export +behavior will be +.Em disabled +if either of the following are true: +.Pp +.Bl -bullet +.It +A DEF file is used. +.It +Any symbol in any object file was marked with the __declspec(dllexport) attribute. +.El +.Pp +.It using a DEF file +Another way of exporting symbols is using a DEF file. A DEF file is an ASCII +file containing definitions of symbols which should be exported when a dll +is created. Usually it is named +.Li <dll name>.def +and is added as any other object file to the linker's command line. The file's +name must end in +.Li .def +or +.Li .DEF . +.Pp +.Bd -literal -offset indent +gcc -o <output> <objectfiles> <dll name>.def +.Ed +.Pp +Using a DEF file turns off the normal auto-export behavior, unless the +.Li --export-all-symbols +option is also used. +.Pp +Here is an example of a DEF file for a shared library called +.Li xyz.dll : +.Pp +.Bd -literal -offset indent +LIBRARY "xyz.dll" BASE=0x20000000 + +EXPORTS +foo +bar +_bar = bar +another_foo = abc.dll.afoo +var1 DATA +.Ed +.Pp +This example defines a DLL with a non-default base address and five symbols +in the export table. The third exported symbol +.Li _bar +is an alias for the second. The fourth symbol, +.Li another_foo +is resolved by "forwarding" to another module and treating it as an alias +for +.Li afoo +exported from the DLL +.Li abc.dll . +The final symbol +.Li var1 +is declared to be a data object. +.Pp +The optional +.Li LIBRARY <name> +command indicates the +.Em internal +name of the output DLL. If +.Li <name> +does not include a suffix, the default library suffix, +.Li .DLL +is appended. +.Pp +When the .DEF file is used to build an application, rather than a library, +the +.Li NAME <name> +command should be used instead of +.Li LIBRARY . +If +.Li <name> +does not include a suffix, the default executable suffix, +.Li .EXE +is appended. +.Pp +With either +.Li LIBRARY <name> +or +.Li NAME <name> +the optional specification +.Li BASE = <number> +may be used to specify a non-default base address for the image. +.Pp +If neither +.Li LIBRARY <name> +nor +.Li NAME <name> +is specified, or they specify an empty string, the internal name is the same +as the filename specified on the command line. +.Pp +The complete specification of an export symbol is: +.Pp +.Bd -literal -offset indent +EXPORTS + ( ( ( <name1> [ = <name2> ] ) + | ( <name1> = <module-name> . <external-name>)) + [ @ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] ) * +.Ed +.Pp +Declares +.Li <name1> +as an exported symbol from the DLL, or declares +.Li <name1> +as an exported alias for +.Li <name2> ; +or declares +.Li <name1> +as a "forward" alias for the symbol +.Li <external-name> +in the DLL +.Li <module-name> . +Optionally, the symbol may be exported by the specified ordinal +.Li <integer> +alias. +.Pp +The optional keywords that follow the declaration indicate: +.Pp +.Li NONAME : +Do not put the symbol name in the DLL's export table. It will still be exported +by its ordinal alias (either the value specified by the .def specification +or, otherwise, the value assigned by the linker). The symbol name, however, +does remain visible in the import library (if any), unless +.Li PRIVATE +is also specified. +.Pp +.Li DATA : +The symbol is a variable or object, rather than a function. The import lib +will export only an indirect reference to +.Li foo +as the symbol +.Li _imp__foo +(ie, +.Li foo +must be resolved as +.Li *_imp__foo ) . +.Pp +.Li CONSTANT : +Like +.Li DATA , +but put the undecorated +.Li foo +as well as +.Li _imp__foo +into the import library. Both refer to the read-only import address table's +pointer to the variable, not to the variable itself. This can be dangerous. +If the user code fails to add the +.Li dllimport +attribute and also fails to explicitly add the extra indirection that the +use of the attribute enforces, the application will behave unexpectedly. +.Pp +.Li PRIVATE : +Put the symbol in the DLL's export table, but do not put it into the static +import library used to resolve imports at link time. The symbol can still +be imported using the +.Li LoadLibrary/GetProcAddress +API at runtime or by by using the GNU ld extension of linking directly to +the DLL without an import library. See ld/deffilep.y in the binutils sources +for the full specification of other DEF file statements +.Pp +While linking a shared dll, +.Xr ld +is able to create a DEF file with the +.Li --output-def <file> +command line option. +.Pp +.It Using decorations +Another way of marking symbols for export is to modify the source code itself, +so that when building the DLL each symbol to be exported is declared as: +.Pp +.Bd -literal -offset indent +__declspec(dllexport) int a_variable +__declspec(dllexport) void a_function(int with_args) +.Ed +.Pp +All such symbols will be exported from the DLL. If, however, any of the object +files in the DLL contain symbols decorated in this way, then the normal auto-export +behavior is disabled, unless the +.Li --export-all-symbols +option is also used. +.Pp +Note that object files that wish to access these symbols must +.Em not +decorate them with dllexport. Instead, they should use dllimport, instead: +.Pp +.Bd -literal -offset indent +__declspec(dllimport) int a_variable +__declspec(dllimport) void a_function(int with_args) +.Ed +.Pp +This complicates the structure of library header files, because when included +by the library itself the header must declare the variables and functions +as dllexport, but when included by client code the header must declare them +as dllimport. There are a number of idioms that are typically used to do this; +often client code can omit the __declspec() declaration completely. See +.Li --enable-auto-import +and +.Li automatic data imports +for more information. +.El +.Pp +.It automatic data imports +The standard Windows dll format supports data imports from dlls only by adding +special decorations (dllimport/dllexport), which let the compiler produce +specific assembler instructions to deal with this issue. This increases the +effort necessary to port existing Un*x code to these platforms, especially +for large c++ libraries and applications. The auto-import feature, which was +initially provided by Paul Sokolovsky, allows one to omit the decorations +to achieve a behavior that conforms to that on POSIX/Un*x platforms. This +feature is enabled with the +.Li --enable-auto-import +command-line option, although it is enabled by default on cygwin/mingw. The +.Li --enable-auto-import +option itself now serves mainly to suppress any warnings that are ordinarily +emitted when linked objects trigger the feature's use. +.Pp +auto-import of variables does not always work flawlessly without additional +assistance. Sometimes, you will see this message +.Pp +"variable '<var>' can't be auto-imported. Please read the documentation for +ld's +.Li --enable-auto-import +for details." +.Pp +The +.Li --enable-auto-import +documentation explains why this error occurs, and several methods that can +be used to overcome this difficulty. One of these methods is the +.Em runtime pseudo-relocs +feature, described below. +.Pp +For complex variables imported from DLLs (such as structs or classes), object +files typically contain a base address for the variable and an offset ( +.Em addend ) +within the variable--to specify a particular field or public member, for instance. +Unfortunately, the runtime loader used in win32 environments is incapable +of fixing these references at runtime without the additional information supplied +by dllimport/dllexport decorations. The standard auto-import feature described +above is unable to resolve these references. +.Pp +The +.Li --enable-runtime-pseudo-relocs +switch allows these references to be resolved without error, while leaving +the task of adjusting the references themselves (with their non-zero addends) +to specialized code provided by the runtime environment. Recent versions of +the cygwin and mingw environments and compilers provide this runtime support; +older versions do not. However, the support is only necessary on the developer's +platform; the compiled result will run without error on an older system. +.Pp +.Li --enable-runtime-pseudo-relocs +is not the default; it must be explicitly enabled as needed. +.Pp +.It direct linking to a dll +The cygwin/mingw ports of +.Xr ld +support the direct linking, including data symbols, to a dll without the usage +of any import libraries. This is much faster and uses much less memory than +does the traditional import library method, especially when linking large +libraries or applications. When +.Xr ld +creates an import lib, each function or variable exported from the dll is +stored in its own bfd, even though a single bfd could contain many exports. +The overhead involved in storing, loading, and processing so many bfd's is +quite large, and explains the tremendous time, memory, and storage needed +to link against particularly large or complex libraries when using import +libs. +.Pp +Linking directly to a dll uses no extra command-line switches other than +.Li -L +and +.Li -l , +because +.Xr ld +already searches for a number of names to match each library. All that is +needed from the developer's perspective is an understanding of this search, +in order to force ld to select the dll instead of an import library. +.Pp +For instance, when ld is called with the argument +.Li -lxxx +it will attempt to find, in the first directory of its search path, +.Pp +.Bd -literal -offset indent +libxxx.dll.a +xxx.dll.a +libxxx.a +xxx.lib +cygxxx.dll (*) +libxxx.dll +xxx.dll +.Ed +.Pp +before moving on to the next directory in the search path. +.Pp +(*) Actually, this is not +.Li cygxxx.dll +but in fact is +.Li <prefix>xxx.dll , +where +.Li <prefix> +is set by the +.Xr ld +option +.Li --dll-search-prefix=<prefix> . +In the case of cygwin, the standard gcc spec file includes +.Li --dll-search-prefix=cyg , +so in effect we actually search for +.Li cygxxx.dll . +.Pp +Other win32-based unix environments, such as mingw or pw32, may use other +.Li <prefix> +es, although at present only cygwin makes use of this feature. It was originally +intended to help avoid name conflicts among dll's built for the various win32/un*x +environments, so that (for example) two versions of a zlib dll could coexist +on the same machine. +.Pp +The generic cygwin/mingw path layout uses a +.Li bin +directory for applications and dll's and a +.Li lib +directory for the import libraries (using cygwin nomenclature): +.Pp +.Bd -literal -offset indent +bin/ + cygxxx.dll +lib/ + libxxx.dll.a (in case of dll's) + libxxx.a (in case of static archive) +.Ed +.Pp +Linking directly to a dll without using the import library can be done two +ways: +.Pp +1. Use the dll directly by adding the +.Li bin +path to the link line +.Bd -literal -offset indent +gcc -Wl,-verbose -o a.exe -L../bin/ -lxxx +.Ed +.Pp +However, as the dll's often have version numbers appended to their names ( +.Li cygncurses-5.dll ) +this will often fail, unless one specifies +.Li -L../bin -lncurses-5 +to include the version. Import libs are generally not versioned, and do not +have this difficulty. +.Pp +2. Create a symbolic link from the dll to a file in the +.Li lib +directory according to the above mentioned search pattern. This should be +used to avoid unwanted changes in the tools needed for making the app/dll. +.Pp +.Bd -literal -offset indent +ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a] +.Ed +.Pp +Then you can link without any make environment changes. +.Pp +.Bd -literal -offset indent +gcc -Wl,-verbose -o a.exe -L../lib/ -lxxx +.Ed +.Pp +This technique also avoids the version number problems, because the following +is perfectly legal +.Pp +.Bd -literal -offset indent +bin/ + cygxxx-5.dll +lib/ + libxxx.dll.a -> ../bin/cygxxx-5.dll +.Ed +.Pp +Linking directly to a dll without using an import lib will work even when +auto-import features are exercised, and even when +.Li --enable-runtime-pseudo-relocs +is used. +.Pp +Given the improvements in speed and memory usage, one might justifiably wonder +why import libraries are used at all. There are three reasons: +.Pp +1. Until recently, the link-directly-to-dll functionality did +.Em not +work with auto-imported data. +.Pp +2. Sometimes it is necessary to include pure static objects within the import +library (which otherwise contains only bfd's for indirection symbols that +point to the exports of a dll). Again, the import lib for the cygwin kernel +makes use of this ability, and it is not possible to do this without an import +lib. +.Pp +3. Symbol aliases can only be resolved using an import lib. This is critical +when linking against OS-supplied dll's (eg, the win32 API) in which symbols +are usually exported as undecorated aliases of their stdcall-decorated assembly +names. +.Pp +So, import libs are not going away. But the ability to replace true import +libs with a simple symbolic link to (or a copy of) a dll, in many cases, is +a useful addition to the suite of tools binutils makes available to the win32 +developer. Given the massive improvements in memory requirements during linking, +storage requirements, and linking speed, we expect that many developers will +soon begin to use this feature whenever possible. +.Pp +.It symbol aliasing +.Bl -tag -width Ds +.It adding additional names +Sometimes, it is useful to export symbols with additional names. A symbol +.Li foo +will be exported as +.Li foo , +but it can also be exported as +.Li _foo +by using special directives in the DEF file when creating the dll. This will +affect also the optional created import library. Consider the following DEF +file: +.Pp +.Bd -literal -offset indent +LIBRARY "xyz.dll" BASE=0x61000000 + +EXPORTS +foo +_foo = foo +.Ed +.Pp +The line +.Li _foo = foo +maps the symbol +.Li foo +to +.Li _foo . +.Pp +Another method for creating a symbol alias is to create it in the source code +using the "weak" attribute: +.Pp +.Bd -literal -offset indent +void foo () { /* Do something. */; } +void _foo () __attribute__ ((weak, alias ("foo"))); +.Ed +.Pp +See the gcc manual for more information about attributes and weak symbols. +.Pp +.It renaming symbols +Sometimes it is useful to rename exports. For instance, the cygwin kernel +does this regularly. A symbol +.Li _foo +can be exported as +.Li foo +but not as +.Li _foo +by using special directives in the DEF file. (This will also affect the import +library, if it is created). In the following example: +.Pp +.Bd -literal -offset indent +LIBRARY "xyz.dll" BASE=0x61000000 + +EXPORTS +_foo = foo +.Ed +.Pp +The line +.Li _foo = foo +maps the exported symbol +.Li foo +to +.Li _foo . +.El +.Pp +Note: using a DEF file disables the default auto-export behavior, unless the +.Li --export-all-symbols +command line option is used. If, however, you are trying to rename symbols, +then you should list +.Em all +desired exports in the DEF file, including the symbols that are not being +renamed, and do +.Em not +use the +.Li --export-all-symbols +option. If you list only the renamed symbols in the DEF file, and use +.Li --export-all-symbols +to handle the other symbols, then the both the new names +.Em and +the original names for the renamed symbols will be exported. In effect, you'd +be aliasing those symbols, not renaming them, which is probably not what you +wanted. +.Pp +.It weak externals +The Windows object format, PE, specifies a form of weak symbols called weak +externals. When a weak symbol is linked and the symbol is not defined, the +weak symbol becomes an alias for some other symbol. There are three variants +of weak externals: +.Bl -bullet +.It +Definition is searched for in objects and libraries, historically +called lazy externals. +.It +Definition is searched for only in other objects, not in libraries. +This form is not presently implemented. +.It +No search; the symbol is an alias. This form is not presently +implemented. +.El +As a GNU extension, weak symbols that do not specify an alternate symbol are +supported. If the symbol is undefined when linking, the symbol uses a default +value. +.El +.Pp +.Ss Li ld and Xtensa Processors +The default +.Xr ld +behavior for Xtensa processors is to interpret +.Li SECTIONS +commands so that lists of explicitly named sections in a specification with +a wildcard file will be interleaved when necessary to keep literal pools within +the range of PC-relative load offsets. For example, with the command: +.Pp +.Bd -literal -offset indent +SECTIONS +{ + .text : { + *(.literal .text) + } +} +.Ed +.Pp +.Xr ld +may interleave some of the +.Li .literal +and +.Li .text +sections from different object files to ensure that the literal pools are +within the range of PC-relative load offsets. A valid interleaving might place +the +.Li .literal +sections from an initial group of files followed by the +.Li .text +sections of that group of files. Then, the +.Li .literal +sections from the rest of the files and the +.Li .text +sections from the rest of the files would follow. +.Pp +Relaxation is enabled by default for the Xtensa version of +.Xr ld +and provides two important link-time optimizations. The first optimization +is to combine identical literal values to reduce code size. A redundant literal +will be removed and all the +.Li L32R +instructions that use it will be changed to reference an identical literal, +as long as the location of the replacement literal is within the offset range +of all the +.Li L32R +instructions. The second optimization is to remove unnecessary overhead from +assembler-generated \(lqlongcall\(rq sequences of +.Li L32R +/ +.Li CALLX Va n +when the target functions are within range of direct +.Li CALL Va n +instructions. +.Pp +For each of these cases where an indirect call sequence can be optimized to +a direct call, the linker will change the +.Li CALLX Va n +instruction to a +.Li CALL Va n +instruction, remove the +.Li L32R +instruction, and remove the literal referenced by the +.Li L32R +instruction if it is not used for anything else. Removing the +.Li L32R +instruction always reduces code size but can potentially hurt performance +by changing the alignment of subsequent branch targets. By default, the linker +will always preserve alignments, either by switching some instructions between +24-bit encodings and the equivalent density instructions or by inserting a +no-op in place of the +.Li L32R +instruction that was removed. If code size is more important than performance, +the +.Op --size-opt +option can be used to prevent the linker from widening density instructions +or inserting no-ops, except in a few cases where no-ops are required for correctness. +.Pp +The following Xtensa-specific command-line options can be used to control +the linker: +.Pp +.Bl -tag -width Ds +.It --no-relax +Since the Xtensa version of +.Li ld +enables the +.Op --relax +option by default, the +.Op --no-relax +option is provided to disable relaxation. +.Pp +.It --size-opt +When optimizing indirect calls to direct calls, optimize for code size more +than performance. With this option, the linker will not insert no-ops or widen +density instructions to preserve branch target alignment. There may still +be some cases where no-ops are required to preserve the correctness of the +code. +.El +.Pp +.Sh BFD +The linker accesses object and archive files using the BFD libraries. These +libraries allow the linker to use the same routines to operate on object files +whatever the object file format. A different object file format can be supported +simply by creating a new BFD back end and adding it to the library. To conserve +runtime memory, however, the linker and associated tools are usually configured +to support only a subset of the object file formats available. You can use +.Li objdump -i +(see Section +.Dq objdump ) +to list all the formats available for your configuration. +.Pp +As with most implementations, BFD is a compromise between several conflicting +requirements. The major factor influencing BFD design was efficiency: any +time used converting between formats is time which would not have been spent +had BFD not been involved. This is partly offset by abstraction payback; since +BFD simplifies applications and back ends, more time and care may be spent +optimizing algorithms for a greater speed. +.Pp +One minor artifact of the BFD solution which you should bear in mind is the +potential for information loss. There are two places where useful information +can be lost using the BFD mechanism: during conversion and during output.See Section +.Dq BFD information loss . +.Pp +.Ss How It Works: An Outline of BFD +When an object file is opened, BFD subroutines automatically determine the +format of the input object file. They then build a descriptor in memory with +pointers to routines that will be used to access elements of the object file's +data structures. +.Pp +As different information from the object files is required, BFD reads from +different sections of the file and processes them. For example, a very common +operation for the linker is processing symbol tables. Each BFD back end provides +a routine for converting between the object file's representation of symbols +and an internal canonical format. When the linker asks for the symbol table +of an object file, it calls through a memory pointer to the routine from the +relevant BFD back end which reads and converts the table into a canonical +form. The linker then operates upon the canonical form. When the link is finished +and the linker writes the output file's symbol table, another BFD back end +routine is called to take the newly created symbol table and convert it into +the chosen output format. +.Pp +.Em Information Loss +.Pp +.Em Information can be lost during output. +The output formats supported by BFD do not provide identical facilities, and +information which can be described in one form has nowhere to go in another +format. One example of this is alignment information in +.Li b.out . +There is nowhere in an +.Li a.out +format file to store alignment information on the contained data, so when +a file is linked from +.Li b.out +and an +.Li a.out +image is produced, alignment information will not propagate to the output +file. (The linker will still use the alignment information internally, so +the link is performed correctly). +.Pp +Another example is COFF section names. COFF files may contain an unlimited +number of sections, each one with a textual section name. If the target of +the link is a format which does not have many sections (e.g., +.Li a.out ) +or has sections without names (e.g., the Oasys format), the link cannot be +done simply. You can circumvent this problem by describing the desired input-to-output +section mapping with the linker command language. +.Pp +.Em Information can be lost during canonicalization. +The BFD internal canonical form of the external formats is not exhaustive; +there are structures in input formats for which there is no direct representation +internally. This means that the BFD back ends cannot maintain all possible +data richness through the transformation between external to internal and +back to external formats. +.Pp +This limitation is only a problem when an application reads one format and +writes another. Each BFD back end is responsible for maintaining as much data +as possible, and the internal BFD canonical form has structures which are +opaque to the BFD core, and exported only to the back ends. When a file is +read in one format, the canonical form is generated for BFD and the application. +At the same time, the back end saves away any information which may otherwise +be lost. If the data is then written back in the same format, the back end +routine will be able to use the canonical form provided by the BFD core as +well as the information it prepared earlier. Since there is a great deal of +commonality between back ends, there is no information lost when linking or +copying big endian COFF to little endian COFF, or +.Li a.out +to +.Li b.out . +When a mixture of formats is linked, the information is only lost from the +files whose format differs from the destination. +.Pp +.Em The BFD canonical object-file format +.Pp +The greatest potential for loss of information occurs when there is the least +overlap between the information provided by the source format, that stored +by the canonical format, and that needed by the destination format. A brief +description of the canonical form may help you understand which kinds of data +you can count on preserving across conversions. +.Pp +.Bl -tag -width Ds +.It files +Information stored on a per-file basis includes target machine architecture, +particular implementation format type, a demand pageable bit, and a write +protected bit. Information like Unix magic numbers is not stored here---only +the magic numbers' meaning, so a +.Li ZMAGIC +file would have both the demand pageable bit and the write protected text +bit set. The byte order of the target is stored on a per-file basis, so that +big- and little-endian object files may be used with one another. +.Pp +.It sections +Each section in the input file contains the name of the section, the section's +original address in the object file, size and alignment information, various +flags, and pointers into other BFD data structures. +.Pp +.It symbols +Each symbol contains a pointer to the information for the object file which +originally defined it, its name, its value, and various flag bits. When a +BFD back end reads in a symbol table, it relocates all symbols to make them +relative to the base of the section where they were defined. Doing this ensures +that each symbol points to its containing section. Each symbol also has a +varying amount of hidden private data for the BFD back end. Since the symbol +points to the original file, the private data format for that symbol is accessible. +.Li ld +can operate on a collection of symbols of wildly different formats without +problems. +.Pp +Normal global and simple local symbols are maintained on output, so an output +file (no matter its format) will retain symbols pointing to functions and +to global, static, and common variables. Some symbol information is not worth +retaining; in +.Li a.out , +type information is stored in the symbol table as long symbol names. This +information would be useless to most COFF debuggers; the linker has command +line switches to allow users to throw it away. +.Pp +There is one word of type information within the symbol, so if the format +supports symbol type information within symbols (for example, COFF, IEEE, +Oasys) and the type is simple enough to fit within one word (nearly everything +but aggregates), the information will be preserved. +.Pp +.It relocation level +Each canonical BFD relocation record contains a pointer to the symbol to relocate +to, the offset of the data to relocate, the section the data is in, and a +pointer to a relocation type descriptor. Relocation is performed by passing +messages through the relocation type descriptor and the symbol pointer. Therefore, +relocations can be performed on output data using a relocation method that +is only available in one of the input formats. For instance, Oasys provides +a byte relocation format. A relocation record requesting this relocation type +would point indirectly to a routine to perform this, so the relocation may +be performed on a byte being written to a 68k COFF file, even though 68k COFF +has no such relocation type. +.Pp +.It line numbers +Object formats can contain, for debugging purposes, some form of mapping between +symbols, source line numbers, and addresses in the output file. These addresses +have to be relocated along with the symbol information. Each symbol with an +associated list of line number records points to the first record of the list. +The head of a line number list consists of a pointer to the symbol, which +allows finding out the address of the function whose line number is being +described. The rest of the list is made up of pairs: offsets into the section +and line numbers. Any format which can simply derive this information can +pass it successfully between formats (COFF, IEEE and Oasys). +.El +.Pp +.Sh Reporting Bugs +Your bug reports play an essential role in making +.Xr ld +reliable. +.Pp +Reporting a bug may help you by bringing a solution to your problem, or it +may not. But in any case the principal function of a bug report is to help +the entire community by making the next version of +.Xr ld +work better. Bug reports are your contribution to the maintenance of +.Xr ld . +.Pp +In order for a bug report to serve its purpose, you must include the information +that enables us to fix the bug. +.Pp +.Ss Have You Found a Bug? +If you are not sure whether you have found a bug, here are some guidelines: +.Pp +.Bl -bullet +.It +If the linker gets a fatal signal, for any input whatever, that is a +.Xr ld +bug. Reliable linkers never crash. +.Pp +.It +If +.Xr ld +produces an error message for valid input, that is a bug. +.Pp +.It +If +.Xr ld +does not produce an error message for invalid input, that may be a bug. In +the general case, the linker can not verify that object files are correct. +.Pp +.It +If you are an experienced user of linkers, your suggestions for improvement +of +.Xr ld +are welcome in any case. +.El +.Pp +.Ss How to Report Bugs +A number of companies and individuals offer support for GNU products. If you +obtained +.Xr ld +from a support organization, we recommend you contact that organization first. +.Pp +You can find contact information for many support companies and individuals +in the file +.Pa etc/SERVICE +in the GNU Emacs distribution. +.Pp +The fundamental principle of reporting bugs usefully is this: +.Sy report all the facts . +If you are not sure whether to state a fact or leave it out, state it! +.Pp +Often people omit facts because they think they know what causes the problem +and assume that some details do not matter. Thus, you might assume that the +name of a symbol you use in an example does not matter. Well, probably it +does not, but one cannot be sure. Perhaps the bug is a stray memory reference +which happens to fetch from the location where that name is stored in memory; +perhaps, if the name were different, the contents of that location would fool +the linker into doing the right thing despite the bug. Play it safe and give +a specific, complete example. That is the easiest thing for you to do, and +the most helpful. +.Pp +Keep in mind that the purpose of a bug report is to enable us to fix the bug +if it is new to us. Therefore, always write your bug reports on the assumption +that the bug has not been reported previously. +.Pp +Sometimes people give a few sketchy facts and ask, \(lqDoes this ring a bell?\(rq +This cannot help us fix a bug, so it is basically useless. We respond by asking +for enough details to enable us to investigate. You might as well expedite +matters by sending them to begin with. +.Pp +To enable us to fix the bug, you should include all these things: +.Pp +.Bl -bullet +.It +The version of +.Xr ld . +.Xr ld +announces it if you start it with the +.Li --version +argument. +.Pp +Without this, we will not know whether there is any point in looking for the +bug in the current version of +.Xr ld . +.Pp +.It +Any patches you may have applied to the +.Xr ld +source, including any patches made to the +.Li BFD +library. +.Pp +.It +The type of machine you are using, and the operating system name and version +number. +.Pp +.It +What compiler (and its version) was used to compile +.Xr ld +---e.g. \(lq +.Li gcc-2.7 +\(rq\&. +.Pp +.It +The command arguments you gave the linker to link your example and observe +the bug. To guarantee you will not omit something important, list them all. +A copy of the Makefile (or the output from make) is sufficient. +.Pp +If we were to try to guess the arguments, we would probably guess wrong and +then we might not encounter the bug. +.Pp +.It +A complete input file, or set of input files, that will reproduce the bug. +It is generally most helpful to send the actual object files provided that +they are reasonably small. Say no more than 10K. For bigger files you can +either make them available by FTP or HTTP or else state that you are willing +to send the object file(s) to whomever requests them. (Note - your email will +be going to a mailing list, so we do not want to clog it up with large attachments). +But small attachments are best. +.Pp +If the source files were assembled using +.Li gas +or compiled using +.Li gcc , +then it may be OK to send the source files rather than the object files. In +this case, be sure to say exactly what version of +.Li gas +or +.Li gcc +was used to produce the object files. Also say how +.Li gas +or +.Li gcc +were configured. +.Pp +.It +A description of what behavior you observe that you believe is incorrect. +For example, \(lqIt gets a fatal signal.\(rq +.Pp +Of course, if the bug is that +.Xr ld +gets a fatal signal, then we will certainly notice it. But if the bug is incorrect +output, we might not notice unless it is glaringly wrong. You might as well +not give us a chance to make a mistake. +.Pp +Even if the problem you experience is a fatal signal, you should still say +so explicitly. Suppose something strange is going on, such as, your copy of +.Xr ld +is out of sync, or you have encountered a bug in the C library on your system. +(This has happened!) Your copy might crash and ours would not. If you told +us to expect a crash, then when ours fails to crash, we would know that the +bug was not happening for us. If you had not told us to expect a crash, then +we would not be able to draw any conclusion from our observations. +.Pp +.It +If you wish to suggest changes to the +.Xr ld +source, send us context diffs, as generated by +.Li diff +with the +.Li -u , +.Li -c , +or +.Li -p +option. Always send diffs from the old file to the new file. If you even discuss +something in the +.Xr ld +source, refer to it by context, not by line number. +.Pp +The line numbers in our development sources will not match those in your sources. +Your line numbers would convey no useful information to us. +.El +.Pp +Here are some things that are not necessary: +.Pp +.Bl -bullet +.It +A description of the envelope of the bug. +.Pp +Often people who encounter a bug spend a lot of time investigating which changes +to the input file will make the bug go away and which changes will not affect +it. +.Pp +This is often time consuming and not very useful, because the way we will +find the bug is by running a single example under the debugger with breakpoints, +not by pure deduction from a series of examples. We recommend that you save +your time for something else. +.Pp +Of course, if you can find a simpler example to report +.Em instead +of the original one, that is a convenience for us. Errors in the output will +be easier to spot, running under the debugger will take less time, and so +on. +.Pp +However, simplification is not vital; if you do not want to do this, report +the bug anyway and send us the entire test case you used. +.Pp +.It +A patch for the bug. +.Pp +A patch for the bug does help us if it is a good one. But do not omit the +necessary information, such as the test case, on the assumption that a patch +is all we need. We might see problems with your patch and decide to fix the +problem another way, or we might not understand it at all. +.Pp +Sometimes with a program as complicated as +.Xr ld +it is very hard to construct an example that will make the program follow +a certain path through the code. If you do not send us the example, we will +not be able to construct one, so we will not be able to verify that the bug +is fixed. +.Pp +And if we cannot understand what bug you are trying to fix, or why your patch +should be an improvement, we will not install it. A test case will help us +to understand. +.Pp +.It +A guess about what the bug is or what it depends on. +.Pp +Such guesses are usually wrong. Even we cannot guess right about such things +without first using the debugger to find the facts. +.El +.Pp +.Sh MRI Compatible Script Files +To aid users making the transition to GNU +.Xr ld +from the MRI linker, +.Xr ld +can use MRI compatible linker scripts as an alternative to the more general-purpose +linker scripting language described in Scripts. MRI compatible linker scripts +have a much simpler command set than the scripting language otherwise used +with +.Xr ld . +GNU +.Xr ld +supports the most commonly used MRI linker commands; these commands are described +here. +.Pp +In general, MRI scripts aren't of much use with the +.Li a.out +object file format, since it only has three sections and MRI scripts lack +some features to make use of them. +.Pp +You can specify a file containing an MRI-compatible script using the +.Li -c +command-line option. +.Pp +Each command in an MRI-compatible script occupies its own line; each command +line starts with the keyword that identifies the command (though blank lines +are also allowed for punctuation). If a line of an MRI-compatible script begins +with an unrecognized keyword, +.Xr ld +issues a warning message, but continues processing the script. +.Pp +Lines beginning with +.Li * +are comments. +.Pp +You can write these commands using all upper-case letters, or all lower case; +for example, +.Li chip +is the same as +.Li CHIP . +The following list shows only the upper-case form of each command. +.Pp +.Bl -tag -width Ds +.It ABSOLUTE Va secname +.It ABSOLUTE Va secname, Va secname, ... Va secname +Normally, +.Xr ld +includes in the output file all sections from all the input files. However, +in an MRI-compatible script, you can use the +.Li ABSOLUTE +command to restrict the sections that will be present in your output program. +If the +.Li ABSOLUTE +command is used at all in a script, then only the sections named explicitly +in +.Li ABSOLUTE +commands will appear in the linker output. You can still use other input sections +(whatever you select on the command line, or using +.Li LOAD ) +to resolve addresses in the output file. +.Pp +.It ALIAS Va out-secname, Va in-secname +Use this command to place the data from input section +.Va in-secname +in a section called +.Va out-secname +in the linker output file. +.Pp +.Va in-secname +may be an integer. +.Pp +.It ALIGN Va secname = Va expression +Align the section called +.Va secname +to +.Va expression . +The +.Va expression +should be a power of two. +.Pp +.It BASE Va expression +Use the value of +.Va expression +as the lowest address (other than absolute addresses) in the output file. +.Pp +.It CHIP Va expression +.It CHIP Va expression, Va expression +This command does nothing; it is accepted only for compatibility. +.Pp +.It END +This command does nothing whatever; it's only accepted for compatibility. +.Pp +.It FORMAT Va output-format +Similar to the +.Li OUTPUT_FORMAT +command in the more general linker language, but restricted to one of these +output formats: +.Pp +.Bl -enum +.It +S-records, if +.Va output-format +is +.Li S +.Pp +.It +IEEE, if +.Va output-format +is +.Li IEEE +.Pp +.It +COFF (the +.Li coff-m68k +variant in BFD), if +.Va output-format +is +.Li COFF +.El +.Pp +.It LIST Va anything... +Print (to the standard output file) a link map, as produced by the +.Xr ld +command-line option +.Li -M . +.Pp +The keyword +.Li LIST +may be followed by anything on the same line, with no change in its effect. +.Pp +.It LOAD Va filename +.It LOAD Va filename, Va filename, ... Va filename +Include one or more object file +.Va filename +in the link; this has the same effect as specifying +.Va filename +directly on the +.Xr ld +command line. +.Pp +.It NAME Va output-name +.Va output-name +is the name for the program produced by +.Xr ld ; +the MRI-compatible command +.Li NAME +is equivalent to the command-line option +.Li -o +or the general script language command +.Li OUTPUT . +.Pp +.It ORDER Va secname, Va secname, ... Va secname +.It ORDER Va secname Va secname Va secname +Normally, +.Xr ld +orders the sections in its output file in the order in which they first appear +in the input files. In an MRI-compatible script, you can override this ordering +with the +.Li ORDER +command. The sections you list with +.Li ORDER +will appear first in your output file, in the order specified. +.Pp +.It PUBLIC Va name= Va expression +.It PUBLIC Va name, Va expression +.It PUBLIC Va name Va expression +Supply a value ( +.Va expression ) +for external symbol +.Va name +used in the linker input files. +.Pp +.It SECT Va secname, Va expression +.It SECT Va secname= Va expression +.It SECT Va secname Va expression +You can use any of these three forms of the +.Li SECT +command to specify the start address ( +.Va expression ) +for section +.Va secname . +If you have more than one +.Li SECT +statement for the same +.Va secname , +only the +.Em first +sets the start address. +.El +.Pp +.Sh GNU Free Documentation License +.Bd -filled -offset indent +Copyright (C) 2000, 2003 Free Software Foundation, Inc. 51 Franklin Street, +Fifth Floor, Boston, MA 02110-1301 USA +.Pp +Everyone is permitted to copy and distribute verbatim copies of this license +document, but changing it is not allowed. +.Ed +.Pp +.Bl -enum +.It +PREAMBLE +.Pp +The purpose of this License is to make a manual, textbook, or other written +document \(lqfree\(rq in the sense of freedom: to assure everyone the effective freedom +to copy and redistribute it, with or without modifying it, either commercially +or noncommercially. Secondarily, this License preserves for the author and +publisher a way to get credit for their work, while not being considered responsible +for modifications made by others. +.Pp +This License is a kind of \(lqcopyleft\(rq, which means that derivative works of the +document must themselves be free in the same sense. It complements the GNU +General Public License, which is a copyleft license designed for free software. +.Pp +We have designed this License in order to use it for manuals for free software, +because free software needs free documentation: a free program should come +with manuals providing the same freedoms that the software does. But this +License is not limited to software manuals; it can be used for any textual +work, regardless of subject matter or whether it is published as a printed +book. We recommend this License principally for works whose purpose is instruction +or reference. +.Pp +.It +APPLICABILITY AND DEFINITIONS +.Pp +This License applies to any manual or other work that contains a notice placed +by the copyright holder saying it can be distributed under the terms of this +License. The \(lqDocument\(rq, below, refers to any such manual or work. Any member +of the public is a licensee, and is addressed as \(lqyou.\(rq +.Pp +A \(lqModified Version\(rq of the Document means any work containing the Document +or a portion of it, either copied verbatim, or with modifications and/or translated +into another language. +.Pp +A \(lqSecondary Section\(rq is a named appendix or a front-matter section of the Document +that deals exclusively with the relationship of the publishers or authors +of the Document to the Document's overall subject (or to related matters) +and contains nothing that could fall directly within that overall subject. +(For example, if the Document is in part a textbook of mathematics, a Secondary +Section may not explain any mathematics.) The relationship could be a matter +of historical connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding them. +.Pp +The \(lqInvariant Sections\(rq are certain Secondary Sections whose titles are designated, +as being those of Invariant Sections, in the notice that says that the Document +is released under this License. +.Pp +The \(lqCover Texts\(rq are certain short passages of text that are listed, as Front-Cover +Texts or Back-Cover Texts, in the notice that says that the Document is released +under this License. +.Pp +A \(lqTransparent\(rq copy of the Document means a machine-readable copy, represented +in a format whose specification is available to the general public, whose +contents can be viewed and edited directly and straightforwardly with generic +text editors or (for images composed of pixels) generic paint programs or +(for drawings) some widely available drawing editor, and that is suitable +for input to text formatters or for automatic translation to a variety of +formats suitable for input to text formatters. A copy made in an otherwise +Transparent file format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is not +\(lqTransparent\(rq is called \(lqOpaque.\(rq +.Pp +Examples of suitable formats for Transparent copies include plain ASCII without +markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly +available DTD, and standard-conforming simple HTML designed for human modification. +Opaque formats include PostScript, PDF, proprietary formats that can be read +and edited only by proprietary word processors, SGML or XML for which the +DTD and/or processing tools are not generally available, and the machine-generated +HTML produced by some word processors for output purposes only. +.Pp +The \(lqTitle Page\(rq means, for a printed book, the title page itself, plus such +following pages as are needed to hold, legibly, the material this License +requires to appear in the title page. For works in formats which do not have +any title page as such, \(lqTitle Page\(rq means the text near the most prominent +appearance of the work's title, preceding the beginning of the body of the +text. +.Pp +.It +VERBATIM COPYING +.Pp +You may copy and distribute the Document in any medium, either commercially +or noncommercially, provided that this License, the copyright notices, and +the license notice saying this License applies to the Document are reproduced +in all copies, and that you add no other conditions whatsoever to those of +this License. You may not use technical measures to obstruct or control the +reading or further copying of the copies you make or distribute. However, +you may accept compensation in exchange for copies. If you distribute a large +enough number of copies you must also follow the conditions in section 3. +.Pp +You may also lend copies, under the same conditions stated above, and you +may publicly display copies. +.Pp +.It +COPYING IN QUANTITY +.Pp +If you publish printed copies of the Document numbering more than 100, and +the Document's license notice requires Cover Texts, you must enclose the copies +in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover +Texts on the front cover, and Back-Cover Texts on the back cover. Both covers +must also clearly and legibly identify you as the publisher of these copies. +The front cover must present the full title with all words of the title equally +prominent and visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve the title +of the Document and satisfy these conditions, can be treated as verbatim copying +in other respects. +.Pp +If the required texts for either cover are too voluminous to fit legibly, +you should put the first ones listed (as many as fit reasonably) on the actual +cover, and continue the rest onto adjacent pages. +.Pp +If you publish or distribute Opaque copies of the Document numbering more +than 100, you must either include a machine-readable Transparent copy along +with each Opaque copy, or state in or with each Opaque copy a publicly-accessible +computer-network location containing a complete Transparent copy of the Document, +free of added material, which the general network-using public has access +to download anonymously at no charge using public-standard network protocols. +If you use the latter option, you must take reasonably prudent steps, when +you begin distribution of Opaque copies in quantity, to ensure that this Transparent +copy will remain thus accessible at the stated location until at least one +year after the last time you distribute an Opaque copy (directly or through +your agents or retailers) of that edition to the public. +.Pp +It is requested, but not required, that you contact the authors of the Document +well before redistributing any large number of copies, to give them a chance +to provide you with an updated version of the Document. +.Pp +.It +MODIFICATIONS +.Pp +You may copy and distribute a Modified Version of the Document under the conditions +of sections 2 and 3 above, provided that you release the Modified Version +under precisely this License, with the Modified Version filling the role of +the Document, thus licensing distribution and modification of the Modified +Version to whoever possesses a copy of it. In addition, you must do these +things in the Modified Version: +.Pp +A. Use in the Title Page (and on the covers, if any) a title distinct from +that of the Document, and from those of previous versions (which should, if +there were any, be listed in the History section of the Document). You may +use the same title as a previous version if the original publisher of that +version gives permission. B. List on the Title Page, as authors, one or more +persons or entities responsible for authorship of the modifications in the +Modified Version, together with at least five of the principal authors of +the Document (all of its principal authors, if it has less than five). C. +State on the Title page the name of the publisher of the Modified Version, +as the publisher. D. Preserve all the copyright notices of the Document. +E. Add an appropriate copyright notice for your modifications adjacent to +the other copyright notices. F. Include, immediately after the copyright +notices, a license notice giving the public permission to use the Modified +Version under the terms of this License, in the form shown in the Addendum +below. G. Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. H. Include +an unaltered copy of this License. I. Preserve the section entitled \(lqHistory\(rq, +and its title, and add to it an item stating at least the title, year, new +authors, and publisher of the Modified Version as given on the Title Page. +If there is no section entitled \(lqHistory\(rq in the Document, create one stating +the title, year, authors, and publisher of the Document as given on its Title +Page, then add an item describing the Modified Version as stated in the previous +sentence. J. Preserve the network location, if any, given in the Document +for public access to a Transparent copy of the Document, and likewise the +network locations given in the Document for previous versions it was based +on. These may be placed in the \(lqHistory\(rq section. You may omit a network location +for a work that was published at least four years before the Document itself, +or if the original publisher of the version it refers to gives permission. +K. In any section entitled \(lqAcknowledgements\(rq or \(lqDedications\(rq, preserve the section's +title, and preserve in the section all the substance and tone of each of the +contributor acknowledgements and/or dedications given therein. L. Preserve +all the Invariant Sections of the Document, unaltered in their text and in +their titles. Section numbers or the equivalent are not considered part of +the section titles. M. Delete any section entitled \(lqEndorsements.\(rq Such a section +may not be included in the Modified Version. N. Do not retitle any existing +section as \(lqEndorsements\(rq or to conflict in title with any Invariant Section. +.Pp +If the Modified Version includes new front-matter sections or appendices that +qualify as Secondary Sections and contain no material copied from the Document, +you may at your option designate some or all of these sections as invariant. +To do this, add their titles to the list of Invariant Sections in the Modified +Version's license notice. These titles must be distinct from any other section +titles. +.Pp +You may add a section entitled \(lqEndorsements\(rq, provided it contains nothing +but endorsements of your Modified Version by various parties--for example, +statements of peer review or that the text has been approved by an organization +as the authoritative definition of a standard. +.Pp +You may add a passage of up to five words as a Front-Cover Text, and a passage +of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts +in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover +Text may be added by (or through arrangements made by) any one entity. If +the Document already includes a cover text for the same cover, previously +added by you or by arrangement made by the same entity you are acting on behalf +of, you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. +.Pp +The author(s) and publisher(s) of the Document do not by this License give +permission to use their names for publicity for or to assert or imply endorsement +of any Modified Version. +.Pp +.It +COMBINING DOCUMENTS +.Pp +You may combine the Document with other documents released under this License, +under the terms defined in section 4 above for modified versions, provided +that you include in the combination all of the Invariant Sections of all of +the original documents, unmodified, and list them all as Invariant Sections +of your combined work in its license notice. +.Pp +The combined work need only contain one copy of this License, and multiple +identical Invariant Sections may be replaced with a single copy. If there +are multiple Invariant Sections with the same name but different contents, +make the title of each such section unique by adding at the end of it, in +parentheses, the name of the original author or publisher of that section +if known, or else a unique number. Make the same adjustment to the section +titles in the list of Invariant Sections in the license notice of the combined +work. +.Pp +In the combination, you must combine any sections entitled \(lqHistory\(rq in the +various original documents, forming one section entitled \(lqHistory\(rq; likewise +combine any sections entitled \(lqAcknowledgements\(rq, and any sections entitled +\(lqDedications.\(rq You must delete all sections entitled \(lqEndorsements.\(rq +.Pp +.It +COLLECTIONS OF DOCUMENTS +.Pp +You may make a collection consisting of the Document and other documents released +under this License, and replace the individual copies of this License in the +various documents with a single copy that is included in the collection, provided +that you follow the rules of this License for verbatim copying of each of +the documents in all other respects. +.Pp +You may extract a single document from such a collection, and distribute it +individually under this License, provided you insert a copy of this License +into the extracted document, and follow this License in all other respects +regarding verbatim copying of that document. +.Pp +.It +AGGREGATION WITH INDEPENDENT WORKS +.Pp +A compilation of the Document or its derivatives with other separate and independent +documents or works, in or on a volume of a storage or distribution medium, +does not as a whole count as a Modified Version of the Document, provided +no compilation copyright is claimed for the compilation. Such a compilation +is called an \(lqaggregate\(rq, and this License does not apply to the other self-contained +works thus compiled with the Document, on account of their being thus compiled, +if they are not themselves derivative works of the Document. +.Pp +If the Cover Text requirement of section 3 is applicable to these copies of +the Document, then if the Document is less than one quarter of the entire +aggregate, the Document's Cover Texts may be placed on covers that surround +only the Document within the aggregate. Otherwise they must appear on covers +around the whole aggregate. +.Pp +.It +TRANSLATION +.Pp +Translation is considered a kind of modification, so you may distribute translations +of the Document under the terms of section 4. Replacing Invariant Sections +with translations requires special permission from their copyright holders, +but you may include translations of some or all Invariant Sections in addition +to the original versions of these Invariant Sections. You may include a translation +of this License provided that you also include the original English version +of this License. In case of a disagreement between the translation and the +original English version of this License, the original English version will +prevail. +.Pp +.It +TERMINATION +.Pp +You may not copy, modify, sublicense, or distribute the Document except as +expressly provided for under this License. Any other attempt to copy, modify, +sublicense or distribute the Document is void, and will automatically terminate +your rights under this License. However, parties who have received copies, +or rights, from you under this License will not have their licenses terminated +so long as such parties remain in full compliance. +.Pp +.It +FUTURE REVISIONS OF THIS LICENSE +.Pp +The Free Software Foundation may publish new, revised versions of the GNU +Free Documentation License from time to time. Such new versions will be similar +in spirit to the present version, but may differ in detail to address new +problems or concerns. See http://www.gnu.org/copyleft/. +.Pp +Each version of the License is given a distinguishing version number. If the +Document specifies that a particular numbered version of this License \(lqor any +later version\(rq applies to it, you have the option of following the terms and +conditions either of that specified version or of any later version that has +been published (not as a draft) by the Free Software Foundation. If the Document +does not specify a version number of this License, you may choose any version +ever published (not as a draft) by the Free Software Foundation. +.Pp +.El +.Ss ADDENDUM: How to use this License for your documents +To use this License in a document you have written, include a copy of the +License in the document and put the following copyright and license notices +just after the title page: +.Pp +.Bd -literal -offset indent + +Copyright (C) year your name. +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 +or any later version published by the Free Software Foundation; +with the Invariant Sections being list their titles, with the +Front-Cover Texts being list, and with the Back-Cover Texts being list. +A copy of the license is included in the section entitled "GNU +Free Documentation License." + +.Ed +.Pp +If you have no Invariant Sections, write \(lqwith no Invariant Sections\(rq instead +of saying which ones are invariant. If you have no Front-Cover Texts, write +\(lqno Front-Cover Texts\(rq instead of \(lqFront-Cover Texts being +.Va list +\(rq; likewise for Back-Cover Texts. +.Pp +If your document contains nontrivial examples of program code, we recommend +releasing these examples in parallel under your choice of free software license, +such as the GNU General Public License, to permit their use in free software. +.Pp +.Sh LD Index diff --git a/contrib/binutils/ld/ldint.7 b/contrib/binutils/ld/ldint.7 new file mode 100644 index 0000000..6c17af4 --- /dev/null +++ b/contrib/binutils/ld/ldint.7 @@ -0,0 +1,1277 @@ +.Dd 2015-03-02 +.Dt LDINT 7 +.Os +.Sh NAME +.Nm ldint +.Nd GNU Linker Internals +.Sh +This file documents the internals of the GNU linker +.Li ld . +It is a collection of miscellaneous information with little form at this point. +Mostly, it is a repository into which you can put information about GNU +.Li ld +as you discover it (or as you design changes to +.Li ld ) . +.Pp +This document is distributed under the terms of the GNU Free Documentation +License. A copy of the license is included in the section entitled "GNU Free +Documentation License". +.Pp +.Sh The Pa README File +Check the +.Pa README +file; it often has useful information that does not appear anywhere else in +the directory. +.Pp +.Sh How linker emulations are generated +Each linker target has an +.Em emulation . +The emulation includes the default linker script, and certain emulations also +modify certain types of linker behaviour. +.Pp +Emulations are created during the build process by the shell script +.Pa genscripts.sh . +.Pp +The +.Pa genscripts.sh +script starts by reading a file in the +.Pa emulparams +directory. This is a shell script which sets various shell variables used +by +.Pa genscripts.sh +and the other shell scripts it invokes. +.Pp +The +.Pa genscripts.sh +script will invoke a shell script in the +.Pa scripttempl +directory in order to create default linker scripts written in the linker +command language. The +.Pa scripttempl +script will be invoked 5 (or, in some cases, 6) times, with different assignments +to shell variables, to create different default scripts. The choice of script +is made based on the command line options. +.Pp +After creating the scripts, +.Pa genscripts.sh +will invoke yet another shell script, this time in the +.Pa emultempl +directory. That shell script will create the emulation source file, which +contains C code. This C code permits the linker emulation to override various +linker behaviours. Most targets use the generic emulation code, which is in +.Pa emultempl/generic.em . +.Pp +To summarize, +.Pa genscripts.sh +reads three shell scripts: an emulation parameters script in the +.Pa emulparams +directory, a linker script generation script in the +.Pa scripttempl +directory, and an emulation source file generation script in the +.Pa emultempl +directory. +.Pp +For example, the Sun 4 linker sets up variables in +.Pa emulparams/sun4.sh , +creates linker scripts using +.Pa scripttempl/aout.sc , +and creates the emulation code using +.Pa emultempl/sunos.em . +.Pp +Note that the linker can support several emulations simultaneously, depending +upon how it is configured. An emulation can be selected with the +.Li -m +option. The +.Li -V +option will list all supported emulations. +.Pp +.Ss Pa emulparams scripts +Each target selects a particular file in the +.Pa emulparams +directory by setting the shell variable +.Li targ_emul +in +.Pa configure.tgt . +This shell variable is used by the +.Pa configure +script to control building an emulation source file. +.Pp +Certain conventions are enforced. Suppose the +.Li targ_emul +variable is set to +.Va emul +in +.Pa configure.tgt . +The name of the emulation shell script will be +.Pa emulparams/ Va emul.sh . +The +.Pa Makefile +must have a target named +.Pa e Va emul.c ; +this target must depend upon +.Pa emulparams/ Va emul.sh , +as well as the appropriate scripts in the +.Pa scripttempl +and +.Pa emultempl +directories. The +.Pa Makefile +target must invoke +.Li GENSCRIPTS +with two arguments: +.Va emul , +and the value of the make variable +.Li tdir_ Va emul . +The value of the latter variable will be set by the +.Pa configure +script, and is used to set the default target directory to search. +.Pp +By convention, the +.Pa emulparams/ Va emul.sh +shell script should only set shell variables. It may set shell variables which +are to be interpreted by the +.Pa scripttempl +and the +.Pa emultempl +scripts. Certain shell variables are interpreted directly by the +.Pa genscripts.sh +script. +.Pp +Here is a list of shell variables interpreted by +.Pa genscripts.sh , +as well as some conventional shell variables interpreted by the +.Pa scripttempl +and +.Pa emultempl +scripts. +.Pp +.Bl -tag -width Ds +.It SCRIPT_NAME +This is the name of the +.Pa scripttempl +script to use. If +.Li SCRIPT_NAME +is set to +.Va script , +.Pa genscripts.sh +will use the script +.Pa scripttempl/ Va script.sc . +.Pp +.It TEMPLATE_NAME +This is the name of the +.Pa emultempl +script to use. If +.Li TEMPLATE_NAME +is set to +.Va template , +.Pa genscripts.sh +will use the script +.Pa emultempl/ Va template.em . +If this variable is not set, the default value is +.Li generic . +.Pp +.It GENERATE_SHLIB_SCRIPT +If this is set to a nonempty string, +.Pa genscripts.sh +will invoke the +.Pa scripttempl +script an extra time to create a shared library script. linker scripts. +.Pp +.It OUTPUT_FORMAT +This is normally set to indicate the BFD output format use (e.g., +.Li "a.out-sunos-big" . +The +.Pa scripttempl +script will normally use it in an +.Li OUTPUT_FORMAT +expression in the linker script. +.Pp +.It ARCH +This is normally set to indicate the architecture to use (e.g., +.Li sparc ) . +The +.Pa scripttempl +script will normally use it in an +.Li OUTPUT_ARCH +expression in the linker script. +.Pp +.It ENTRY +Some +.Pa scripttempl +scripts use this to set the entry address, in an +.Li ENTRY +expression in the linker script. +.Pp +.It TEXT_START_ADDR +Some +.Pa scripttempl +scripts use this to set the start address of the +.Li .text +section. +.Pp +.It NONPAGED_TEXT_START_ADDR +If this is defined, the +.Pa genscripts.sh +script sets +.Li TEXT_START_ADDR +to its value before running the +.Pa scripttempl +script for the +.Li -n +and +.Li -N +options (see Section +.Dq linker scripts ) . +.Pp +.It SEGMENT_SIZE +The +.Pa genscripts.sh +script uses this to set the default value of +.Li DATA_ALIGNMENT +when running the +.Pa scripttempl +script. +.Pp +.It TARGET_PAGE_SIZE +If +.Li SEGMENT_SIZE +is not defined, the +.Pa genscripts.sh +script uses this to define it. +.Pp +.It ALIGNMENT +Some +.Pa scripttempl +scripts set this to a number to pass to +.Li ALIGN +to set the required alignment for the +.Li end +symbol. +.El +.Pp +.Ss Pa scripttempl scripts +Each linker target uses a +.Pa scripttempl +script to generate the default linker scripts. The name of the +.Pa scripttempl +script is set by the +.Li SCRIPT_NAME +variable in the +.Pa emulparams +script. If +.Li SCRIPT_NAME +is set to +.Va script , +.Li genscripts.sh +will invoke +.Pa scripttempl/ Va script.sc . +.Pp +The +.Pa genscripts.sh +script will invoke the +.Pa scripttempl +script 5 to 8 times. Each time it will set the shell variable +.Li LD_FLAG +to a different value. When the linker is run, the options used will direct +it to select a particular script. (Script selection is controlled by the +.Li get_script +emulation entry point; this describes the conventional behaviour). +.Pp +The +.Pa scripttempl +script should just write a linker script, written in the linker command language, +to standard output. If the emulation name--the name of the +.Pa emulparams +file without the +.Pa .sc +extension--is +.Va emul , +then the output will be directed to +.Pa ldscripts/ Va emul. Va extension +in the build directory, where +.Va extension +changes each time the +.Pa scripttempl +script is invoked. +.Pp +Here is the list of values assigned to +.Li LD_FLAG . +.Pp +.Bl -tag -width Ds +.It (empty) +The script generated is used by default (when none of the following cases +apply). The output has an extension of +.Pa .x . +.It n +The script generated is used when the linker is invoked with the +.Li -n +option. The output has an extension of +.Pa .xn . +.It N +The script generated is used when the linker is invoked with the +.Li -N +option. The output has an extension of +.Pa .xbn . +.It r +The script generated is used when the linker is invoked with the +.Li -r +option. The output has an extension of +.Pa .xr . +.It u +The script generated is used when the linker is invoked with the +.Li -Ur +option. The output has an extension of +.Pa .xu . +.It shared +The +.Pa scripttempl +script is only invoked with +.Li LD_FLAG +set to this value if +.Li GENERATE_SHLIB_SCRIPT +is defined in the +.Pa emulparams +file. The +.Pa emultempl +script must arrange to use this script at the appropriate time, normally when +the linker is invoked with the +.Li -shared +option. The output has an extension of +.Pa .xs . +.It c +The +.Pa scripttempl +script is only invoked with +.Li LD_FLAG +set to this value if +.Li GENERATE_COMBRELOC_SCRIPT +is defined in the +.Pa emulparams +file or if +.Li SCRIPT_NAME +is +.Li elf . +The +.Pa emultempl +script must arrange to use this script at the appropriate time, normally when +the linker is invoked with the +.Li -z combreloc +option. The output has an extension of +.Pa .xc . +.It cshared +The +.Pa scripttempl +script is only invoked with +.Li LD_FLAG +set to this value if +.Li GENERATE_COMBRELOC_SCRIPT +is defined in the +.Pa emulparams +file or if +.Li SCRIPT_NAME +is +.Li elf +and +.Li GENERATE_SHLIB_SCRIPT +is defined in the +.Pa emulparams +file. The +.Pa emultempl +script must arrange to use this script at the appropriate time, normally when +the linker is invoked with the +.Li -shared -z combreloc +option. The output has an extension of +.Pa .xsc . +.El +.Pp +Besides the shell variables set by the +.Pa emulparams +script, and the +.Li LD_FLAG +variable, the +.Pa genscripts.sh +script will set certain variables for each run of the +.Pa scripttempl +script. +.Pp +.Bl -tag -width Ds +.It RELOCATING +This will be set to a non-empty string when the linker is doing a final relocation +(e.g., all scripts other than +.Li -r +and +.Li -Ur ) . +.Pp +.It CONSTRUCTING +This will be set to a non-empty string when the linker is building global +constructor and destructor tables (e.g., all scripts other than +.Li -r ) . +.Pp +.It DATA_ALIGNMENT +This will be set to an +.Li ALIGN +expression when the output should be page aligned, or to +.Li . +when generating the +.Li -N +script. +.Pp +.It CREATE_SHLIB +This will be set to a non-empty string when generating a +.Li -shared +script. +.Pp +.It COMBRELOC +This will be set to a non-empty string when generating +.Li -z combreloc +scripts to a temporary file name which can be used during script generation. +.El +.Pp +The conventional way to write a +.Pa scripttempl +script is to first set a few shell variables, and then write out a linker +script using +.Li cat +with a here document. The linker script will use variable substitutions, based +on the above variables and those set in the +.Pa emulparams +script, to control its behaviour. +.Pp +When there are parts of the +.Pa scripttempl +script which should only be run when doing a final relocation, they should +be enclosed within a variable substitution based on +.Li RELOCATING . +For example, on many targets special symbols such as +.Li _end +should be defined when doing a final link. Naturally, those symbols should +not be defined when doing a relocatable link using +.Li -r . +The +.Pa scripttempl +script could use a construct like this to define those symbols: +.Bd -literal -offset indent + ${RELOCATING+ _end = .;} +.Ed +This will do the symbol assignment only if the +.Li RELOCATING +variable is defined. +.Pp +The basic job of the linker script is to put the sections in the correct order, +and at the correct memory addresses. For some targets, the linker script may +have to do some other operations. +.Pp +For example, on most MIPS platforms, the linker is responsible for defining +the special symbol +.Li _gp , +used to initialize the +.Li $gp +register. It must be set to the start of the small data section plus +.Li 0x8000 . +Naturally, it should only be defined when doing a final relocation. This will +typically be done like this: +.Bd -literal -offset indent + ${RELOCATING+ _gp = ALIGN(16) + 0x8000;} +.Ed +This line would appear just before the sections which compose the small data +section ( +.Li .sdata , +.Li .sbss ) . +All those sections would be contiguous in memory. +.Pp +Many COFF systems build constructor tables in the linker script. The compiler +will arrange to output the address of each global constructor in a +.Li .ctor +section, and the address of each global destructor in a +.Li .dtor +section (this is done by defining +.Li ASM_OUTPUT_CONSTRUCTOR +and +.Li ASM_OUTPUT_DESTRUCTOR +in the +.Li gcc +configuration files). The +.Li gcc +runtime support routines expect the constructor table to be named +.Li __CTOR_LIST__ . +They expect it to be a list of words, with the first word being the count +of the number of entries. There should be a trailing zero word. (Actually, +the count may be -1 if the trailing word is present, and the trailing word +may be omitted if the count is correct, but, as the +.Li gcc +behaviour has changed slightly over the years, it is safest to provide both). +Here is a typical way that might be handled in a +.Pa scripttempl +file. +.Bd -literal -offset indent + ${CONSTRUCTING+ __CTOR_LIST__ = .;} + ${CONSTRUCTING+ LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)} + ${CONSTRUCTING+ *(.ctors)} + ${CONSTRUCTING+ LONG(0)} + ${CONSTRUCTING+ __CTOR_END__ = .;} + ${CONSTRUCTING+ __DTOR_LIST__ = .;} + ${CONSTRUCTING+ LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)} + ${CONSTRUCTING+ *(.dtors)} + ${CONSTRUCTING+ LONG(0)} + ${CONSTRUCTING+ __DTOR_END__ = .;} +.Ed +The use of +.Li CONSTRUCTING +ensures that these linker script commands will only appear when the linker +is supposed to be building the constructor and destructor tables. This example +is written for a target which uses 4 byte pointers. +.Pp +Embedded systems often need to set a stack address. This is normally best +done by using the +.Li PROVIDE +construct with a default stack address. This permits the user to easily override +the stack address using the +.Li --defsym +option. Here is an example: +.Bd -literal -offset indent + ${RELOCATING+ PROVIDE (__stack = 0x80000000);} +.Ed +The value of the symbol +.Li __stack +would then be used in the startup code to initialize the stack pointer. +.Pp +.Ss Pa emultempl scripts +Each linker target uses an +.Pa emultempl +script to generate the emulation code. The name of the +.Pa emultempl +script is set by the +.Li TEMPLATE_NAME +variable in the +.Pa emulparams +script. If the +.Li TEMPLATE_NAME +variable is not set, the default is +.Li generic . +If the value of +.Li TEMPLATE_NAME +is +.Va template , +.Pa genscripts.sh +will use +.Pa emultempl/ Va template.em . +.Pp +Most targets use the generic +.Pa emultempl +script, +.Pa emultempl/generic.em . +A different +.Pa emultempl +script is only needed if the linker must support unusual actions, such as +linking against shared libraries. +.Pp +The +.Pa emultempl +script is normally written as a simple invocation of +.Li cat +with a here document. The document will use a few variable substitutions. +Typically each function names uses a substitution involving +.Li EMULATION_NAME , +for ease of debugging when the linker supports multiple emulations. +.Pp +Every function and variable in the emitted file should be static. The only +globally visible object must be named +.Li ld_ Va EMULATION_NAME_emulation , +where +.Va EMULATION_NAME +is the name of the emulation set in +.Pa configure.tgt +(this is also the name of the +.Pa emulparams +file without the +.Pa .sh +extension). The +.Pa genscripts.sh +script will set the shell variable +.Li EMULATION_NAME +before invoking the +.Pa emultempl +script. +.Pp +The +.Li ld_ Va EMULATION_NAME_emulation +variable must be a +.Li struct ld_emulation_xfer_struct , +as defined in +.Pa ldemul.h . +It defines a set of function pointers which are invoked by the linker, as +well as strings for the emulation name (normally set from the shell variable +.Li EMULATION_NAME +and the default BFD target name (normally set from the shell variable +.Li OUTPUT_FORMAT +which is normally set by the +.Pa emulparams +file). +.Pp +The +.Pa genscripts.sh +script will set the shell variable +.Li COMPILE_IN +when it invokes the +.Pa emultempl +script for the default emulation. In this case, the +.Pa emultempl +script should include the linker scripts directly, and return them from the +.Li get_scripts +entry point. When the emulation is not the default, the +.Li get_scripts +entry point should just return a file name. See +.Pa emultempl/generic.em +for an example of how this is done. +.Pp +At some point, the linker emulation entry points should be documented. +.Pp +.Sh A Walkthrough of a Typical Emulation +This chapter is to help people who are new to the way emulations interact +with the linker, or who are suddenly thrust into the position of having to +work with existing emulations. It will discuss the files you need to be aware +of. It will tell you when the given "hooks" in the emulation will be called. +It will, hopefully, give you enough information about when and how things +happen that you'll be able to get by. As always, the source is the definitive +reference to this. +.Pp +The starting point for the linker is in +.Pa ldmain.c +where +.Li main +is defined. The bulk of the code that's emulation specific will initially +be in +.Li emultempl/ Va emulation.em +but will end up in +.Li e Va emulation.c +when the build is done. Most of the work to select and interface with emulations +is in +.Li ldemul.h +and +.Li ldemul.c . +Specifically, +.Li ldemul.h +defines the +.Li ld_emulation_xfer_struct +structure your emulation exports. +.Pp +Your emulation file exports a symbol +.Li ld_ Va EMULATION_NAME_emulation . +If your emulation is selected (it usually is, since usually there's only one), +.Li ldemul.c +sets the variable +.Va ld_emulation +to point to it. +.Li ldemul.c +also defines a number of API functions that interface to your emulation, like +.Li ldemul_after_parse +which simply calls your +.Li ld_ Va EMULATION_emulation.after_parse +function. For the rest of this section, the functions will be mentioned, but +you should assume the indirect reference to your emulation also. +.Pp +We will also skip or gloss over parts of the link process that don't relate +to emulations, like setting up internationalization. +.Pp +After initialization, +.Li main +selects an emulation by pre-scanning the command line arguments. It calls +.Li ldemul_choose_target +to choose a target. If you set +.Li choose_target +to +.Li ldemul_default_target , +it picks your +.Li target_name +by default. +.Pp +.Li main +calls +.Li ldemul_before_parse , +then +.Li parse_args . +.Li parse_args +calls +.Li ldemul_parse_args +for each arg, which must update the +.Li getopt +globals if it recognizes the argument. If the emulation doesn't recognize +it, then parse_args checks to see if it recognizes it. +.Pp +Now that the emulation has had access to all its command-line options, +.Li main +calls +.Li ldemul_set_symbols . +This can be used for any initialization that may be affected by options. It +is also supposed to set up any variables needed by the emulation script. +.Pp +.Li main +now calls +.Li ldemul_get_script +to get the emulation script to use (based on arguments, no doubt,see Section +.Dq Emulations ) +and runs it. While parsing, +.Li ldgram.y +may call +.Li ldemul_hll +or +.Li ldemul_syslib +to handle the +.Li HLL +or +.Li SYSLIB +commands. It may call +.Li ldemul_unrecognized_file +if you asked the linker to link a file it doesn't recognize. It will call +.Li ldemul_recognized_file +for each file it does recognize, in case the emulation wants to handle some +files specially. All the while, it's loading the files (possibly calling +.Li ldemul_open_dynamic_archive ) +and symbols and stuff. After it's done reading the script, +.Li main +calls +.Li ldemul_after_parse . +Use the after-parse hook to set up anything that depends on stuff the script +might have set up, like the entry point. +.Pp +.Li main +next calls +.Li lang_process +in +.Li ldlang.c . +This appears to be the main core of the linking itself, as far as emulation +hooks are concerned(*). It first opens the output file's BFD, calling +.Li ldemul_set_output_arch , +and calls +.Li ldemul_create_output_section_statements +in case you need to use other means to find or create object files (i.e. shared +libraries found on a path, or fake stub objects). Despite the name, nobody +creates output sections here. +.Pp +(*) In most cases, the BFD library does the bulk of the actual linking, handling +symbol tables, symbol resolution, relocations, and building the final output +file. See the BFD reference for all the details. Your emulation is usually +concerned more with managing things at the file and section level, like "put +this here, add this section", etc. +.Pp +Next, the objects to be linked are opened and BFDs created for them, and +.Li ldemul_after_open +is called. At this point, you have all the objects and symbols loaded, but +none of the data has been placed yet. +.Pp +Next comes the Big Linking Thingy (except for the parts BFD does). All input +sections are mapped to output sections according to the script. If a section +doesn't get mapped by default, +.Li ldemul_place_orphan +will get called to figure out where it goes. Next it figures out the offsets +for each section, calling +.Li ldemul_before_allocation +before and +.Li ldemul_after_allocation +after deciding where each input section ends up in the output sections. +.Pp +The last part of +.Li lang_process +is to figure out all the symbols' values. After assigning final values to +the symbols, +.Li ldemul_finish +is called, and after that, any undefined symbols are turned into fatal errors. +.Pp +OK, back to +.Li main , +which calls +.Li ldwrite +in +.Pa ldwrite.c . +.Li ldwrite +calls BFD's final_link, which does all the relocation fixups and writes the +output bfd to disk, and we're done. +.Pp +In summary, +.Pp +.Bl -bullet +.It +.Li main() +in +.Pa ldmain.c +.It +.Pa emultempl/ Va EMULATION.em +has your code +.It +.Li ldemul_choose_target +(defaults to your +.Li target_name ) +.It +.Li ldemul_before_parse +.It +Parse argv, calls +.Li ldemul_parse_args +for each +.It +.Li ldemul_set_symbols +.It +.Li ldemul_get_script +.It +parse script +.Pp +.Bl -bullet +.It +may call +.Li ldemul_hll +or +.Li ldemul_syslib +.It +may call +.Li ldemul_open_dynamic_archive +.El +.Pp +.It +.Li ldemul_after_parse +.It +.Li lang_process() +in +.Pa ldlang.c +.Pp +.Bl -bullet +.It +create +.Li output_bfd +.It +.Li ldemul_set_output_arch +.It +.Li ldemul_create_output_section_statements +.It +read objects, create input bfds - all symbols exist, but have no values +.It +may call +.Li ldemul_unrecognized_file +.It +will call +.Li ldemul_recognized_file +.It +.Li ldemul_after_open +.It +map input sections to output sections +.It +may call +.Li ldemul_place_orphan +for remaining sections +.It +.Li ldemul_before_allocation +.It +gives input sections offsets into output sections, places output sections +.It +.Li ldemul_after_allocation +- section addresses valid +.It +assigns values to symbols +.It +.Li ldemul_finish +- symbol values valid +.El +.Pp +.It +output bfd is written to disk +.Pp +.El +.Sh Some Architecture Specific Notes +This is the place for notes on the behavior of +.Li ld +on specific platforms. Currently, only Intel x86 is documented (and of that, +only the auto-import behavior for DLLs). +.Pp +.Ss Intel x86 +.Bl -tag -width Ds +.Li ld +can create DLLs that operate with various runtimes available on a common x86 +operating system. These runtimes include native (using the mingw "platform"), +cygwin, and pw. +.Pp +.It auto-import from DLLs +.Bl -enum +.It +With this feature on, DLL clients can import variables from DLL without any +concern from their side (for example, without any source code modifications). +Auto-import can be enabled using the +.Li --enable-auto-import +flag, or disabled via the +.Li --disable-auto-import +flag. Auto-import is disabled by default. +.Pp +.It +This is done completely in bounds of the PE specification (to be fair, there's +a minor violation of the spec at one point, but in practice auto-import works +on all known variants of that common x86 operating system) So, the resulting +DLL can be used with any other PE compiler/linker. +.Pp +.It +Auto-import is fully compatible with standard import method, in which variables +are decorated using attribute modifiers. Libraries of either type may be mixed +together. +.Pp +.It +Overhead (space): 8 bytes per imported symbol, plus 20 for each reference +to it; Overhead (load time): negligible; Overhead (virtual/physical memory): +should be less than effect of DLL relocation. +.El +.Pp +Motivation +.Pp +The obvious and only way to get rid of dllimport insanity is to make client +access variable directly in the DLL, bypassing the extra dereference imposed +by ordinary DLL runtime linking. I.e., whenever client contains something +like +.Pp +.Li mov dll_var,%eax, +.Pp +address of dll_var in the command should be relocated to point into loaded +DLL. The aim is to make OS loader do so, and than make ld help with that. +Import section of PE made following way: there's a vector of structures each +describing imports from particular DLL. Each such structure points to two +other parallel vectors: one holding imported names, and one which will hold +address of corresponding imported name. So, the solution is de-vectorize these +structures, making import locations be sparse and pointing directly into code. +.Pp +Implementation +.Pp +For each reference of data symbol to be imported from DLL (to set of which +belong symbols with name <sym>, if __imp_<sym> is found in implib), the import +fixup entry is generated. That entry is of type IMAGE_IMPORT_DESCRIPTOR and +stored in .idata$3 subsection. Each fixup entry contains pointer to symbol's +address within .text section (marked with __fuN_<sym> symbol, where N is integer), +pointer to DLL name (so, DLL name is referenced by multiple entries), and +pointer to symbol name thunk. Symbol name thunk is singleton vector (__nm_th_<symbol>) +pointing to IMAGE_IMPORT_BY_NAME structure (__nm_<symbol>) directly containing +imported name. Here comes that "om the edge" problem mentioned above: PE specification +rambles that name vector (OriginalFirstThunk) should run in parallel with +addresses vector (FirstThunk), i.e. that they should have same number of elements +and terminated with zero. We violate this, since FirstThunk points directly +into machine code. But in practice, OS loader implemented the sane way: it +goes thru OriginalFirstThunk and puts addresses to FirstThunk, not something +else. It once again should be noted that dll and symbol name structures are +reused across fixup entries and should be there anyway to support standard +import stuff, so sustained overhead is 20 bytes per reference. Other question +is whether having several IMAGE_IMPORT_DESCRIPTORS for the same DLL is possible. +Answer is yes, it is done even by native compiler/linker (libth32's functions +are in fact resident in windows9x kernel32.dll, so if you use it, you have +two IMAGE_IMPORT_DESCRIPTORS for kernel32.dll). Yet other question is whether +referencing the same PE structures several times is valid. The answer is why +not, prohibiting that (detecting violation) would require more work on behalf +of loader than not doing it. +.Pp +.El +.Sh GNU Free Documentation License +GNU Free Documentation License Version 1.1, March 2000 +.Pp +Copyright (C) 2000 Free Software Foundation, Inc. 51 Franklin Street, Fifth +Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and distribute +verbatim copies of this license document, but changing it is not allowed. +.Pp +0. PREAMBLE +.Pp +The purpose of this License is to make a manual, textbook, or other written +document "free" in the sense of freedom: to assure everyone the effective +freedom to copy and redistribute it, with or without modifying it, either +commercially or noncommercially. Secondarily, this License preserves for the +author and publisher a way to get credit for their work, while not being considered +responsible for modifications made by others. +.Pp +This License is a kind of "copyleft", which means that derivative works of +the document must themselves be free in the same sense. It complements the +GNU General Public License, which is a copyleft license designed for free +software. +.Pp +We have designed this License in order to use it for manuals for free software, +because free software needs free documentation: a free program should come +with manuals providing the same freedoms that the software does. But this +License is not limited to software manuals; it can be used for any textual +work, regardless of subject matter or whether it is published as a printed +book. We recommend this License principally for works whose purpose is instruction +or reference. +.Pp +1. APPLICABILITY AND DEFINITIONS +.Pp +This License applies to any manual or other work that contains a notice placed +by the copyright holder saying it can be distributed under the terms of this +License. The "Document", below, refers to any such manual or work. Any member +of the public is a licensee, and is addressed as "you". +.Pp +A "Modified Version" of the Document means any work containing the Document +or a portion of it, either copied verbatim, or with modifications and/or translated +into another language. +.Pp +A "Secondary Section" is a named appendix or a front-matter section of the +Document that deals exclusively with the relationship of the publishers or +authors of the Document to the Document's overall subject (or to related matters) +and contains nothing that could fall directly within that overall subject. +(For example, if the Document is in part a textbook of mathematics, a Secondary +Section may not explain any mathematics.) The relationship could be a matter +of historical connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding them. +.Pp +The "Invariant Sections" are certain Secondary Sections whose titles are designated, +as being those of Invariant Sections, in the notice that says that the Document +is released under this License. +.Pp +The "Cover Texts" are certain short passages of text that are listed, as Front-Cover +Texts or Back-Cover Texts, in the notice that says that the Document is released +under this License. +.Pp +A "Transparent" copy of the Document means a machine-readable copy, represented +in a format whose specification is available to the general public, whose +contents can be viewed and edited directly and straightforwardly with generic +text editors or (for images composed of pixels) generic paint programs or +(for drawings) some widely available drawing editor, and that is suitable +for input to text formatters or for automatic translation to a variety of +formats suitable for input to text formatters. A copy made in an otherwise +Transparent file format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is not +"Transparent" is called "Opaque". +.Pp +Examples of suitable formats for Transparent copies include plain ASCII without +markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly +available DTD, and standard-conforming simple HTML designed for human modification. +Opaque formats include PostScript, PDF, proprietary formats that can be read +and edited only by proprietary word processors, SGML or XML for which the +DTD and/or processing tools are not generally available, and the machine-generated +HTML produced by some word processors for output purposes only. +.Pp +The "Title Page" means, for a printed book, the title page itself, plus such +following pages as are needed to hold, legibly, the material this License +requires to appear in the title page. For works in formats which do not have +any title page as such, "Title Page" means the text near the most prominent +appearance of the work's title, preceding the beginning of the body of the +text. +.Pp +2. VERBATIM COPYING +.Pp +You may copy and distribute the Document in any medium, either commercially +or noncommercially, provided that this License, the copyright notices, and +the license notice saying this License applies to the Document are reproduced +in all copies, and that you add no other conditions whatsoever to those of +this License. You may not use technical measures to obstruct or control the +reading or further copying of the copies you make or distribute. However, +you may accept compensation in exchange for copies. If you distribute a large +enough number of copies you must also follow the conditions in section 3. +.Pp +You may also lend copies, under the same conditions stated above, and you +may publicly display copies. +.Pp +3. COPYING IN QUANTITY +.Pp +If you publish printed copies of the Document numbering more than 100, and +the Document's license notice requires Cover Texts, you must enclose the copies +in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover +Texts on the front cover, and Back-Cover Texts on the back cover. Both covers +must also clearly and legibly identify you as the publisher of these copies. +The front cover must present the full title with all words of the title equally +prominent and visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve the title +of the Document and satisfy these conditions, can be treated as verbatim copying +in other respects. +.Pp +If the required texts for either cover are too voluminous to fit legibly, +you should put the first ones listed (as many as fit reasonably) on the actual +cover, and continue the rest onto adjacent pages. +.Pp +If you publish or distribute Opaque copies of the Document numbering more +than 100, you must either include a machine-readable Transparent copy along +with each Opaque copy, or state in or with each Opaque copy a publicly-accessible +computer-network location containing a complete Transparent copy of the Document, +free of added material, which the general network-using public has access +to download anonymously at no charge using public-standard network protocols. +If you use the latter option, you must take reasonably prudent steps, when +you begin distribution of Opaque copies in quantity, to ensure that this Transparent +copy will remain thus accessible at the stated location until at least one +year after the last time you distribute an Opaque copy (directly or through +your agents or retailers) of that edition to the public. +.Pp +It is requested, but not required, that you contact the authors of the Document +well before redistributing any large number of copies, to give them a chance +to provide you with an updated version of the Document. +.Pp +4. MODIFICATIONS +.Pp +You may copy and distribute a Modified Version of the Document under the conditions +of sections 2 and 3 above, provided that you release the Modified Version +under precisely this License, with the Modified Version filling the role of +the Document, thus licensing distribution and modification of the Modified +Version to whoever possesses a copy of it. In addition, you must do these +things in the Modified Version: +.Pp +A. Use in the Title Page (and on the covers, if any) a title distinct from +that of the Document, and from those of previous versions (which should, if +there were any, be listed in the History section of the Document). You may +use the same title as a previous version if the original publisher of that +version gives permission. B. List on the Title Page, as authors, one or more +persons or entities responsible for authorship of the modifications in the +Modified Version, together with at least five of the principal authors of +the Document (all of its principal authors, if it has less than five). C. +State on the Title page the name of the publisher of the Modified Version, +as the publisher. D. Preserve all the copyright notices of the Document. E. +Add an appropriate copyright notice for your modifications adjacent to the +other copyright notices. F. Include, immediately after the copyright notices, +a license notice giving the public permission to use the Modified Version +under the terms of this License, in the form shown in the Addendum below. +G. Preserve in that license notice the full lists of Invariant Sections and +required Cover Texts given in the Document's license notice. H. Include an +unaltered copy of this License. I. Preserve the section entitled "History", +and its title, and add to it an item stating at least the title, year, new +authors, and publisher of the Modified Version as given on the Title Page. +If there is no section entitled "History" in the Document, create one stating +the title, year, authors, and publisher of the Document as given on its Title +Page, then add an item describing the Modified Version as stated in the previous +sentence. J. Preserve the network location, if any, given in the Document +for public access to a Transparent copy of the Document, and likewise the +network locations given in the Document for previous versions it was based +on. These may be placed in the "History" section. You may omit a network location +for a work that was published at least four years before the Document itself, +or if the original publisher of the version it refers to gives permission. +K. In any section entitled "Acknowledgements" or "Dedications", preserve the +section's title, and preserve in the section all the substance and tone of +each of the contributor acknowledgements and/or dedications given therein. +L. Preserve all the Invariant Sections of the Document, unaltered in their +text and in their titles. Section numbers or the equivalent are not considered +part of the section titles. M. Delete any section entitled "Endorsements". +Such a section may not be included in the Modified Version. N. Do not retitle +any existing section as "Endorsements" or to conflict in title with any Invariant +Section. +.Pp +If the Modified Version includes new front-matter sections or appendices that +qualify as Secondary Sections and contain no material copied from the Document, +you may at your option designate some or all of these sections as invariant. +To do this, add their titles to the list of Invariant Sections in the Modified +Version's license notice. These titles must be distinct from any other section +titles. +.Pp +You may add a section entitled "Endorsements", provided it contains nothing +but endorsements of your Modified Version by various parties--for example, +statements of peer review or that the text has been approved by an organization +as the authoritative definition of a standard. +.Pp +You may add a passage of up to five words as a Front-Cover Text, and a passage +of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts +in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover +Text may be added by (or through arrangements made by) any one entity. If +the Document already includes a cover text for the same cover, previously +added by you or by arrangement made by the same entity you are acting on behalf +of, you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. +.Pp +The author(s) and publisher(s) of the Document do not by this License give +permission to use their names for publicity for or to assert or imply endorsement +of any Modified Version. +.Pp +5. COMBINING DOCUMENTS +.Pp +You may combine the Document with other documents released under this License, +under the terms defined in section 4 above for modified versions, provided +that you include in the combination all of the Invariant Sections of all of +the original documents, unmodified, and list them all as Invariant Sections +of your combined work in its license notice. +.Pp +The combined work need only contain one copy of this License, and multiple +identical Invariant Sections may be replaced with a single copy. If there +are multiple Invariant Sections with the same name but different contents, +make the title of each such section unique by adding at the end of it, in +parentheses, the name of the original author or publisher of that section +if known, or else a unique number. Make the same adjustment to the section +titles in the list of Invariant Sections in the license notice of the combined +work. +.Pp +In the combination, you must combine any sections entitled "History" in the +various original documents, forming one section entitled "History"; likewise +combine any sections entitled "Acknowledgements", and any sections entitled +"Dedications". You must delete all sections entitled "Endorsements." +.Pp +6. COLLECTIONS OF DOCUMENTS +.Pp +You may make a collection consisting of the Document and other documents released +under this License, and replace the individual copies of this License in the +various documents with a single copy that is included in the collection, provided +that you follow the rules of this License for verbatim copying of each of +the documents in all other respects. +.Pp +You may extract a single document from such a collection, and distribute it +individually under this License, provided you insert a copy of this License +into the extracted document, and follow this License in all other respects +regarding verbatim copying of that document. +.Pp +7. AGGREGATION WITH INDEPENDENT WORKS +.Pp +A compilation of the Document or its derivatives with other separate and independent +documents or works, in or on a volume of a storage or distribution medium, +does not as a whole count as a Modified Version of the Document, provided +no compilation copyright is claimed for the compilation. Such a compilation +is called an "aggregate", and this License does not apply to the other self-contained +works thus compiled with the Document, on account of their being thus compiled, +if they are not themselves derivative works of the Document. +.Pp +If the Cover Text requirement of section 3 is applicable to these copies of +the Document, then if the Document is less than one quarter of the entire +aggregate, the Document's Cover Texts may be placed on covers that surround +only the Document within the aggregate. Otherwise they must appear on covers +around the whole aggregate. +.Pp +8. TRANSLATION +.Pp +Translation is considered a kind of modification, so you may distribute translations +of the Document under the terms of section 4. Replacing Invariant Sections +with translations requires special permission from their copyright holders, +but you may include translations of some or all Invariant Sections in addition +to the original versions of these Invariant Sections. You may include a translation +of this License provided that you also include the original English version +of this License. In case of a disagreement between the translation and the +original English version of this License, the original English version will +prevail. +.Pp +9. TERMINATION +.Pp +You may not copy, modify, sublicense, or distribute the Document except as +expressly provided for under this License. Any other attempt to copy, modify, +sublicense or distribute the Document is void, and will automatically terminate +your rights under this License. However, parties who have received copies, +or rights, from you under this License will not have their licenses terminated +so long as such parties remain in full compliance. +.Pp +10. FUTURE REVISIONS OF THIS LICENSE +.Pp +The Free Software Foundation may publish new, revised versions of the GNU +Free Documentation License from time to time. Such new versions will be similar +in spirit to the present version, but may differ in detail to address new +problems or concerns. See http://www.gnu.org/copyleft/. +.Pp +Each version of the License is given a distinguishing version number. If the +Document specifies that a particular numbered version of this License "or +any later version" applies to it, you have the option of following the terms +and conditions either of that specified version or of any later version that +has been published (not as a draft) by the Free Software Foundation. If the +Document does not specify a version number of this License, you may choose +any version ever published (not as a draft) by the Free Software Foundation. +.Pp +ADDENDUM: How to use this License for your documents +.Pp +To use this License in a document you have written, include a copy of the +License in the document and put the following copyright and license notices +just after the title page: +.Pp +.Bd -literal -offset indent + Copyright (c) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + A copy of the license is included in the section entitled "GNU + Free Documentation License". +.Ed +.Pp +If you have no Invariant Sections, write "with no Invariant Sections" instead +of saying which ones are invariant. If you have no Front-Cover Texts, write +"no Front-Cover Texts" instead of "Front-Cover Texts being LIST"; likewise +for Back-Cover Texts. +.Pp +If your document contains nontrivial examples of program code, we recommend +releasing these examples in parallel under your choice of free software license, +such as the GNU General Public License, to permit their use in free software. +.Pp |