From 7bb36fb5519c0d25cfec61b31cf19e058fc18403 Mon Sep 17 00:00:00 2001 From: Baptiste Daroussin Date: Mon, 2 Mar 2015 17:20:34 +0000 Subject: [PATCH] Generate manpage out of the texinfo files using texi2mdoc --- contrib/binutils/binutils/doc/binutils.7 | 4917 +++++++++++++ contrib/binutils/gas/doc/as.7 | 8368 ++++++++++++++++++++++ contrib/binutils/ld/ld.7 | 7819 ++++++++++++++++++++ contrib/binutils/ld/ldint.7 | 1277 ++++ 4 files changed, 22381 insertions(+) create mode 100644 contrib/binutils/binutils/doc/binutils.7 create mode 100644 contrib/binutils/gas/doc/as.7 create mode 100644 contrib/binutils/ld/ld.7 create mode 100644 contrib/binutils/ld/ldint.7 diff --git a/contrib/binutils/binutils/doc/binutils.7 b/contrib/binutils/binutils/doc/binutils.7 new file mode 100644 index 000000000000..2c4c0e1b8f2b --- /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 [ ) , +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 -B \e + --rename-section .data=.rodata,alloc,load,readonly,data,contents \e + +.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: +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 @ . +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 @ +in addition to the symbols with +.Li @ . +.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 |--hex-dump=] + [-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 +.It --hex-dump= +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 000000000000..4d335576d060 --- /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 STT_FUNCTION + .type STT_OBJECT + + .type ,#function + .type ,#object + + .type ,@function + .type ,@object + + .type ,%function + .type ,%object + + .type ,"function" + .type ,"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 , = +.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