diff options
Diffstat (limited to 'contrib')
117 files changed, 37424 insertions, 25026 deletions
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 [ <mri-script ] +.Ed +.Pp +The GNU +.Xr ar +program creates, modifies, and extracts from archives. An +.Em archive +is a single file holding a collection of other files in a structure that makes +it possible to retrieve the original individual files (called +.Em members +of the archive). +.Pp +The original files' contents, mode (permissions), timestamp, owner, and group +are preserved in the archive, and can be restored on extraction. +.Pp +GNU +.Xr ar +can maintain archives whose members have names of any length; however, depending +on how +.Xr ar +is configured on your system, a limit on member-name length may be imposed +for compatibility with archive formats maintained with other tools. If it +exists, the limit is often 15 characters (typical of formats related to a.out) +or 16 characters (typical of formats related to coff). +.Pp +.Xr ar +is considered a binary utility because archives of this sort are most often +used as +.Em libraries +holding commonly needed subroutines. +.Pp +.Xr ar +creates an index to the symbols defined in relocatable object modules in the +archive when you specify the modifier +.Li s . +Once created, this index is updated in the archive whenever +.Xr ar +makes a change to its contents (save for the +.Li q +update operation). An archive with such an index speeds up linking to the +library, and allows routines in the library to call each other without regard +to their placement in the archive. +.Pp +You may use +.Li nm -s +or +.Li nm --print-armap +to list this index table. If an archive lacks the table, another form of +.Xr ar +called +.Xr ranlib +can be used to add just the table. +.Pp +GNU +.Xr ar +is designed to be compatible with two different facilities. You can control +its activity using command-line options, like the different varieties of +.Xr ar +on Unix systems; or, if you specify the single command-line option +.Op -M , +you can control it with a script supplied via standard input, like the MRI +\(lqlibrarian\(rq program. +.Pp +.Ss Controlling Xr ar on the Command Line +.Bd -literal -offset indent +ar [-X32_64] [-]p[mod [relpos] [count]] archive [member...] +.Ed +.Pp +When you use +.Xr ar +in the Unix style, +.Xr ar +insists on at least two arguments to execute: one keyletter specifying the +.Em operation +(optionally accompanied by other keyletters specifying +.Em modifiers ) , +and the archive name to act on. +.Pp +Most operations can also accept further +.Va member +arguments, specifying particular files to operate on. +.Pp +GNU +.Xr ar +allows you to mix the operation code +.Va p +and modifier flags +.Va mod +in any order, within the first command-line argument. +.Pp +If you wish, you may begin the first command-line argument with a dash. +.Pp +The +.Va p +keyletter specifies what operation to execute; it may be any of the following, +but you must specify only one of them: +.Pp +.Bl -tag -width Ds +.It d +.Em Delete +modules from the archive. Specify the names of modules to be deleted as +.Va member +\&...; the archive is untouched if you specify no files to delete. +.Pp +If you specify the +.Li v +modifier, +.Xr ar +lists each module as it is deleted. +.Pp +.It m +Use this operation to +.Em move +members in an archive. +.Pp +The ordering of members in an archive can make a difference in how programs +are linked using the library, if a symbol is defined in more than one member. +.Pp +If no modifiers are used with +.Li m , +any members you name in the +.Va member +arguments are moved to the +.Em end +of the archive; you can use the +.Li a , +.Li b , +or +.Li i +modifiers to move them to a specified place instead. +.Pp +.It p +.Em Print +the specified members of the archive, to the standard output file. If the +.Li v +modifier is specified, show the member name before copying its contents to +standard output. +.Pp +If you specify no +.Va member +arguments, all the files in the archive are printed. +.Pp +.It q +.Em Quick append ; +Historically, add the files +.Va member +\&...to the end of +.Va archive , +without checking for replacement. +.Pp +The modifiers +.Li a , +.Li b , +and +.Li i +do +.Em not +affect this operation; new members are always placed at the end of the archive. +.Pp +The modifier +.Li v +makes +.Xr ar +list each file as it is appended. +.Pp +Since the point of this operation is speed, the archive's symbol table index +is not updated, even if it already existed; you can use +.Li ar s +or +.Xr ranlib +explicitly to update the symbol table index. +.Pp +However, too many different systems assume quick append rebuilds the index, +so GNU +.Xr ar +implements +.Li q +as a synonym for +.Li r . +.Pp +.It r +Insert the files +.Va member +\&...into +.Va archive +(with +.Em replacement ) . +This operation differs from +.Li q +in that any previously existing members are deleted if their names match those +being added. +.Pp +If one of the files named in +.Va member +\&...does not exist, +.Xr ar +displays an error message, and leaves undisturbed any existing members of +the archive matching that name. +.Pp +By default, new members are added at the end of the file; but you may use +one of the modifiers +.Li a , +.Li b , +or +.Li i +to request placement relative to some existing member. +.Pp +The modifier +.Li v +used with this operation elicits a line of output for each file inserted, +along with one of the letters +.Li a +or +.Li r +to indicate whether the file was appended (no old member deleted) or replaced. +.Pp +.It t +Display a +.Em table +listing the contents of +.Va archive , +or those of the files listed in +.Va member +\&...that are present in the archive. Normally only the member name is shown; if +you also want to see the modes (permissions), timestamp, owner, group, and +size, you can request that by also specifying the +.Li v +modifier. +.Pp +If you do not specify a +.Va member , +all files in the archive are listed. +.Pp +If there is more than one file with the same name (say, +.Li fie ) +in an archive (say +.Li b.a ) , +.Li ar t b.a fie +lists only the first instance; to see them all, you must ask for a complete +listing---in our example, +.Li ar t b.a . +.Pp +.It x +.Em Extract +members (named +.Va member ) +from the archive. You can use the +.Li v +modifier with this operation, to request that +.Xr ar +list each name as it extracts it. +.Pp +If you do not specify a +.Va member , +all files in the archive are extracted. +.Pp +.El +A number of modifiers ( +.Va mod ) +may immediately follow the +.Va p +keyletter, to specify variations on an operation's behavior: +.Pp +.Bl -tag -width Ds +.It a +Add new files +.Em after +an existing member of the archive. If you use the modifier +.Li a , +the name of an existing archive member must be present as the +.Va relpos +argument, before the +.Va archive +specification. +.Pp +.It b +Add new files +.Em before +an existing member of the archive. If you use the modifier +.Li b , +the name of an existing archive member must be present as the +.Va relpos +argument, before the +.Va archive +specification. (same as +.Li i ) . +.Pp +.It c +.Em Create +the archive. The specified +.Va archive +is always created if it did not exist, when you request an update. But a warning +is issued unless you specify in advance that you expect to create it, by using +this modifier. +.Pp +.It f +Truncate names in the archive. GNU +.Xr ar +will normally permit file names of any length. This will cause it to create +archives which are not compatible with the native +.Xr ar +program on some systems. If this is a concern, the +.Li f +modifier may be used to truncate file names when putting them in the archive. +.Pp +.It i +Insert new files +.Em before +an existing member of the archive. If you use the modifier +.Li i , +the name of an existing archive member must be present as the +.Va relpos +argument, before the +.Va archive +specification. (same as +.Li b ) . +.Pp +.It l +This modifier is accepted but not used. +.Pp +.It N +Uses the +.Va count +parameter. This is used if there are multiple entries in the archive with +the same name. Extract or delete instance +.Va count +of the given name from the archive. +.Pp +.It o +Preserve the +.Em original +dates of members when extracting them. If you do not specify this modifier, +files extracted from the archive are stamped with the time of extraction. +.Pp +.It P +Use the full path name when matching names in the archive. GNU +.Xr ar +can not create an archive with a full path name (such archives are not POSIX +complaint), but other archive creators can. This option will cause GNU +.Xr ar +to match file names using a complete path name, which can be convenient when +extracting a single file from an archive created by another tool. +.Pp +.It s +Write an object-file index into the archive, or update an existing one, even +if no other change is made to the archive. You may use this modifier flag +either with any operation, or alone. Running +.Li ar s +on an archive is equivalent to running +.Li ranlib +on it. +.Pp +.It S +Do not generate an archive symbol table. This can speed up building a large +library in several steps. The resulting archive can not be used with the linker. +In order to build a symbol table, you must omit the +.Li S +modifier on the last execution of +.Li ar , +or you must run +.Li ranlib +on the archive. +.Pp +.It u +Normally, +.Li ar r +\&...inserts all files listed into the archive. If you would like to insert +.Em only +those of the files you list that are newer than existing members of the same +names, use this modifier. The +.Li u +modifier is allowed only for the operation +.Li r +(replace). In particular, the combination +.Li qu +is not allowed, since checking the timestamps would lose any speed advantage +from the operation +.Li q . +.Pp +.It v +This modifier requests the +.Em verbose +version of an operation. Many operations display additional information, such +as filenames processed, when the modifier +.Li v +is appended. +.Pp +.It V +This modifier shows the version number of +.Xr ar . +.El +.Pp +.Xr ar +ignores an initial option spelt +.Li -X32_64 , +for compatibility with AIX. The behaviour produced by this option is the default +for GNU +.Xr ar . +.Xr ar +does not support any of the other +.Li -X +options; in particular, it does not support +.Op -X32 +which is the default for AIX +.Xr ar . +.Pp +.Ss Controlling Xr ar with a Script +.Bd -literal -offset indent +ar -M [ <script ] +.Ed +.Pp +If you use the single command-line option +.Li -M +with +.Xr ar , +you can control its operation with a rudimentary command language. This form +of +.Xr ar +operates interactively if standard input is coming directly from a terminal. +During interactive use, +.Xr ar +prompts for input (the prompt is +.Li AR > ) , +and continues executing even after errors. If you redirect standard input +to a script file, no prompts are issued, and +.Xr ar +abandons execution (with a nonzero exit code) on any error. +.Pp +The +.Xr ar +command language is +.Em not +designed to be equivalent to the command-line options; in fact, it provides +somewhat less control over archives. The only purpose of the command language +is to ease the transition to GNU +.Xr ar +for developers who already have scripts written for the MRI \(lqlibrarian\(rq program. +.Pp +The syntax for the +.Xr ar +command language is straightforward: +.Bl -bullet +.It +commands are recognized in upper or lower case; for example, +.Li LIST +is the same as +.Li list . +In the following descriptions, commands are shown in upper case for clarity. +.Pp +.It +a single command may appear on each line; it is the first word on the line. +.Pp +.It +empty lines are allowed, and have no effect. +.Pp +.It +comments are allowed; text after either of the characters +.Li * +or +.Li ; +is ignored. +.Pp +.It +Whenever you use a list of names as part of the argument to an +.Xr ar +command, you can separate the individual names with either commas or blanks. +Commas are shown in the explanations below, for clarity. +.Pp +.It +.Li + +is used as a line continuation character; if +.Li + +appears at the end of a line, the text on the following line is considered +part of the current command. +.El +.Pp +Here are the commands you can use in +.Xr ar +scripts, or when using +.Xr ar +interactively. Three of them have special significance: +.Pp +.Li OPEN +or +.Li CREATE +specify a +.Em current archive , +which is a temporary file required for most of the other commands. +.Pp +.Li SAVE +commits the changes so far specified by the script. Prior to +.Li SAVE , +commands affect only the temporary copy of the current archive. +.Pp +.Bl -tag -width Ds +.It ADDLIB Va archive +.It ADDLIB Va archive ( Va module, Va module, ... Va module) +Add all the contents of +.Va archive +(or, if specified, each named +.Va module +from +.Va archive ) +to the current archive. +.Pp +Requires prior use of +.Li OPEN +or +.Li CREATE . +.Pp +.It ADDMOD Va member, Va member, ... Va member +Add each named +.Va member +as a module in the current archive. +.Pp +Requires prior use of +.Li OPEN +or +.Li CREATE . +.Pp +.It CLEAR +Discard the contents of the current archive, canceling the effect of any operations +since the last +.Li SAVE . +May be executed (with no effect) even if no current archive is specified. +.Pp +.It CREATE Va archive +Creates an archive, and makes it the current archive (required for many other +commands). The new archive is created with a temporary name; it is not actually +saved as +.Va archive +until you use +.Li SAVE . +You can overwrite existing archives; similarly, the contents of any existing +file named +.Va archive +will not be destroyed until +.Li SAVE . +.Pp +.It DELETE Va module, Va module, ... Va module +Delete each listed +.Va module +from the current archive; equivalent to +.Li ar -d Va archive Va module ... Va module . +.Pp +Requires prior use of +.Li OPEN +or +.Li CREATE . +.Pp +.It DIRECTORY Va archive ( Va module, ... Va module) +.It DIRECTORY Va archive ( Va module, ... Va module) Va outputfile +List each named +.Va module +present in +.Va archive . +The separate command +.Li VERBOSE +specifies the form of the output: when verbose output is off, output is like +that of +.Li ar -t Va archive Va module... . +When verbose output is on, the listing is like +.Li ar -tv Va archive Va module... . +.Pp +Output normally goes to the standard output stream; however, if you specify +.Va outputfile +as a final argument, +.Xr ar +directs the output to that file. +.Pp +.It END +Exit from +.Xr ar , +with a +.Li 0 +exit code to indicate successful completion. This command does not save the +output file; if you have changed the current archive since the last +.Li SAVE +command, those changes are lost. +.Pp +.It EXTRACT Va module, Va module, ... Va module +Extract each named +.Va module +from the current archive, writing them into the current directory as separate +files. Equivalent to +.Li ar -x Va archive Va module... . +.Pp +Requires prior use of +.Li OPEN +or +.Li CREATE . +.Pp +.It LIST +Display full contents of the current archive, in \(lqverbose\(rq style regardless +of the state of +.Li VERBOSE . +The effect is like +.Li ar tv Va archive . +(This single command is a GNU +.Xr ar +enhancement, rather than present for MRI compatibility.) +.Pp +Requires prior use of +.Li OPEN +or +.Li CREATE . +.Pp +.It OPEN Va archive +Opens an existing archive for use as the current archive (required for many +other commands). Any changes as the result of subsequent commands will not +actually affect +.Va archive +until you next use +.Li SAVE . +.Pp +.It REPLACE Va module, Va module, ... Va module +In the current archive, replace each existing +.Va module +(named in the +.Li REPLACE +arguments) from files in the current working directory. To execute this command +without errors, both the file, and the module in the current archive, must +exist. +.Pp +Requires prior use of +.Li OPEN +or +.Li CREATE . +.Pp +.It VERBOSE +Toggle an internal flag governing the output from +.Li DIRECTORY . +When the flag is on, +.Li DIRECTORY +output matches output from +.Li ar -tv +\&...\&. +.Pp +.It SAVE +Commit your changes to the current archive, and actually save it as a file +with the name specified in the last +.Li CREATE +or +.Li OPEN +command. +.Pp +Requires prior use of +.Li OPEN +or +.Li CREATE . +.Pp +.El +.Sh nm +.Bd -literal -offset indent +nm [-a|--debug-syms] [-g|--extern-only] + [-B] [-C|--demangle[=style]] [-D|--dynamic] + [-S|--print-size] [-s|--print-armap] + [-A|-o|--print-file-name][--special-syms] + [-n|-v|--numeric-sort] [-p|--no-sort] + [-r|--reverse-sort] [--size-sort] [-u|--undefined-only] + [-t radix|--radix=radix] [-P|--portability] + [--target=bfdname] [-fformat|--format=format] + [--defined-only] [-l|--line-numbers] [--no-demangle] + [-V|--version] [-X 32_64] [--help] [objfile...] +.Ed +.Pp +GNU +.Xr nm +lists the symbols from object files +.Va objfile +\&...\&. If no object files are listed as arguments, +.Xr nm +assumes the file +.Pa a.out . +.Pp +For each symbol, +.Xr nm +shows: +.Pp +.Bl -bullet +.It +The symbol value, in the radix selected by options (see below), or hexadecimal +by default. +.Pp +.It +The symbol type. At least the following types are used; others are, as well, +depending on the object file format. If lowercase, the symbol is local; if +uppercase, the symbol is global (external). +.Pp +.Bl -tag -width Ds +.It A +The symbol's value is absolute, and will not be changed by further linking. +.Pp +.It B +The symbol is in the uninitialized data section (known as BSS). +.Pp +.It C +The symbol is common. Common symbols are uninitialized data. When linking, +multiple common symbols may appear with the same name. If the symbol is defined +anywhere, the common symbols are treated as undefined references. For more +details on common symbols, see the discussion of --warn-common in Options,,Linker +options,ld.info,The GNU linker. +.Pp +.It D +The symbol is in the initialized data section. +.Pp +.It G +The symbol is in an initialized data section for small objects. Some object +file formats permit more efficient access to small data objects, such as a +global int variable as opposed to a large global array. +.Pp +.It I +The symbol is an indirect reference to another symbol. This is a GNU extension +to the a.out object file format which is rarely used. +.Pp +.It N +The symbol is a debugging symbol. +.Pp +.It R +The symbol is in a read only data section. +.Pp +.It S +The symbol is in an uninitialized data section for small objects. +.Pp +.It T +The symbol is in the text (code) section. +.Pp +.It U +The symbol is undefined. +.Pp +.It V +The symbol is a weak object. When a weak defined symbol is linked with a normal +defined symbol, the normal defined symbol is used with no error. When a weak +undefined symbol is linked and the symbol is not defined, the value of the +weak symbol becomes zero with no error. +.Pp +.It W +The symbol is a weak symbol that has not been specifically tagged as a weak +object symbol. When a weak defined symbol is linked with a normal defined +symbol, the normal defined symbol is used with no error. When a weak undefined +symbol is linked and the symbol is not defined, the value of the symbol is +determined in a system-specific manner without error. On some systems, uppercase +indicates that a default value has been specified. +.Pp +.It - +The symbol is a stabs symbol in an a.out object file. In this case, the next +values printed are the stabs other field, the stabs desc field, and the stab +type. Stabs symbols are used to hold debugging information. For more information, +see Top,Stabs,Stabs Overview,stabs.info, The \(lqstabs\(rq debug format. +.Pp +.It ? +The symbol type is unknown, or object file format specific. +.El +.Pp +.It +The symbol name. +.El +.Pp +The long and short forms of options, shown here as alternatives, are equivalent. +.Pp +.Bl -tag -width Ds +.It -A +.It -o +.It --print-file-name +Precede each symbol by the name of the input file (or archive member) in which +it was found, rather than identifying the input file once only, before all +of its symbols. +.Pp +.It -a +.It --debug-syms +Display all symbols, even debugger-only symbols; normally these are not listed. +.Pp +.It -B +The same as +.Op --format=bsd +(for compatibility with the MIPS +.Xr nm ) . +.Pp +.It -C +.It --demangle[= Va style] +Decode ( +.Em demangle ) +low-level symbol names into user-level names. Besides removing any initial +underscore prepended by the system, this makes C++ function names readable. +Different compilers have different mangling styles. The optional demangling +style argument can be used to choose an appropriate demangling style for your +compiler.See Section +.Dq c++filt , +for more information on demangling. +.Pp +.It --no-demangle +Do not demangle low-level symbol names. This is the default. +.Pp +.It -D +.It --dynamic +Display the dynamic symbols rather than the normal symbols. This is only meaningful +for dynamic objects, such as certain types of shared libraries. +.Pp +.It -f Va format +.It --format= Va format +Use the output format +.Va format , +which can be +.Li bsd , +.Li sysv , +or +.Li posix . +The default is +.Li bsd . +Only the first character of +.Va format +is significant; it can be either upper or lower case. +.Pp +.It -g +.It --extern-only +Display only external symbols. +.Pp +.It -l +.It --line-numbers +For each symbol, use debugging information to try to find a filename and line +number. For a defined symbol, look for the line number of the address of the +symbol. For an undefined symbol, look for the line number of a relocation +entry which refers to the symbol. If line number information can be found, +print it after the other symbol information. +.Pp +.It -n +.It -v +.It --numeric-sort +Sort symbols numerically by their addresses, rather than alphabetically by +their names. +.Pp +.It -p +.It --no-sort +Do not bother to sort the symbols in any order; print them in the order encountered. +.Pp +.It -P +.It --portability +Use the POSIX.2 standard output format instead of the default format. Equivalent +to +.Li -f posix . +.Pp +.It -S +.It --print-size +Print size, not the value, of defined symbols for the +.Li bsd +output format. +.Pp +.It -s +.It --print-armap +When listing symbols from archive members, include the index: a mapping (stored +in the archive by +.Xr ar +or +.Xr ranlib ) +of which modules contain definitions for which names. +.Pp +.It -r +.It --reverse-sort +Reverse the order of the sort (whether numeric or alphabetic); let the last +come first. +.Pp +.It --size-sort +Sort symbols by size. The size is computed as the difference between the value +of the symbol and the value of the symbol with the next higher value. If the +.Li bsd +output format is used the size of the symbol is printed, rather than the value, +and +.Li -S +must be used in order both size and value to be printed. +.Pp +.It --special-syms +Display symbols which have a target-specific special meaning. These symbols +are usually used by the target for some special processing and are not normally +helpful when included included in the normal symbol lists. For example for +ARM targets this option would skip the mapping symbols used to mark transitions +between ARM code, THUMB code and data. +.Pp +.It -t Va radix +.It --radix= Va radix +Use +.Va radix +as the radix for printing the symbol values. It must be +.Li d +for decimal, +.Li o +for octal, or +.Li x +for hexadecimal. +.Pp +.It --target= Va bfdname +Specify an object code format other than your system's default format.See Section +.Dq Target Selection , +for more information. +.Pp +.It -u +.It --undefined-only +Display only undefined symbols (those external to each object file). +.Pp +.It --defined-only +Display only defined symbols for each object file. +.Pp +.It -V +.It --version +Show the version number of +.Xr nm +and exit. +.Pp +.It -X +This option is ignored for compatibility with the AIX version of +.Xr nm . +It takes one parameter which must be the string +.Op 32_64 . +The default mode of AIX +.Xr nm +corresponds to +.Op -X 32 , +which is not supported by GNU +.Xr nm . +.Pp +.It --help +Show a summary of the options to +.Xr nm +and exit. +.El +.Pp +.Sh objcopy +.Bd -literal -offset indent +objcopy [-F bfdname|--target=bfdname] + [-I bfdname|--input-target=bfdname] + [-O bfdname|--output-target=bfdname] + [-B bfdarch|--binary-architecture=bfdarch] + [-S|--strip-all] + [-g|--strip-debug] + [-K symbolname|--keep-symbol=symbolname] + [-N symbolname|--strip-symbol=symbolname] + [--strip-unneeded-symbol=symbolname] + [-G symbolname|--keep-global-symbol=symbolname] + [--localize-hidden] + [-L symbolname|--localize-symbol=symbolname] + [--globalize-symbol=symbolname] + [-W symbolname|--weaken-symbol=symbolname] + [-w|--wildcard] + [-x|--discard-all] + [-X|--discard-locals] + [-b byte|--byte=byte] + [-i interleave|--interleave=interleave] + [-j sectionname|--only-section=sectionname] + [-R sectionname|--remove-section=sectionname] + [-p|--preserve-dates] + [--debugging] + [--gap-fill=val] + [--pad-to=address] + [--set-start=val] + [--adjust-start=incr] + [--change-addresses=incr] + [--change-section-address section{=,+,-}val] + [--change-section-lma section{=,+,-}val] + [--change-section-vma section{=,+,-}val] + [--change-warnings] [--no-change-warnings] + [--set-section-flags section=flags] + [--add-section sectionname=filename] + [--rename-section oldname=newname[,flags]] + [--change-leading-char] [--remove-leading-char] + [--reverse-bytes=num] + [--srec-len=ival] [--srec-forceS3] + [--redefine-sym old=new] + [--redefine-syms=filename] + [--weaken] + [--keep-symbols=filename] + [--strip-symbols=filename] + [--strip-unneeded-symbols=filename] + [--keep-global-symbols=filename] + [--localize-symbols=filename] + [--globalize-symbols=filename] + [--weaken-symbols=filename] + [--alt-machine-code=index] + [--prefix-symbols=string] + [--prefix-sections=string] + [--prefix-alloc-sections=string] + [--add-GNU-debuglink=path-to-file] + [--keep-file-symbols] + [--only-keep-debug] + [--extract-symbol] + [--writable-text] + [--readonly-text] + [--pure] + [--impure] + [-v|--verbose] + [-V|--version] + [--help] [--info] + infile [outfile] +.Ed +.Pp +The GNU +.Xr objcopy +utility copies the contents of an object file to another. +.Xr objcopy +uses the GNU bfd Library to read and write the object files. It can write +the destination object file in a format different from that of the source +object file. The exact behavior of +.Xr objcopy +is controlled by command-line options. Note that +.Xr objcopy +should be able to copy a fully linked file between any two formats. However, +copying a relocatable object file between any two formats may not work as +expected. +.Pp +.Xr objcopy +creates temporary files to do its translations and deletes them afterward. +.Xr objcopy +uses bfd to do all its translation work; it has access to all the formats +described in bfd and thus is able to recognize most formats without being +told explicitly.See Section +.Dq BFD . +.Pp +.Xr objcopy +can be used to generate S-records by using an output target of +.Li srec +(e.g., use +.Li -O srec ) . +.Pp +.Xr objcopy +can be used to generate a raw binary file by using an output target of +.Li binary +(e.g., use +.Op -O binary ) . +When +.Xr objcopy +generates a raw binary file, it will essentially produce a memory dump of +the contents of the input object file. All symbols and relocation information +will be discarded. The memory dump will start at the load address of the lowest +section copied into the output file. +.Pp +When generating an S-record or a raw binary file, it may be helpful to use +.Op -S +to remove sections containing debugging information. In some cases +.Op -R +will be useful to remove sections which contain information that is not needed +by the binary file. +.Pp +Note--- +.Xr objcopy +is not able to change the endianness of its input files. If the input format +has an endianness (some formats do not), +.Xr objcopy +can only copy the inputs into file formats that have the same endianness or +which have no endianness (e.g., +.Li srec ) . +(However, see the +.Op --reverse-bytes +option.) +.Pp +.Bl -tag -width Ds +.It Va infile +.It Va outfile +The input and output files, respectively. If you do not specify +.Va outfile , +.Xr objcopy +creates a temporary file and destructively renames the result with the name +of +.Va infile . +.Pp +.It -I Va bfdname +.It --input-target= Va bfdname +Consider the source file's object format to be +.Va bfdname , +rather than attempting to deduce it.See Section +.Dq Target Selection , +for more information. +.Pp +.It -O Va bfdname +.It --output-target= Va bfdname +Write the output file using the object format +.Va bfdname . +See Section.Dq Target Selection , +for more information. +.Pp +.It -F Va bfdname +.It --target= Va bfdname +Use +.Va bfdname +as the object format for both the input and the output file; i.e., simply +transfer data from source to destination with no translation.See Section +.Dq Target Selection , +for more information. +.Pp +.It -B Va bfdarch +.It --binary-architecture= Va bfdarch +Useful when transforming a raw binary input file into an object file. In this +case the output architecture can be set to +.Va bfdarch . +This option will be ignored if the input file has a known +.Va bfdarch . +You can access this binary data inside a program by referencing the special +symbols that are created by the conversion process. These symbols are called +_binary_ +.Va objfile +_start, _binary_ +.Va objfile +_end and _binary_ +.Va objfile +_size. e.g. you can transform a picture file into an object file and then +access it in your code using these symbols. +.Pp +.It -j Va sectionname +.It --only-section= Va sectionname +Copy only the named section from the input file to the output file. This option +may be given more than once. Note that using this option inappropriately may +make the output file unusable. +.Pp +.It -R Va sectionname +.It --remove-section= Va sectionname +Remove any section named +.Va sectionname +from the output file. This option may be given more than once. Note that using +this option inappropriately may make the output file unusable. +.Pp +.It -S +.It --strip-all +Do not copy relocation and symbol information from the source file. +.Pp +.It -g +.It --strip-debug +Do not copy debugging symbols or sections from the source file. +.Pp +.It --strip-unneeded +Strip all symbols that are not needed for relocation processing. +.Pp +.It -K Va symbolname +.It --keep-symbol= Va symbolname +When stripping symbols, keep symbol +.Va symbolname +even if it would normally be stripped. This option may be given more than +once. +.Pp +.It -N Va symbolname +.It --strip-symbol= Va symbolname +Do not copy symbol +.Va symbolname +from the source file. This option may be given more than once. +.Pp +.It --strip-unneeded-symbol= Va symbolname +Do not copy symbol +.Va symbolname +from the source file unless it is needed by a relocation. This option may +be given more than once. +.Pp +.It -G Va symbolname +.It --keep-global-symbol= Va symbolname +Keep only symbol +.Va symbolname +global. Make all other symbols local to the file, so that they are not visible +externally. This option may be given more than once. +.Pp +.It --localize-hidden +In an ELF object, mark all symbols that have hidden or internal visibility +as local. This option applies on top of symbol-specific localization options +such as +.Op -L . +.Pp +.It -L Va symbolname +.It --localize-symbol= Va symbolname +Make symbol +.Va symbolname +local to the file, so that it is not visible externally. This option may be +given more than once. +.Pp +.It -W Va symbolname +.It --weaken-symbol= Va symbolname +Make symbol +.Va symbolname +weak. This option may be given more than once. +.Pp +.It --globalize-symbol= Va symbolname +Give symbol +.Va symbolname +global scoping so that it is visible outside of the file in which it is defined. +This option may be given more than once. +.Pp +.It -w +.It --wildcard +Permit regular expressions in +.Va symbolname +s used in other command line options. The question mark (?), asterisk (*), +backslash (\e) and square brackets ([]) operators can be used anywhere in the +symbol name. If the first character of the symbol name is the exclamation +point (!) then the sense of the switch is reversed for that symbol. For example: +.Pp +.Bd -literal -offset indent + -w -W !foo -W fo* +.Ed +.Pp +would cause objcopy to weaken all symbols that start with \(lqfo\(rq except for the +symbol \(lqfoo\(rq. +.Pp +.It -x +.It --discard-all +Do not copy non-global symbols from the source file. +.Pp +.It -X +.It --discard-locals +Do not copy compiler-generated local symbols. (These usually start with +.Li L +or +.Li . . ) +.Pp +.It -b Va byte +.It --byte= Va byte +Keep only every +.Va byte +th byte of the input file (header data is not affected). +.Va byte +can be in the range from 0 to +.Va interleave +-1, where +.Va interleave +is given by the +.Op -i +or +.Op --interleave +option, or the default of 4. This option is useful for creating files to program +rom. It is typically used with an +.Li srec +output target. +.Pp +.It -i Va interleave +.It --interleave= Va interleave +Only copy one out of every +.Va interleave +bytes. Select which byte to copy with the +.Op -b +or +.Op --byte +option. The default is 4. +.Xr objcopy +ignores this option if you do not specify either +.Op -b +or +.Op --byte . +.Pp +.It -p +.It --preserve-dates +Set the access and modification dates of the output file to be the same as +those of the input file. +.Pp +.It --debugging +Convert debugging information, if possible. This is not the default because +only certain debugging formats are supported, and the conversion process can +be time consuming. +.Pp +.It --gap-fill Va val +Fill gaps between sections with +.Va val . +This operation applies to the +.Em load address +(LMA) of the sections. It is done by increasing the size of the section with +the lower address, and filling in the extra space created with +.Va val . +.Pp +.It --pad-to Va address +Pad the output file up to the load address +.Va address . +This is done by increasing the size of the last section. The extra space is +filled in with the value specified by +.Op --gap-fill +(default zero). +.Pp +.It --set-start Va val +Set the start address of the new file to +.Va val . +Not all object file formats support setting the start address. +.Pp +.It --change-start Va incr +.It --adjust-start Va incr +Change the start address by adding +.Va incr . +Not all object file formats support setting the start address. +.Pp +.It --change-addresses Va incr +.It --adjust-vma Va incr +Change the VMA and LMA addresses of all sections, as well as the start address, +by adding +.Va incr . +Some object file formats do not permit section addresses to be changed arbitrarily. +Note that this does not relocate the sections; if the program expects sections +to be loaded at a certain address, and this option is used to change the sections +such that they are loaded at a different address, the program may fail. +.Pp +.It --change-section-address Va section{=,+,-} Va val +.It --adjust-section-vma Va section{=,+,-} Va val +Set or change both the VMA address and the LMA address of the named +.Va section . +If +.Li = +is used, the section address is set to +.Va val . +Otherwise, +.Va val +is added to or subtracted from the section address. See the comments under +.Op --change-addresses , +above. If +.Va section +does not exist in the input file, a warning will be issued, unless +.Op --no-change-warnings +is used. +.Pp +.It --change-section-lma Va section{=,+,-} Va val +Set or change the LMA address of the named +.Va section . +The LMA address is the address where the section will be loaded into memory +at program load time. Normally this is the same as the VMA address, which +is the address of the section at program run time, but on some systems, especially +those where a program is held in ROM, the two can be different. If +.Li = +is used, the section address is set to +.Va val . +Otherwise, +.Va val +is added to or subtracted from the section address. See the comments under +.Op --change-addresses , +above. If +.Va section +does not exist in the input file, a warning will be issued, unless +.Op --no-change-warnings +is used. +.Pp +.It --change-section-vma Va section{=,+,-} Va val +Set or change the VMA address of the named +.Va section . +The VMA address is the address where the section will be located once the +program has started executing. Normally this is the same as the LMA address, +which is the address where the section will be loaded into memory, but on +some systems, especially those where a program is held in ROM, the two can +be different. If +.Li = +is used, the section address is set to +.Va val . +Otherwise, +.Va val +is added to or subtracted from the section address. See the comments under +.Op --change-addresses , +above. If +.Va section +does not exist in the input file, a warning will be issued, unless +.Op --no-change-warnings +is used. +.Pp +.It --change-warnings +.It --adjust-warnings +If +.Op --change-section-address +or +.Op --change-section-lma +or +.Op --change-section-vma +is used, and the named section does not exist, issue a warning. This is the +default. +.Pp +.It --no-change-warnings +.It --no-adjust-warnings +Do not issue a warning if +.Op --change-section-address +or +.Op --adjust-section-lma +or +.Op --adjust-section-vma +is used, even if the named section does not exist. +.Pp +.It --set-section-flags Va section= Va flags +Set the flags for the named section. The +.Va flags +argument is a comma separated string of flag names. The recognized names are +.Li alloc , +.Li contents , +.Li load , +.Li noload , +.Li readonly , +.Li code , +.Li data , +.Li rom , +.Li share , +and +.Li debug . +You can set the +.Li contents +flag for a section which does not have contents, but it is not meaningful +to clear the +.Li contents +flag of a section which does have contents--just remove the section instead. +Not all flags are meaningful for all object file formats. +.Pp +.It --add-section Va sectionname= Va filename +Add a new section named +.Va sectionname +while copying the file. The contents of the new section are taken from the +file +.Va filename . +The size of the section will be the size of the file. This option only works +on file formats which can support sections with arbitrary names. +.Pp +.It --rename-section Va oldname= Va newname[, Va flags] +Rename a section from +.Va oldname +to +.Va newname , +optionally changing the section's flags to +.Va flags +in the process. This has the advantage over usng a linker script to perform +the rename in that the output stays as an object file and does not become +a linked executable. +.Pp +This option is particularly helpful when the input format is binary, since +this will always create a section called .data. If for example, you wanted +instead to create a section called .rodata containing binary data you could +use the following command line to achieve it: +.Pp +.Bd -literal -offset indent + objcopy -I binary -O <output_format> -B <architecture> \e + --rename-section .data=.rodata,alloc,load,readonly,data,contents \e + <input_binary_file> <output_object_file> +.Ed +.Pp +.It --change-leading-char +Some object file formats use special characters at the start of symbols. The +most common such character is underscore, which compilers often add before +every symbol. This option tells +.Xr objcopy +to change the leading character of every symbol when it converts between object +file formats. If the object file formats use the same leading character, this +option has no effect. Otherwise, it will add a character, or remove a character, +or change a character, as appropriate. +.Pp +.It --remove-leading-char +If the first character of a global symbol is a special symbol leading character +used by the object file format, remove the character. The most common symbol +leading character is underscore. This option will remove a leading underscore +from all global symbols. This can be useful if you want to link together objects +of different file formats with different conventions for symbol names. This +is different from +.Op --change-leading-char +because it always changes the symbol name when appropriate, regardless of +the object file format of the output file. +.Pp +.It --reverse-bytes= Va num +Reverse the bytes in a section with output contents. A section length must +be evenly divisible by the value given in order for the swap to be able to +take place. Reversing takes place before the interleaving is performed. +.Pp +This option is used typically in generating ROM images for problematic target +systems. For example, on some target boards, the 32-bit words fetched from +8-bit ROMs are re-assembled in little-endian byte order regardless of the +CPU byte order. Depending on the programming model, the endianness of the +ROM may need to be modified. +.Pp +Consider a simple file with a section containing the following eight bytes: +.Li 12345678 . +.Pp +Using +.Li --reverse-bytes=2 +for the above example, the bytes in the output file would be ordered +.Li 21436587 . +.Pp +Using +.Li --reverse-bytes=4 +for the above example, the bytes in the output file would be ordered +.Li 43218765 . +.Pp +By using +.Li --reverse-bytes=2 +for the above example, followed by +.Li --reverse-bytes=4 +on the output file, the bytes in the second output file would be ordered +.Li 34127856 . +.Pp +.It --srec-len= Va ival +Meaningful only for srec output. Set the maximum length of the Srecords being +produced to +.Va ival . +This length covers both address, data and crc fields. +.Pp +.It --srec-forceS3 +Meaningful only for srec output. Avoid generation of S1/S2 records, creating +S3-only record format. +.Pp +.It --redefine-sym Va old= Va new +Change the name of a symbol +.Va old , +to +.Va new . +This can be useful when one is trying link two things together for which you +have no source, and there are name collisions. +.Pp +.It --redefine-syms= Va filename +Apply +.Op --redefine-sym +to each symbol pair " +.Va old +.Va new " +listed in the file +.Va filename . +.Va filename +is simply a flat file, with one symbol pair per line. Line comments may be +introduced by the hash character. This option may be given more than once. +.Pp +.It --weaken +Change all global symbols in the file to be weak. This can be useful when +building an object which will be linked against other objects using the +.Op -R +option to the linker. This option is only effective when using an object file +format which supports weak symbols. +.Pp +.It --keep-symbols= Va filename +Apply +.Op --keep-symbol +option to each symbol listed in the file +.Va filename . +.Va filename +is simply a flat file, with one symbol name per line. Line comments may be +introduced by the hash character. This option may be given more than once. +.Pp +.It --strip-symbols= Va filename +Apply +.Op --strip-symbol +option to each symbol listed in the file +.Va filename . +.Va filename +is simply a flat file, with one symbol name per line. Line comments may be +introduced by the hash character. This option may be given more than once. +.Pp +.It --strip-unneeded-symbols= Va filename +Apply +.Op --strip-unneeded-symbol +option to each symbol listed in the file +.Va filename . +.Va filename +is simply a flat file, with one symbol name per line. Line comments may be +introduced by the hash character. This option may be given more than once. +.Pp +.It --keep-global-symbols= Va filename +Apply +.Op --keep-global-symbol +option to each symbol listed in the file +.Va filename . +.Va filename +is simply a flat file, with one symbol name per line. Line comments may be +introduced by the hash character. This option may be given more than once. +.Pp +.It --localize-symbols= Va filename +Apply +.Op --localize-symbol +option to each symbol listed in the file +.Va filename . +.Va filename +is simply a flat file, with one symbol name per line. Line comments may be +introduced by the hash character. This option may be given more than once. +.Pp +.It --globalize-symbols= Va filename +Apply +.Op --globalize-symbol +option to each symbol listed in the file +.Va filename . +.Va filename +is simply a flat file, with one symbol name per line. Line comments may be +introduced by the hash character. This option may be given more than once. +.Pp +.It --weaken-symbols= Va filename +Apply +.Op --weaken-symbol +option to each symbol listed in the file +.Va filename . +.Va filename +is simply a flat file, with one symbol name per line. Line comments may be +introduced by the hash character. This option may be given more than once. +.Pp +.It --alt-machine-code= Va index +If the output architecture has alternate machine codes, use the +.Va index +th code instead of the default one. This is useful in case a machine is assigned +an official code and the tool-chain adopts the new code, but other applications +still depend on the original code being used. For ELF based architectures +if the +.Va index +alternative does not exist then the value is treated as an absolute number +to be stored in the e_machine field of the ELF header. +.Pp +.It --writable-text +Mark the output text as writable. This option isn't meaningful for all object +file formats. +.Pp +.It --readonly-text +Make the output text write protected. This option isn't meaningful for all +object file formats. +.Pp +.It --pure +Mark the output file as demand paged. This option isn't meaningful for all +object file formats. +.Pp +.It --impure +Mark the output file as impure. This option isn't meaningful for all object +file formats. +.Pp +.It --prefix-symbols= Va string +Prefix all symbols in the output file with +.Va string . +.Pp +.It --prefix-sections= Va string +Prefix all section names in the output file with +.Va string . +.Pp +.It --prefix-alloc-sections= Va string +Prefix all the names of all allocated sections in the output file with +.Va string . +.Pp +.It --add-GNU-debuglink= Va path-to-file +Creates a .GNU_debuglink section which contains a reference to +.Va path-to-file +and adds it to the output file. +.Pp +.It --keep-file-symbols +When stripping a file, perhaps with +.Op --strip-debug +or +.Op --strip-unneeded , +retain any symbols specifying source file names, which would otherwise get +stripped. +.Pp +.It --only-keep-debug +Strip a file, removing contents of any sections that would not be stripped +by +.Op --strip-debug +and leaving the debugging sections intact. In ELF files, this preserves all +note sections in the output. +.Pp +The intention is that this option will be used in conjunction with +.Op --add-GNU-debuglink +to create a two part executable. One a stripped binary which will occupy less +space in RAM and in a distribution and the second a debugging information +file which is only needed if debugging abilities are required. The suggested +procedure to create these files is as follows: +.Pp +.Bl -enum +.It +Link the executable as normal. Assuming that is is called +.Li foo +then... +.It +Run +.Li objcopy --only-keep-debug foo foo.dbg +to +create a file containing the debugging info. +.It +Run +.Li objcopy --strip-debug foo +to create a +stripped executable. +.It +Run +.Li objcopy --add-GNU-debuglink=foo.dbg foo +to add a link to the debugging info into the stripped executable. +.El +.Pp +Note - the choice of +.Li .dbg +as an extension for the debug info file is arbitrary. Also the +.Li --only-keep-debug +step is optional. You could instead do this: +.Pp +.Bl -enum +.It +Link the executable as normal. +.It +Copy +.Li foo +to +.Li foo.full +.It +Run +.Li objcopy --strip-debug foo +.It +Run +.Li objcopy --add-GNU-debuglink=foo.full foo +.El +.Pp +i.e., the file pointed to by the +.Op --add-GNU-debuglink +can be the full executable. It does not have to be a file created by the +.Op --only-keep-debug +switch. +.Pp +Note - this switch is only intended for use on fully linked files. It does +not make sense to use it on object files where the debugging information may +be incomplete. Besides the GNU_debuglink feature currently only supports the +presence of one filename containing debugging information, not multiple filenames +on a one-per-object-file basis. +.Pp +.It --extract-symbol +Keep the file's section flags and symbols but remove all section data. Specifically, +the option: +.Pp +.Bl -bullet +.It +sets the virtual and load addresses of every section to zero; +.It +removes the contents of all sections; +.It +sets the size of every section to zero; and +.It +sets the file's start address to zero. +.El +.Pp +This option is used to build a +.Pa .sym +file for a VxWorks kernel. It can also be a useful way of reducing the size +of a +.Op --just-symbols +linker input file. +.Pp +.It -V +.It --version +Show the version number of +.Xr objcopy . +.Pp +.It -v +.It --verbose +Verbose output: list all object files modified. In the case of archives, +.Li objcopy -V +lists all members of the archive. +.Pp +.It --help +Show a summary of the options to +.Xr objcopy . +.Pp +.It --info +Display a list showing all architectures and object formats available. +.El +.Pp +.Sh objdump +.Bd -literal -offset indent +objdump [-a|--archive-headers] + [-b bfdname|--target=bfdname] + [-C|--demangle[=style] ] + [-d|--disassemble] + [-D|--disassemble-all] + [-z|--disassemble-zeroes] + [-EB|-EL|--endian={big | little }] + [-f|--file-headers] + [--file-start-context] + [-g|--debugging] + [-e|--debugging-tags] + [-h|--section-headers|--headers] + [-i|--info] + [-j section|--section=section] + [-l|--line-numbers] + [-S|--source] + [-m machine|--architecture=machine] + [-M options|--disassembler-options=options] + [-p|--private-headers] + [-r|--reloc] + [-R|--dynamic-reloc] + [-s|--full-contents] + [-W|--dwarf] + [-G|--stabs] + [-t|--syms] + [-T|--dynamic-syms] + [-x|--all-headers] + [-w|--wide] + [--start-address=address] + [--stop-address=address] + [--prefix-addresses] + [--[no-]show-raw-insn] + [--adjust-vma=offset] + [--special-syms] + [-V|--version] + [-H|--help] + objfile... +.Ed +.Pp +.Xr objdump +displays information about one or more object files. The options control what +particular information to display. This information is mostly useful to programmers +who are working on the compilation tools, as opposed to programmers who just +want their program to compile and work. +.Pp +.Va objfile +\&...are the object files to be examined. When you specify archives, +.Xr objdump +shows information on each of the member object files. +.Pp +The long and short forms of options, shown here as alternatives, are equivalent. +At least one option from the list +.Op -a,-d,-D,-e,-f,-g,-G,-h,-H,-p,-r,-R,-s,-S,-t,-T,-V,-x +must be given. +.Pp +.Bl -tag -width Ds +.It -a +.It --archive-header +If any of the +.Va objfile +files are archives, display the archive header information (in a format similar +to +.Li ls -l ) . +Besides the information you could list with +.Li ar tv , +.Li objdump -a +shows the object file format of each archive member. +.Pp +.It --adjust-vma= Va offset +When dumping information, first add +.Va offset +to all the section addresses. This is useful if the section addresses do not +correspond to the symbol table, which can happen when putting sections at +particular addresses when using a format which can not represent section addresses, +such as a.out. +.Pp +.It -b Va bfdname +.It --target= Va bfdname +Specify that the object-code format for the object files is +.Va bfdname . +This option may not be necessary; +.Va objdump +can automatically recognize many formats. +.Pp +For example, +.Bd -literal -offset indent +objdump -b oasys -m vax -h fu.o +.Ed +displays summary information from the section headers ( +.Op -h ) +of +.Pa fu.o , +which is explicitly identified ( +.Op -m ) +as a VAX object file in the format produced by Oasys compilers. You can list +the formats available with the +.Op -i +option.See Section +.Dq Target Selection , +for more information. +.Pp +.It -C +.It --demangle[= Va style] +Decode ( +.Em demangle ) +low-level symbol names into user-level names. Besides removing any initial +underscore prepended by the system, this makes C++ function names readable. +Different compilers have different mangling styles. The optional demangling +style argument can be used to choose an appropriate demangling style for your +compiler.See Section +.Dq c++filt , +for more information on demangling. +.Pp +.It -g +.It --debugging +Display debugging information. This attempts to parse debugging information +stored in the file and print it out using a C like syntax. Only certain types +of debugging information have been implemented. Some other types are supported +by +.Xr readelf -w . +See Section.Dq readelf . +.Pp +.It -e +.It --debugging-tags +Like +.Op -g , +but the information is generated in a format compatible with ctags tool. +.Pp +.It -d +.It --disassemble +Display the assembler mnemonics for the machine instructions from +.Va objfile . +This option only disassembles those sections which are expected to contain +instructions. +.Pp +.It -D +.It --disassemble-all +Like +.Op -d , +but disassemble the contents of all sections, not just those expected to contain +instructions. +.Pp +.It --prefix-addresses +When disassembling, print the complete address on each line. This is the older +disassembly format. +.Pp +.It -EB +.It -EL +.It --endian={big|little} +Specify the endianness of the object files. This only affects disassembly. +This can be useful when disassembling a file format which does not describe +endianness information, such as S-records. +.Pp +.It -f +.It --file-headers +Display summary information from the overall header of each of the +.Va objfile +files. +.Pp +.It --file-start-context +Specify that when displaying interlisted source code/disassembly (assumes +.Op -S ) +from a file that has not yet been displayed, extend the context to the start +of the file. +.Pp +.It -h +.It --section-headers +.It --headers +Display summary information from the section headers of the object file. +.Pp +File segments may be relocated to nonstandard addresses, for example by using +the +.Op -Ttext , +.Op -Tdata , +or +.Op -Tbss +options to +.Xr ld . +However, some object file formats, such as a.out, do not store the starting +address of the file segments. In those situations, although +.Xr ld +relocates the sections correctly, using +.Li objdump -h +to list the file section headers cannot show the correct addresses. Instead, +it shows the usual addresses, which are implicit for the target. +.Pp +.It -H +.It --help +Print a summary of the options to +.Xr objdump +and exit. +.Pp +.It -i +.It --info +Display a list showing all architectures and object formats available for +specification with +.Op -b +or +.Op -m . +.Pp +.It -j Va name +.It --section= Va name +Display information only for section +.Va name . +.Pp +.It -l +.It --line-numbers +Label the display (using debugging information) with the filename and source +line numbers corresponding to the object code or relocs shown. Only useful +with +.Op -d , +.Op -D , +or +.Op -r . +.Pp +.It -m Va machine +.It --architecture= Va machine +Specify the architecture to use when disassembling object files. This can +be useful when disassembling object files which do not describe architecture +information, such as S-records. You can list the available architectures with +the +.Op -i +option. +.Pp +.It -M Va options +.It --disassembler-options= Va options +Pass target specific information to the disassembler. Only supported on some +targets. If it is necessary to specify more than one disassembler option then +multiple +.Op -M +options can be used or can be placed together into a comma separated list. +.Pp +If the target is an ARM architecture then this switch can be used to select +which register name set is used during disassembler. Specifying +.Op -M reg-names-std +(the default) will select the register names as used in ARM's instruction +set documentation, but with register 13 called 'sp', register 14 called 'lr' +and register 15 called 'pc'. Specifying +.Op -M reg-names-apcs +will select the name set used by the ARM Procedure Call Standard, whilst specifying +.Op -M reg-names-raw +will just use +.Li r +followed by the register number. +.Pp +There are also two variants on the APCS register naming scheme enabled by +.Op -M reg-names-atpcs +and +.Op -M reg-names-special-atpcs +which use the ARM/Thumb Procedure Call Standard naming conventions. (Either +with the normal register names or the special register names). +.Pp +This option can also be used for ARM architectures to force the disassembler +to interpret all instructions as Thumb instructions by using the switch +.Op --disassembler-options=force-thumb . +This can be useful when attempting to disassemble thumb code produced by other +compilers. +.Pp +For the x86, some of the options duplicate functions of the +.Op -m +switch, but allow finer grained control. Multiple selections from the following +may be specified as a comma separated string. +.Op x86-64 , +.Op i386 +and +.Op i8086 +select disassembly for the given architecture. +.Op intel +and +.Op att +select between intel syntax mode and AT&T syntax mode. +.Op addr64 , +.Op addr32 , +.Op addr16 , +.Op data32 +and +.Op data16 +specify the default address size and operand size. These four options will +be overridden if +.Op x86-64 , +.Op i386 +or +.Op i8086 +appear later in the option string. Lastly, +.Op suffix , +when in AT&T mode, instructs the disassembler to print a mnemonic suffix even +when the suffix could be inferred by the operands. +.Pp +For PPC, +.Op booke , +.Op booke32 +and +.Op booke64 +select disassembly of BookE instructions. +.Op 32 +and +.Op 64 +select PowerPC and PowerPC64 disassembly, respectively. +.Op e300 +selects disassembly for the e300 family. +.Op 440 +selects disassembly for the PowerPC 440. +.Pp +For MIPS, this option controls the printing of instruction mnemonic names +and register names in disassembled instructions. Multiple selections from +the following may be specified as a comma separated string, and invalid options +are ignored: +.Pp +.Bl -tag -width Ds +.It no-aliases +Print the 'raw' instruction mnemonic instead of some pseudo instruction mnemonic. +I.e., print 'daddu' or 'or' instead of 'move', 'sll' instead of 'nop', etc. +.Pp +.It gpr-names= Va ABI +Print GPR (general-purpose register) names as appropriate for the specified +ABI. By default, GPR names are selected according to the ABI of the binary +being disassembled. +.Pp +.It fpr-names= Va ABI +Print FPR (floating-point register) names as appropriate for the specified +ABI. By default, FPR numbers are printed rather than names. +.Pp +.It cp0-names= Va ARCH +Print CP0 (system control coprocessor; coprocessor 0) register names as appropriate +for the CPU or architecture specified by +.Va ARCH . +By default, CP0 register names are selected according to the architecture +and CPU of the binary being disassembled. +.Pp +.It hwr-names= Va ARCH +Print HWR (hardware register, used by the +.Li rdhwr +instruction) names as appropriate for the CPU or architecture specified by +.Va ARCH . +By default, HWR names are selected according to the architecture and CPU of +the binary being disassembled. +.Pp +.It reg-names= Va ABI +Print GPR and FPR names as appropriate for the selected ABI. +.Pp +.It reg-names= Va ARCH +Print CPU-specific register names (CP0 register and HWR names) as appropriate +for the selected CPU or architecture. +.El +.Pp +For any of the options listed above, +.Va ABI +or +.Va ARCH +may be specified as +.Li numeric +to have numbers printed rather than names, for the selected types of registers. +You can list the available values of +.Va ABI +and +.Va ARCH +using the +.Op --help +option. +.Pp +For VAX, you can specify function entry addresses with +.Op -M entry:0xf00ba . +You can use this multiple times to properly disassemble VAX binary files that +don't contain symbol tables (like ROM dumps). In these cases, the function +entry mask would otherwise be decoded as VAX instructions, which would probably +lead the rest of the function being wrongly disassembled. +.Pp +.It -p +.It --private-headers +Print information that is specific to the object file format. The exact information +printed depends upon the object file format. For some object file formats, +no additional information is printed. +.Pp +.It -r +.It --reloc +Print the relocation entries of the file. If used with +.Op -d +or +.Op -D , +the relocations are printed interspersed with the disassembly. +.Pp +.It -R +.It --dynamic-reloc +Print the dynamic relocation entries of the file. This is only meaningful +for dynamic objects, such as certain types of shared libraries. +.Pp +.It -s +.It --full-contents +Display the full contents of any sections requested. By default all non-empty +sections are displayed. +.Pp +.It -S +.It --source +Display source code intermixed with disassembly, if possible. Implies +.Op -d . +.Pp +.It --show-raw-insn +When disassembling instructions, print the instruction in hex as well as in +symbolic form. This is the default except when +.Op --prefix-addresses +is used. +.Pp +.It --no-show-raw-insn +When disassembling instructions, do not print the instruction bytes. This +is the default when +.Op --prefix-addresses +is used. +.Pp +.It -W +.It --dwarf +Displays the contents of the DWARF debug sections in the file, if any are +present. +.Pp +.It -G +.It --stabs +Display the full contents of any sections requested. Display the contents +of the .stab and .stab.index and .stab.excl sections from an ELF file. This +is only useful on systems (such as Solaris 2.0) in which +.Li .stab +debugging symbol-table entries are carried in an ELF section. In most other +file formats, debugging symbol-table entries are interleaved with linkage +symbols, and are visible in the +.Op --syms +output. For more information on stabs symbols, see Top,Stabs,Stabs Overview,stabs.info, +The \(lqstabs\(rq debug format. +.Pp +.It --start-address= Va address +Start displaying data at the specified address. This affects the output of +the +.Op -d , +.Op -r +and +.Op -s +options. +.Pp +.It --stop-address= Va address +Stop displaying data at the specified address. This affects the output of +the +.Op -d , +.Op -r +and +.Op -s +options. +.Pp +.It -t +.It --syms +Print the symbol table entries of the file. This is similar to the information +provided by the +.Li nm +program. +.Pp +.It -T +.It --dynamic-syms +Print the dynamic symbol table entries of the file. This is only meaningful +for dynamic objects, such as certain types of shared libraries. This is similar +to the information provided by the +.Li nm +program when given the +.Op -D +( +.Op --dynamic ) +option. +.Pp +.It --special-syms +When displaying symbols include those which the target considers to be special +in some way and which would not normally be of interest to the user. +.Pp +.It -V +.It --version +Print the version number of +.Xr objdump +and exit. +.Pp +.It -x +.It --all-headers +Display all available header information, including the symbol table and relocation +entries. Using +.Op -x +is equivalent to specifying all of +.Op -a -f -h -p -r -t . +.Pp +.It -w +.It --wide +Format some lines for output devices that have more than 80 columns. Also +do not truncate symbol names when they are displayed. +.Pp +.It -z +.It --disassemble-zeroes +Normally the disassembly output will skip blocks of zeroes. This option directs +the disassembler to disassemble those blocks, just like any other data. +.El +.Pp +.Sh ranlib +.Bd -literal -offset indent +ranlib [-vV] archive +.Ed +.Pp +.Xr ranlib +generates an index to the contents of an archive and stores it in the archive. +The index lists each symbol defined by a member of an archive that is a relocatable +object file. +.Pp +You may use +.Li nm -s +or +.Li nm --print-armap +to list this index. +.Pp +An archive with such an index speeds up linking to the library and allows +routines in the library to call each other without regard to their placement +in the archive. +.Pp +The GNU +.Xr ranlib +program is another form of GNU +.Xr ar ; +running +.Xr ranlib +is completely equivalent to executing +.Li ar -s . +See Section.Dq ar . +.Pp +.Bl -tag -width Ds +.It -v +.It -V +.It --version +Show the version number of +.Xr ranlib . +.El +.Pp +.Sh size +.Bd -literal -offset indent +size [-A|-B|--format=compatibility] + [--help] + [-d|-o|-x|--radix=number] + [-t|--totals] + [--target=bfdname] [-V|--version] + [objfile...] +.Ed +.Pp +The GNU +.Xr size +utility lists the section sizes---and the total size---for each of the object +or archive files +.Va objfile +in its argument list. By default, one line of output is generated for each +object file or each module in an archive. +.Pp +.Va objfile +\&...are the object files to be examined. If none are specified, the file +.Li a.out +will be used. +.Pp +The command line options have the following meanings: +.Pp +.Bl -tag -width Ds +.It -A +.It -B +.It --format= Va compatibility +Using one of these options, you can choose whether the output from GNU +.Xr size +resembles output from System V +.Xr size +(using +.Op -A , +or +.Op --format=sysv ) , +or Berkeley +.Xr size +(using +.Op -B , +or +.Op --format=berkeley ) . +The default is the one-line format similar to Berkeley's. +.Pp +Here is an example of the Berkeley (default) format of output from +.Xr size : +.Bd -literal -offset indent +$ size --format=Berkeley ranlib size +text data bss dec hex filename +294880 81920 11592 388392 5ed28 ranlib +294880 81920 11888 388688 5ee50 size +.Ed +.Pp +This is the same data, but displayed closer to System V conventions: +.Pp +.Bd -literal -offset indent +$ size --format=SysV ranlib size +ranlib : +section size addr +\&.text 294880 8192 +\&.data 81920 303104 +\&.bss 11592 385024 +Total 388392 + + +size : +section size addr +\&.text 294880 8192 +\&.data 81920 303104 +\&.bss 11888 385024 +Total 388688 +.Ed +.Pp +.It --help +Show a summary of acceptable arguments and options. +.Pp +.It -d +.It -o +.It -x +.It --radix= Va number +Using one of these options, you can control whether the size of each section +is given in decimal ( +.Op -d , +or +.Op --radix=10 ) ; +octal ( +.Op -o , +or +.Op --radix=8 ) ; +or hexadecimal ( +.Op -x , +or +.Op --radix=16 ) . +In +.Op --radix= Va number , +only the three values (8, 10, 16) are supported. The total size is always +given in two radices; decimal and hexadecimal for +.Op -d +or +.Op -x +output, or octal and hexadecimal if you're using +.Op -o . +.Pp +.It -t +.It --totals +Show totals of all objects listed (Berkeley format listing mode only). +.Pp +.It --target= Va bfdname +Specify that the object-code format for +.Va objfile +is +.Va bfdname . +This option may not be necessary; +.Xr size +can automatically recognize many formats.See Section +.Dq Target Selection , +for more information. +.Pp +.It -V +.It --version +Display the version number of +.Xr size . +.El +.Pp +.Sh strings +.Bd -literal -offset indent +strings [-afov] [-min-len] + [-n min-len] [--bytes=min-len] + [-t radix] [--radix=radix] + [-e encoding] [--encoding=encoding] + [-] [--all] [--print-file-name] + [-T bfdname] [--target=bfdname] + [--help] [--version] file... +.Ed +.Pp +For each +.Va file +given, GNU +.Xr strings +prints the printable character sequences that are at least 4 characters long +(or the number given with the options below) and are followed by an unprintable +character. By default, it only prints the strings from the initialized and +loaded sections of object files; for other types of files, it prints the strings +from the whole file. +.Pp +.Xr strings +is mainly useful for determining the contents of non-text files. +.Pp +.Bl -tag -width Ds +.It -a +.It --all +.It - +Do not scan only the initialized and loaded sections of object files; scan +the whole files. +.Pp +.It -f +.It --print-file-name +Print the name of the file before each string. +.Pp +.It --help +Print a summary of the program usage on the standard output and exit. +.Pp +.It - Va min-len +.It -n Va min-len +.It --bytes= Va min-len +Print sequences of characters that are at least +.Va min-len +characters long, instead of the default 4. +.Pp +.It -o +Like +.Li -t o . +Some other versions of +.Xr strings +have +.Op -o +act like +.Li -t d +instead. Since we can not be compatible with both ways, we simply chose one. +.Pp +.It -t Va radix +.It --radix= Va radix +Print the offset within the file before each string. The single character +argument specifies the radix of the offset--- +.Li o +for octal, +.Li x +for hexadecimal, or +.Li d +for decimal. +.Pp +.It -e Va encoding +.It --encoding= Va encoding +Select the character encoding of the strings that are to be found. Possible +values for +.Va encoding +are: +.Li s += single-7-bit-byte characters (ASCII, ISO 8859, etc., default), +.Li S += single-8-bit-byte characters, +.Li b += 16-bit bigendian, +.Li l += 16-bit littleendian, +.Li B += 32-bit bigendian, +.Li L += 32-bit littleendian. Useful for finding wide character strings. +.Pp +.It -T Va bfdname +.It --target= Va bfdname +Specify an object code format other than your system's default format.See Section +.Dq Target Selection , +for more information. +.Pp +.It -v +.It --version +Print the program version number on the standard output and exit. +.El +.Pp +.Sh strip +.Bd -literal -offset indent +strip [-F bfdname |--target=bfdname] + [-I bfdname |--input-target=bfdname] + [-O bfdname |--output-target=bfdname] + [-s|--strip-all] + [-S|-g|-d|--strip-debug] + [-K symbolname |--keep-symbol=symbolname] + [-N symbolname |--strip-symbol=symbolname] + [-w|--wildcard] + [-x|--discard-all] [-X |--discard-locals] + [-R sectionname |--remove-section=sectionname] + [-o file] [-p|--preserve-dates] + [--keep-file-symbols] + [--only-keep-debug] + [-v |--verbose] [-V|--version] + [--help] [--info] + objfile... +.Ed +.Pp +GNU +.Xr strip +discards all symbols from object files +.Va objfile . +The list of object files may include archives. At least one object file must +be given. +.Pp +.Xr strip +modifies the files named in its argument, rather than writing modified copies +under different names. +.Pp +.Bl -tag -width Ds +.It -F Va bfdname +.It --target= Va bfdname +Treat the original +.Va objfile +as a file with the object code format +.Va bfdname , +and rewrite it in the same format.See Section +.Dq Target Selection , +for more information. +.Pp +.It --help +Show a summary of the options to +.Xr strip +and exit. +.Pp +.It --info +Display a list showing all architectures and object formats available. +.Pp +.It -I Va bfdname +.It --input-target= Va bfdname +Treat the original +.Va objfile +as a file with the object code format +.Va bfdname . +See Section.Dq Target Selection , +for more information. +.Pp +.It -O Va bfdname +.It --output-target= Va bfdname +Replace +.Va objfile +with a file in the output format +.Va bfdname . +See Section.Dq Target Selection , +for more information. +.Pp +.It -R Va sectionname +.It --remove-section= Va sectionname +Remove any section named +.Va sectionname +from the output file. This option may be given more than once. Note that using +this option inappropriately may make the output file unusable. +.Pp +.It -s +.It --strip-all +Remove all symbols. +.Pp +.It -g +.It -S +.It -d +.It --strip-debug +Remove debugging symbols only. +.Pp +.It --strip-unneeded +Remove all symbols that are not needed for relocation processing. +.Pp +.It -K Va symbolname +.It --keep-symbol= Va symbolname +When stripping symbols, keep symbol +.Va symbolname +even if it would normally be stripped. This option may be given more than +once. +.Pp +.It -N Va symbolname +.It --strip-symbol= Va symbolname +Remove symbol +.Va symbolname +from the source file. This option may be given more than once, and may be +combined with strip options other than +.Op -K . +.Pp +.It -o Va file +Put the stripped output in +.Va file , +rather than replacing the existing file. When this argument is used, only +one +.Va objfile +argument may be specified. +.Pp +.It -p +.It --preserve-dates +Preserve the access and modification dates of the file. +.Pp +.It -w +.It --wildcard +Permit regular expressions in +.Va symbolname +s used in other command line options. The question mark (?), asterisk (*), +backslash (\e) and square brackets ([]) operators can be used anywhere in the +symbol name. If the first character of the symbol name is the exclamation +point (!) then the sense of the switch is reversed for that symbol. For example: +.Pp +.Bd -literal -offset indent + -w -K !foo -K fo* +.Ed +.Pp +would cause strip to only keep symbols that start with the letters \(lqfo\(rq, but +to discard the symbol \(lqfoo\(rq. +.Pp +.It -x +.It --discard-all +Remove non-global symbols. +.Pp +.It -X +.It --discard-locals +Remove compiler-generated local symbols. (These usually start with +.Li L +or +.Li . . ) +.Pp +.It --keep-file-symbols +When stripping a file, perhaps with +.Op --strip-debug +or +.Op --strip-unneeded , +retain any symbols specifying source file names, which would otherwise get +stripped. +.Pp +.It --only-keep-debug +Strip a file, removing contents of any sections that would not be stripped +by +.Op --strip-debug +and leaving the debugging sections intact. In ELF files, this preserves all +note sections in the output. +.Pp +The intention is that this option will be used in conjunction with +.Op --add-GNU-debuglink +to create a two part executable. One a stripped binary which will occupy less +space in RAM and in a distribution and the second a debugging information +file which is only needed if debugging abilities are required. The suggested +procedure to create these files is as follows: +.Pp +.Bl -enum +.It +Link the executable as normal. Assuming that is is called +.Li foo +then... +.It +Run +.Li objcopy --only-keep-debug foo foo.dbg +to +create a file containing the debugging info. +.It +Run +.Li objcopy --strip-debug foo +to create a +stripped executable. +.It +Run +.Li objcopy --add-GNU-debuglink=foo.dbg foo +to add a link to the debugging info into the stripped executable. +.El +.Pp +Note - the choice of +.Li .dbg +as an extension for the debug info file is arbitrary. Also the +.Li --only-keep-debug +step is optional. You could instead do this: +.Pp +.Bl -enum +.It +Link the executable as normal. +.It +Copy +.Li foo +to +.Li foo.full +.It +Run +.Li strip --strip-debug foo +.It +Run +.Li objcopy --add-GNU-debuglink=foo.full foo +.El +.Pp +ie the file pointed to by the +.Op --add-GNU-debuglink +can be the full executable. It does not have to be a file created by the +.Op --only-keep-debug +switch. +.Pp +Note - this switch is only intended for use on fully linked files. It does +not make sense to use it on object files where the debugging information may +be incomplete. Besides the GNU_debuglink feature currently only supports the +presence of one filename containing debugging information, not multiple filenames +on a one-per-object-file basis. +.Pp +.It -V +.It --version +Show the version number for +.Xr strip . +.Pp +.It -v +.It --verbose +Verbose output: list all object files modified. In the case of archives, +.Li strip -v +lists all members of the archive. +.El +.Pp +.Sh c++filt +.Bd -literal -offset indent +c++filt [-_|--strip-underscores] + [-n|--no-strip-underscores] + [-p|--no-params] + [-t|--types] + [-i|--no-verbose] + [-s format|--format=format] + [--help] [--version] [symbol...] +.Ed +.Pp +The C++ and Java languages provide function overloading, which means that +you can write many functions with the same name, providing that each function +takes parameters of different types. In order to be able to distinguish these +similarly named functions C++ and Java encode them into a low-level assembler +name which uniquely identifies each different version. This process is known +as +.Em mangling . +The +.Xr c++filt +program does the inverse mapping: it decodes ( +.Em demangles ) +low-level names into user-level names so that they can be read. +.Pp +Every alphanumeric word (consisting of letters, digits, underscores, dollars, +or periods) seen in the input is a potential mangled name. If the name decodes +into a C++ name, the C++ name replaces the low-level name in the output, otherwise +the original word is output. In this way you can pass an entire assembler +source file, containing mangled names, through +.Xr c++filt +and see the same source file containing demangled names. +.Pp +You can also use +.Xr c++filt +to decipher individual symbols by passing them on the command line: +.Pp +.Bd -literal -offset indent +c++filt symbol +.Ed +.Pp +If no +.Va symbol +arguments are given, +.Xr c++filt +reads symbol names from the standard input instead. All the results are printed +on the standard output. The difference between reading names from the command +line versus reading names from the standard input is that command line arguments +are expected to be just mangled names and no checking is performed to separate +them from surrounding text. Thus for example: +.Pp +.Bd -literal -offset indent +c++filt -n _Z1fv +.Ed +.Pp +will work and demangle the name to \(lqf()\(rq whereas: +.Pp +.Bd -literal -offset indent +c++filt -n _Z1fv, +.Ed +.Pp +will not work. (Note the extra comma at the end of the mangled name which +makes it invalid). This command however will work: +.Pp +.Bd -literal -offset indent +echo _Z1fv, | c++filt -n +.Ed +.Pp +and will display \(lqf(),\(rq ie the demangled name followed by a trailing comma. +This behaviour is because when the names are read from the standard input +it is expected that they might be part of an assembler source file where there +might be extra, extraneous characters trailing after a mangled name. eg: +.Pp +.Bd -literal -offset indent + .type _Z1fv, @function +.Ed +.Pp +.Bl -tag -width Ds +.It -_ +.It --strip-underscores +On some systems, both the C and C++ compilers put an underscore in front of +every name. For example, the C name +.Li foo +gets the low-level name +.Li _foo . +This option removes the initial underscore. Whether +.Xr c++filt +removes the underscore by default is target dependent. +.Pp +.It -j +.It --java +Prints demangled names using Java syntax. The default is to use C++ syntax. +.Pp +.It -n +.It --no-strip-underscores +Do not remove the initial underscore. +.Pp +.It -p +.It --no-params +When demangling the name of a function, do not display the types of the function's +parameters. +.Pp +.It -t +.It --types +Attempt to demangle types as well as function names. This is disabled by default +since mangled types are normally only used internally in the compiler, and +they can be confused with non-mangled names. eg a function called \(lqa\(rq treated +as a mangled type name would be demangled to \(lqsigned char\(rq. +.Pp +.It -i +.It --no-verbose +Do not include implementation details (if any) in the demangled output. +.Pp +.It -s Va format +.It --format= Va format +.Xr c++filt +can decode various methods of mangling, used by different compilers. The argument +to this option selects which method it uses: +.Pp +.Bl -tag -width Ds +.It auto +Automatic selection based on executable (the default method) +.It GNU +the one used by the GNU C++ compiler (g++) +.It lucid +the one used by the Lucid compiler (lcc) +.It arm +the one specified by the C++ Annotated Reference Manual +.It hp +the one used by the HP compiler (aCC) +.It edg +the one used by the EDG compiler +.It GNU-v3 +the one used by the GNU C++ compiler (g++) with the V3 ABI. +.It java +the one used by the GNU Java compiler (gcj) +.It gnat +the one used by the GNU Ada compiler (GNAT). +.El +.Pp +.It --help +Print a summary of the options to +.Xr c++filt +and exit. +.Pp +.It --version +Print the version number of +.Xr c++filt +and exit. +.El +.Pp +.Qo +.Em Warning: +.Xr c++filt +is a new utility, and the details of its user interface are subject to change +in future releases. In particular, a command-line option may be required in +the future to decode a name passed as an argument on the command line; in +other words, +.Pp +.Bd -literal -offset indent +c++filt symbol +.Ed +.Pp +may in a future release become +.Pp +.Bd -literal -offset indent +c++filt option symbol +.Ed +.Qc +.Pp +.Sh addr2line +.Bd -literal -offset indent +addr2line [-b bfdname|--target=bfdname] + [-C|--demangle[=style]] + [-e filename|--exe=filename] + [-f|--functions] [-s|--basename] + [-i|--inlines] + [-j|--section=name] + [-H|--help] [-V|--version] + [addr addr ...] +.Ed +.Pp +.Xr addr2line +translates addresses into file names and line numbers. Given an address in +an executable or an offset in a section of a relocatable object, it uses the +debugging information to figure out which file name and line number are associated +with it. +.Pp +The executable or relocatable object to use is specified with the +.Op -e +option. The default is the file +.Pa a.out . +The section in the relocatable object to use is specified with the +.Op -j +option. +.Pp +.Xr addr2line +has two modes of operation. +.Pp +In the first, hexadecimal addresses are specified on the command line, and +.Xr addr2line +displays the file name and line number for each address. +.Pp +In the second, +.Xr addr2line +reads hexadecimal addresses from standard input, and prints the file name +and line number for each address on standard output. In this mode, +.Xr addr2line +may be used in a pipe to convert dynamically chosen addresses. +.Pp +The format of the output is +.Li FILENAME:LINENO . +The file name and line number for each address is printed on a separate line. +If the +.Xr -f +option is used, then each +.Li FILENAME:LINENO +line is preceded by a +.Li FUNCTIONNAME +line which is the name of the function containing the address. +.Pp +If the file name or function name can not be determined, +.Xr addr2line +will print two question marks in their place. If the line number can not be +determined, +.Xr addr2line +will print 0. +.Pp +The long and short forms of options, shown here as alternatives, are equivalent. +.Pp +.Bl -tag -width Ds +.It -b Va bfdname +.It --target= Va bfdname +Specify that the object-code format for the object files is +.Va bfdname . +.Pp +.It -C +.It --demangle[= Va style] +Decode ( +.Em demangle ) +low-level symbol names into user-level names. Besides removing any initial +underscore prepended by the system, this makes C++ function names readable. +Different compilers have different mangling styles. The optional demangling +style argument can be used to choose an appropriate demangling style for your +compiler.See Section +.Dq c++filt , +for more information on demangling. +.Pp +.It -e Va filename +.It --exe= Va filename +Specify the name of the executable for which addresses should be translated. +The default file is +.Pa a.out . +.Pp +.It -f +.It --functions +Display function names as well as file and line number information. +.Pp +.It -s +.It --basenames +Display only the base of each file name. +.Pp +.It -i +.It --inlines +If the address belongs to a function that was inlined, the source information +for all enclosing scopes back to the first non-inlined function will also +be printed. For example, if +.Li main +inlines +.Li callee1 +which inlines +.Li callee2 , +and address is from +.Li callee2 , +the source information for +.Li callee1 +and +.Li main +will also be printed. +.Pp +.It -j +.It --section +Read offsets relative to the specified section instead of absolute addresses. +.El +.Pp +.Sh nlmconv +.Xr nlmconv +converts a relocatable object file into a NetWare Loadable Module. +.Pp +.Qo +.Em Warning: +.Xr nlmconv +is not always built as part of the binary utilities, since it is only useful +for NLM targets. +.Qc +.Pp +.Bd -literal -offset indent +nlmconv [-I bfdname|--input-target=bfdname] + [-O bfdname|--output-target=bfdname] + [-T headerfile|--header-file=headerfile] + [-d|--debug] [-l linker|--linker=linker] + [-h|--help] [-V|--version] + infile outfile +.Ed +.Pp +.Xr nlmconv +converts the relocatable +.Li i386 +object file +.Va infile +into the NetWare Loadable Module +.Va outfile , +optionally reading +.Va headerfile +for NLM header information. For instructions on writing the NLM command file +language used in header files, see the +.Li linkers +section, +.Li NLMLINK +in particular, of the +.Em NLM Development and Tools Overview , +which is part of the NLM Software Developer's Kit (\(lqNLM SDK\(rq), available from +Novell, Inc. +.Xr nlmconv +uses the GNU Binary File Descriptor library to read +.Va infile ; +see BFD,,BFD,ld.info,Using LD, for more information. +.Pp +.Xr nlmconv +can perform a link step. In other words, you can list more than one object +file for input if you list them in the definitions file (rather than simply +specifying one input file on the command line). In this case, +.Xr nlmconv +calls the linker for you. +.Pp +.Bl -tag -width Ds +.It -I Va bfdname +.It --input-target= Va bfdname +Object format of the input file. +.Xr nlmconv +can usually determine the format of a given file (so no default is necessary).See Section +.Dq Target Selection , +for more information. +.Pp +.It -O Va bfdname +.It --output-target= Va bfdname +Object format of the output file. +.Xr nlmconv +infers the output format based on the input format, e.g. for a +.Li i386 +input file the output format is +.Li nlm32-i386 . +See Section.Dq Target Selection , +for more information. +.Pp +.It -T Va headerfile +.It --header-file= Va headerfile +Reads +.Va headerfile +for NLM header information. For instructions on writing the NLM command file +language used in header files, see see the +.Li linkers +section, of the +.Em NLM Development and Tools Overview , +which is part of the NLM Software Developer's Kit, available from Novell, +Inc. +.Pp +.It -d +.It --debug +Displays (on standard error) the linker command line used by +.Xr nlmconv . +.Pp +.It -l Va linker +.It --linker= Va linker +Use +.Va linker +for any linking. +.Va linker +can be an absolute or a relative pathname. +.Pp +.It -h +.It --help +Prints a usage summary. +.Pp +.It -V +.It --version +Prints the version number for +.Xr nlmconv . +.El +.Pp +.Sh windmc +.Xr windmc +may be used to generator Windows message resources. +.Pp +.Qo +.Em Warning: +.Xr windmc +is not always built as part of the binary utilities, since it is only useful +for Windows targets. +.Qc +.Pp +.Bd -literal -offset indent +windmc [options] input-file +.Ed +.Pp +.Xr windmc +reads message definitions from an input file (.mc) and translate them into +a set of output files. The output files may be of four kinds: +.Pp +.Bl -tag -width Ds +.It h +A C header file containing the message definitions. +.Pp +.It rc +A resource file compilable by the +.Xr windres +tool. +.Pp +.It bin +One or more binary files containing the resource data for a specific message +language. +.Pp +.It dbg +A C include file that maps message id's to their symbolic name. +.El +.Pp +The exact description of these different formats is available in documentation +from Microsoft. +.Pp +When +.Xr windmc +converts from the +.Li mc +format to the +.Li bin +format, +.Li rc , +.Li h , +and optional +.Li dbg +it is acting like the Windows Message Compiler. +.Pp +.Bl -tag -width Ds +.It -a +.It --ascii_in +Specifies that the input file specified is ANSI. This is the default behaviour. +.Pp +.It -A +.It --ascii_out +Specifies that messages in the output +.Li bin +files should be in ANSI format. +.Pp +.It -b +.It --binprefix +Specifies that +.Li bin +filenames should have to be prefixed by the basename of the source file. +.Pp +.It -c +.It --customflag +Sets the customer bit in all message id's. +.Pp +.It -C Va codepage +.It --codepage_in Va codepage +Sets the default codepage to be used to convert input file to UTF16. The default +is ocdepage 1252. +.Pp +.It -d +.It --decimal_values +Outputs the constants in the header file in decimal. Default is using hexadecimal +output. +.Pp +.It -e Va ext +.It --extension Va ext +The extension for the header file. The default is .h extension. +.Pp +.It -F Va target +.It --target Va target +Specify the BFD format to use for a bin file as output. This is a BFD target +name; you can use the +.Op --help +option to see a list of supported targets. Normally +.Xr windmc +will use the default format, which is the first one listed by the +.Op --help +option. Target Selection. +.Pp +.It -h Va path +.It --headerdir Va path +The target directory of the generated header file. The default is the current +directory. +.Pp +.It -H +.It --help +Displays a list of command line options and then exits. +.Pp +.It -m Va characters +.It --maxlength Va characters +Instructs +.Xr windmc +to generate a warning if the length of any message exceeds the number specified. +.Pp +.It -n +.It --nullterminate +Terminate message text in +.Li bin +files by zero. By default they are terminated by CR/LF. +.Pp +.It -o +.It --hresult_use +Not yet implemented. Instructs +.Li windmc +to generate an OLE2 header file, using HRESULT definitions. Status codes are +used if the flag is not specified. +.Pp +.It -O Va codepage +.It --codepage_out Va codepage +Sets the default codepage to be used to output text files. The default is +ocdepage 1252. +.Pp +.It -r Va path +.It --rcdir Va path +The target directory for the generated +.Li rc +script and the generated +.Li bin +files that the resource compiler script includes. The default is the current +directory. +.Pp +.It -u +.It --unicode_in +Specifies that the input file is UTF16. +.Pp +.It -U +.It --unicode_out +Specifies that messages in the output +.Li bin +file should be in UTF16 format. This is the default behaviour. +.Pp +.It -v +.It --verbose +Enable verbose mode. This tells you what the preprocessor is if you didn't +specify one. +.Pp +.It -V +.It --version +Prints the version number for +.Xr windres . +.Pp +.It -x Va path +.It --xdgb Va path +The path of the +.Li dbg +C include file that maps message id's to the symbolic name. No such file is +generated without specifying the switch. +.El +.Pp +.Sh windres +.Xr windres +may be used to manipulate Windows resources. +.Pp +.Qo +.Em Warning: +.Xr windres +is not always built as part of the binary utilities, since it is only useful +for Windows targets. +.Qc +.Pp +.Bd -literal -offset indent +windres [options] [input-file] [output-file] +.Ed +.Pp +.Xr windres +reads resources from an input file and copies them into an output file. Either +file may be in one of three formats: +.Pp +.Bl -tag -width Ds +.It rc +A text format read by the Resource Compiler. +.Pp +.It res +A binary format generated by the Resource Compiler. +.Pp +.It coff +A COFF object or executable. +.El +.Pp +The exact description of these different formats is available in documentation +from Microsoft. +.Pp +When +.Xr windres +converts from the +.Li rc +format to the +.Li res +format, it is acting like the Windows Resource Compiler. When +.Xr windres +converts from the +.Li res +format to the +.Li coff +format, it is acting like the Windows +.Li CVTRES +program. +.Pp +When +.Xr windres +generates an +.Li rc +file, the output is similar but not identical to the format expected for the +input. When an input +.Li rc +file refers to an external filename, an output +.Li rc +file will instead include the file contents. +.Pp +If the input or output format is not specified, +.Xr windres +will guess based on the file name, or, for the input file, the file contents. +A file with an extension of +.Pa .rc +will be treated as an +.Li rc +file, a file with an extension of +.Pa .res +will be treated as a +.Li res +file, and a file with an extension of +.Pa .o +or +.Pa .exe +will be treated as a +.Li coff +file. +.Pp +If no output file is specified, +.Xr windres +will print the resources in +.Li rc +format to standard output. +.Pp +The normal use is for you to write an +.Li rc +file, use +.Xr windres +to convert it to a COFF object file, and then link the COFF file into your +application. This will make the resources described in the +.Li rc +file available to Windows. +.Pp +.Bl -tag -width Ds +.It -i Va filename +.It --input Va filename +The name of the input file. If this option is not used, then +.Xr windres +will use the first non-option argument as the input file name. If there are +no non-option arguments, then +.Xr windres +will read from standard input. +.Xr windres +can not read a COFF file from standard input. +.Pp +.It -o Va filename +.It --output Va filename +The name of the output file. If this option is not used, then +.Xr windres +will use the first non-option argument, after any used for the input file +name, as the output file name. If there is no non-option argument, then +.Xr windres +will write to standard output. +.Xr windres +can not write a COFF file to standard output. Note, for compatibility with +.Xr rc +the option +.Op -fo +is also accepted, but its use is not recommended. +.Pp +.It -J Va format +.It --input-format Va format +The input format to read. +.Va format +may be +.Li res , +.Li rc , +or +.Li coff . +If no input format is specified, +.Xr windres +will guess, as described above. +.Pp +.It -O Va format +.It --output-format Va format +The output format to generate. +.Va format +may be +.Li res , +.Li rc , +or +.Li coff . +If no output format is specified, +.Xr windres +will guess, as described above. +.Pp +.It -F Va target +.It --target Va target +Specify the BFD format to use for a COFF file as input or output. This is +a BFD target name; you can use the +.Op --help +option to see a list of supported targets. Normally +.Xr windres +will use the default format, which is the first one listed by the +.Op --help +option. Target Selection. +.Pp +.It --preprocessor Va program +When +.Xr windres +reads an +.Li rc +file, it runs it through the C preprocessor first. This option may be used +to specify the preprocessor to use, including any leading arguments. The default +preprocessor argument is +.Li gcc -E -xc-header -DRC_INVOKED . +.Pp +.It -I Va directory +.It --include-dir Va directory +Specify an include directory to use when reading an +.Li rc +file. +.Xr windres +will pass this to the preprocessor as an +.Op -I +option. +.Xr windres +will also search this directory when looking for files named in the +.Li rc +file. If the argument passed to this command matches any of the supported +.Va formats +(as described in the +.Op -J +option), it will issue a deprecation warning, and behave just like the +.Op -J +option. New programs should not use this behaviour. If a directory happens +to match a +.Va format , +simple prefix it with +.Li ./ +to disable the backward compatibility. +.Pp +.It -D Va target +.It --define Va sym[= Va val] +Specify a +.Op -D +option to pass to the preprocessor when reading an +.Li rc +file. +.Pp +.It -U Va target +.It --undefine Va sym +Specify a +.Op -U +option to pass to the preprocessor when reading an +.Li rc +file. +.Pp +.It -r +Ignored for compatibility with rc. +.Pp +.It -v +Enable verbose mode. This tells you what the preprocessor is if you didn't +specify one. +.Pp +.It -c Va val +.It --codepage Va val +Specify the default codepage to use when reading an +.Li rc +file. +.Va val +should be a hexadecimal prefixed by +.Li 0x +or decimal codepage code. The valid range is from zero up to 0xffff, but the +validity of the codepage is host and configuration dependent. +.Pp +.It -l Va val +.It --language Va val +Specify the default language to use when reading an +.Li rc +file. +.Va val +should be a hexadecimal language code. The low eight bits are the language, +and the high eight bits are the sublanguage. +.Pp +.It --use-temp-file +Use a temporary file to instead of using popen to read the output of the preprocessor. +Use this option if the popen implementation is buggy on the host (eg., certain +non-English language versions of Windows 95 and Windows 98 are known to have +buggy popen where the output will instead go the console). +.Pp +.It --no-use-temp-file +Use popen, not a temporary file, to read the output of the preprocessor. This +is the default behaviour. +.Pp +.It -h +.It --help +Prints a usage summary. +.Pp +.It -V +.It --version +Prints the version number for +.Xr windres . +.Pp +.It --yydebug +If +.Xr windres +is compiled with +.Li YYDEBUG +defined as +.Li 1 , +this will turn on parser debugging. +.El +.Pp +.Sh dlltool +.Xr dlltool +is used to create the files needed to create dynamic link libraries (DLLs) +on systems which understand PE format image files such as Windows. A DLL contains +an export table which contains information that the runtime loader needs to +resolve references from a referencing program. +.Pp +The export table is generated by this program by reading in a +.Pa .def +file or scanning the +.Pa .a +and +.Pa .o +files which will be in the DLL. A +.Pa .o +file can contain information in special +.Li .drectve +sections with export information. +.Pp +.Qo +.Em Note: +.Xr dlltool +is not always built as part of the binary utilities, since it is only useful +for those targets which support DLLs. +.Qc +.Pp +.Bd -literal -offset indent +dlltool [-d|--input-def def-file-name] + [-b|--base-file base-file-name] + [-e|--output-exp exports-file-name] + [-z|--output-def def-file-name] + [-l|--output-lib library-file-name] + [--export-all-symbols] [--no-export-all-symbols] + [--exclude-symbols list] + [--no-default-excludes] + [-S|--as path-to-assembler] [-f|--as-flags options] + [-D|--dllname name] [-m|--machine machine] + [-a|--add-indirect] + [-U|--add-underscore] [--add-stdcall-underscore] + [-k|--kill-at] [-A|--add-stdcall-alias] + [-p|--ext-prefix-alias prefix] + [-x|--no-idata4] [-c|--no-idata5] [-i|--interwork] + [-n|--nodelete] [-t|--temp-prefix prefix] + [-v|--verbose] + [-h|--help] [-V|--version] + [object-file ...] +.Ed +.Pp +.Xr dlltool +reads its inputs, which can come from the +.Op -d +and +.Op -b +options as well as object files specified on the command line. It then processes +these inputs and if the +.Op -e +option has been specified it creates a exports file. If the +.Op -l +option has been specified it creates a library file and if the +.Op -z +option has been specified it creates a def file. Any or all of the +.Op -e , +.Op -l +and +.Op -z +options can be present in one invocation of dlltool. +.Pp +When creating a DLL, along with the source for the DLL, it is necessary to +have three other files. +.Xr dlltool +can help with the creation of these files. +.Pp +The first file is a +.Pa .def +file which specifies which functions are exported from the DLL, which functions +the DLL imports, and so on. This is a text file and can be created by hand, +or +.Xr dlltool +can be used to create it using the +.Op -z +option. In this case +.Xr dlltool +will scan the object files specified on its command line looking for those +functions which have been specially marked as being exported and put entries +for them in the +.Pa .def +file it creates. +.Pp +In order to mark a function as being exported from a DLL, it needs to have +an +.Op -export:<name_of_function> +entry in the +.Li .drectve +section of the object file. This can be done in C by using the asm() operator: +.Pp +.Bd -literal -offset indent + asm (".section .drectve"); + asm (".ascii \e"-export:my_func\e""); + + int my_func (void) { ... } +.Ed +.Pp +The second file needed for DLL creation is an exports file. This file is linked +with the object files that make up the body of the DLL and it handles the +interface between the DLL and the outside world. This is a binary file and +it can be created by giving the +.Op -e +option to +.Xr dlltool +when it is creating or reading in a +.Pa .def +file. +.Pp +The third file needed for DLL creation is the library file that programs will +link with in order to access the functions in the DLL. This file can be created +by giving the +.Op -l +option to dlltool when it is creating or reading in a +.Pa .def +file. +.Pp +.Xr dlltool +builds the library file by hand, but it builds the exports file by creating +temporary files containing assembler statements and then assembling these. +The +.Op -S +command line option can be used to specify the path to the assembler that +dlltool will use, and the +.Op -f +option can be used to pass specific flags to that assembler. The +.Op -n +can be used to prevent dlltool from deleting these temporary assembler files +when it is done, and if +.Op -n +is specified twice then this will prevent dlltool from deleting the temporary +object files it used to build the library. +.Pp +Here is an example of creating a DLL from a source file +.Li dll.c +and also creating a program (from an object file called +.Li program.o ) +that uses that DLL: +.Pp +.Bd -literal -offset indent + gcc -c dll.c + dlltool -e exports.o -l dll.lib dll.o + gcc dll.o exports.o -o dll.dll + gcc program.o dll.lib -o program +.Ed +.Pp +The command line options have the following meanings: +.Pp +.Bl -tag -width Ds +.It -d Va filename +.It --input-def Va filename +Specifies the name of a +.Pa .def +file to be read in and processed. +.Pp +.It -b Va filename +.It --base-file Va filename +Specifies the name of a base file to be read in and processed. The contents +of this file will be added to the relocation section in the exports file generated +by dlltool. +.Pp +.It -e Va filename +.It --output-exp Va filename +Specifies the name of the export file to be created by dlltool. +.Pp +.It -z Va filename +.It --output-def Va filename +Specifies the name of the +.Pa .def +file to be created by dlltool. +.Pp +.It -l Va filename +.It --output-lib Va filename +Specifies the name of the library file to be created by dlltool. +.Pp +.It --export-all-symbols +Treat all global and weak defined symbols found in the input object files +as symbols to be exported. There is a small list of symbols which are not +exported by default; see the +.Op --no-default-excludes +option. You may add to the list of symbols to not export by using the +.Op --exclude-symbols +option. +.Pp +.It --no-export-all-symbols +Only export symbols explicitly listed in an input +.Pa .def +file or in +.Li .drectve +sections in the input object files. This is the default behaviour. The +.Li .drectve +sections are created by +.Li dllexport +attributes in the source code. +.Pp +.It --exclude-symbols Va list +Do not export the symbols in +.Va list . +This is a list of symbol names separated by comma or colon characters. The +symbol names should not contain a leading underscore. This is only meaningful +when +.Op --export-all-symbols +is used. +.Pp +.It --no-default-excludes +When +.Op --export-all-symbols +is used, it will by default avoid exporting certain special symbols. The current +list of symbols to avoid exporting is +.Li DllMain@12 , +.Li DllEntryPoint@0 , +.Li impure_ptr . +You may use the +.Op --no-default-excludes +option to go ahead and export these special symbols. This is only meaningful +when +.Op --export-all-symbols +is used. +.Pp +.It -S Va path +.It --as Va path +Specifies the path, including the filename, of the assembler to be used to +create the exports file. +.Pp +.It -f Va options +.It --as-flags Va options +Specifies any specific command line options to be passed to the assembler +when building the exports file. This option will work even if the +.Op -S +option is not used. This option only takes one argument, and if it occurs +more than once on the command line, then later occurrences will override earlier +occurrences. So if it is necessary to pass multiple options to the assembler +they should be enclosed in double quotes. +.Pp +.It -D Va name +.It --dll-name Va name +Specifies the name to be stored in the +.Pa .def +file as the name of the DLL when the +.Op -e +option is used. If this option is not present, then the filename given to +the +.Op -e +option will be used as the name of the DLL. +.Pp +.It -m Va machine +.It -machine Va machine +Specifies the type of machine for which the library file should be built. +.Xr dlltool +has a built in default type, depending upon how it was created, but this option +can be used to override that. This is normally only useful when creating DLLs +for an ARM processor, when the contents of the DLL are actually encode using +Thumb instructions. +.Pp +.It -a +.It --add-indirect +Specifies that when +.Xr dlltool +is creating the exports file it should add a section which allows the exported +functions to be referenced without using the import library. Whatever the +hell that means! +.Pp +.It -U +.It --add-underscore +Specifies that when +.Xr dlltool +is creating the exports file it should prepend an underscore to the names +of +.Em all +exported symbols. +.Pp +.It --add-stdcall-underscore +Specifies that when +.Xr dlltool +is creating the exports file it should prepend an underscore to the names +of exported +.Em stdcall +functions. Variable names and non-stdcall function names are not modified. +This option is useful when creating GNU-compatible import libs for third party +DLLs that were built with MS-Windows tools. +.Pp +.It -k +.It --kill-at +Specifies that when +.Xr dlltool +is creating the exports file it should not append the string +.Li @ <number> . +These numbers are called ordinal numbers and they represent another way of +accessing the function in a DLL, other than by name. +.Pp +.It -A +.It --add-stdcall-alias +Specifies that when +.Xr dlltool +is creating the exports file it should add aliases for stdcall symbols without +.Li @ <number> +in addition to the symbols with +.Li @ <number> . +.Pp +.It -p +.It --ext-prefix-alias Va prefix +Causes +.Xr dlltool +to create external aliases for all DLL imports with the specified prefix. +The aliases are created for both external and import symbols with no leading +underscore. +.Pp +.It -x +.It --no-idata4 +Specifies that when +.Xr dlltool +is creating the exports and library files it should omit the +.Li .idata4 +section. This is for compatibility with certain operating systems. +.Pp +.It -c +.It --no-idata5 +Specifies that when +.Xr dlltool +is creating the exports and library files it should omit the +.Li .idata5 +section. This is for compatibility with certain operating systems. +.Pp +.It -i +.It --interwork +Specifies that +.Xr dlltool +should mark the objects in the library file and exports file that it produces +as supporting interworking between ARM and Thumb code. +.Pp +.It -n +.It --nodelete +Makes +.Xr dlltool +preserve the temporary assembler files it used to create the exports file. +If this option is repeated then dlltool will also preserve the temporary object +files it uses to create the library file. +.Pp +.It -t Va prefix +.It --temp-prefix Va prefix +Makes +.Xr dlltool +use +.Va prefix +when constructing the names of temporary assembler and object files. By default, +the temp file prefix is generated from the pid. +.Pp +.It -v +.It --verbose +Make dlltool describe what it is doing. +.Pp +.It -h +.It --help +Displays a list of command line options and then exits. +.Pp +.It -V +.It --version +Displays dlltool's version number and then exits. +.Pp +.El +.Ss The format of the Xr dlltool Pa .def file +A +.Pa .def +file contains any number of the following commands: +.Pp +.Bl -tag -width Ds +.It Li NAME Va name Li [ , Va base Li ] +The result is going to be named +.Va name +.Li .exe . +.Pp +.It Li LIBRARY Va name Li [ , Va base Li ] +The result is going to be named +.Va name +.Li .dll . +.Pp +.It Li EXPORTS ( ( ( Va name1 Li [ = Va name2 Li ] ) | ( Va name1 Li = Va module-name Li . Va external-name Li ) ) +.It Li [ Va integer Li ] [ NONAME ] [ CONSTANT ] [ DATA ] [ PRIVATE ] ) * +Declares +.Va name1 +as an exported symbol from the DLL, with optional ordinal number +.Va integer , +or declares +.Va name1 +as an alias (forward) of the function +.Va external-name +in the DLL +.Va module-name . +.Pp +.It Li IMPORTS ( ( Va internal-name Li = Va module-name Li . Va integer Li ) | [ Va internal-name Li = ] Va module-name Li . Va external-name Li ) ) * +Declares that +.Va external-name +or the exported function whose ordinal number is +.Va integer +is to be imported from the file +.Va module-name . +If +.Va internal-name +is specified then this is the name that the imported function will be referred +to in the body of the DLL. +.Pp +.It Li DESCRIPTION Va string +Puts +.Va string +into the output +.Pa .exp +file in the +.Li .rdata +section. +.Pp +.It Li STACKSIZE Va number-reserve Li [, Va number-commit Li ] +.It Li HEAPSIZE Va number-reserve Li [, Va number-commit Li ] +Generates +.Li --stack +or +.Li --heap +.Va number-reserve +, +.Va number-commit +in the output +.Li .drectve +section. The linker will see this and act upon it. +.Pp +.It Li CODE Va attr Li + +.It Li DATA Va attr Li + +.It Li SECTIONS ( Va section-name Va attr Li + ) * +Generates +.Li --attr +.Va section-name +.Va attr +in the output +.Li .drectve +section, where +.Va attr +is one of +.Li READ , +.Li WRITE , +.Li EXECUTE +or +.Li SHARED . +The linker will see this and act upon it. +.Pp +.El +.Sh readelf +.Bd -literal -offset indent +readelf [-a|--all] + [-h|--file-header] + [-l|--program-headers|--segments] + [-S|--section-headers|--sections] + [-g|--section-groups] + [-t|--section-details] + [-e|--headers] + [-s|--syms|--symbols] + [-n|--notes] + [-r|--relocs] + [-u|--unwind] + [-d|--dynamic] + [-V|--version-info] + [-A|--arch-specific] + [-D|--use-dynamic] + [-x <number or name>|--hex-dump=<number or name>] + [-w[liaprmfFsoR]| + --debug-dump[=line,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges]] + [-I|-histogram] + [-v|--version] + [-W|--wide] + [-H|--help] + elffile... +.Ed +.Pp +.Xr readelf +displays information about one or more ELF format object files. The options +control what particular information to display. +.Pp +.Va elffile +\&...are the object files to be examined. 32-bit and 64-bit ELF files are supported, +as are archives containing ELF files. +.Pp +This program performs a similar function to +.Xr objdump +but it goes into more detail and it exists independently of the bfd library, +so if there is a bug in bfd then readelf will not be affected. +.Pp +The long and short forms of options, shown here as alternatives, are equivalent. +At least one option besides +.Li -v +or +.Li -H +must be given. +.Pp +.Bl -tag -width Ds +.It -a +.It --all +Equivalent to specifying +.Op --file-header , +.Op --program-headers , +.Op --sections , +.Op --symbols , +.Op --relocs , +.Op --dynamic , +.Op --notes +and +.Op --version-info . +.Pp +.It -h +.It --file-header +Displays the information contained in the ELF header at the start of the file. +.Pp +.It -l +.It --program-headers +.It --segments +Displays the information contained in the file's segment headers, if it has +any. +.Pp +.It -S +.It --sections +.It --section-headers +Displays the information contained in the file's section headers, if it has +any. +.Pp +.It -g +.It --section-groups +Displays the information contained in the file's section groups, if it has +any. +.Pp +.It -t +.It --section-details +Displays the detailed section information. Implies +.Op -S . +.Pp +.It -s +.It --symbols +.It --syms +Displays the entries in symbol table section of the file, if it has one. +.Pp +.It -e +.It --headers +Display all the headers in the file. Equivalent to +.Op -h -l -S . +.Pp +.It -n +.It --notes +Displays the contents of the NOTE segments and/or sections, if any. +.Pp +.It -r +.It --relocs +Displays the contents of the file's relocation section, if it has one. +.Pp +.It -u +.It --unwind +Displays the contents of the file's unwind section, if it has one. Only the +unwind sections for IA64 ELF files are currently supported. +.Pp +.It -d +.It --dynamic +Displays the contents of the file's dynamic section, if it has one. +.Pp +.It -V +.It --version-info +Displays the contents of the version sections in the file, it they exist. +.Pp +.It -A +.It --arch-specific +Displays architecture-specific information in the file, if there is any. +.Pp +.It -D +.It --use-dynamic +When displaying symbols, this option makes +.Xr readelf +use the symbol table in the file's dynamic section, rather than the one in +the symbols section. +.Pp +.It -x <number or name> +.It --hex-dump=<number or name> +Displays the contents of the indicated section as a hexadecimal dump. A number +identifies a particular section by index in the section table; any other string +identifies all sections with that name in the object file. +.Pp +.It -w[liaprmfFsoR] +.It --debug-dump[=line,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges] +Displays the contents of the debug sections in the file, if any are present. +If one of the optional letters or words follows the switch then only data +found in those specific sections will be dumped. +.Pp +.It -I +.It --histogram +Display a histogram of bucket list lengths when displaying the contents of +the symbol tables. +.Pp +.It -v +.It --version +Display the version number of readelf. +.Pp +.It -W +.It --wide +Don't break output lines to fit into 80 columns. By default +.Xr readelf +breaks section header and segment listing lines for 64-bit ELF files, so that +they fit into 80 columns. This option causes +.Xr readelf +to print each section header resp. each segment one a single line, which is +far more readable on terminals wider than 80 columns. +.Pp +.It -H +.It --help +Display the command line options understood by +.Xr readelf . +.Pp +.El +.Sh Common Options +The following command-line options are supported by all of the programs described +in this manual. +.Pp +.Bl -tag -width Ds +.It @ Va file +Read command-line options from +.Va file . +The options read are inserted in place of the original @ +.Va file +option. If +.Va file +does not exist, or cannot be read, then the option will be treated literally, +and not removed. +.Pp +Options in +.Va file +are separated by whitespace. A whitespace character may be included in an +option by surrounding the entire option in either single or double quotes. +Any character (including a backslash) may be included by prefixing the character +to be included with a backslash. The +.Va file +may itself contain additional @ +.Va file +options; any such options will be processed recursively. +.Pp +.It --help +Display the command-line options supported by the program. +.Pp +.It --version +Display the version number of the program. +.Pp +.El +.Sh Selecting the Target System +You can specify two aspects of the target system to the GNU binary file utilities, +each in several ways: +.Pp +.Bl -bullet +.It +the target +.Pp +.It +the architecture +.El +.Pp +In the following summaries, the lists of ways to specify values are in order +of decreasing precedence. The ways listed first override those listed later. +.Pp +The commands to list valid values only list the values for which the programs +you are running were configured. If they were configured with +.Op --enable-targets=all , +the commands list most of the available values, but a few are left out; not +all targets can be configured in at once because some of them can only be +configured +.Em native +(on hosts with the same type as the target system). +.Pp +.Ss Target Selection +A +.Em target +is an object file format. A given target may be supported for multiple architectures +(see Section +.Dq Architecture Selection ) . +A target selection may also have variations for different operating systems +or architectures. +.Pp +The command to list valid target values is +.Li objdump -i +(the first column of output contains the relevant information). +.Pp +Some sample values are: +.Li a.out-hp300bsd , +.Li ecoff-littlemips , +.Li a.out-sunos-big . +.Pp +You can also specify a target using a configuration triplet. This is the same +sort of name that is passed to +.Pa configure +to specify a target. When you use a configuration triplet as an argument, +it must be fully canonicalized. You can see the canonical version of a triplet +by running the shell script +.Pa config.sub +which is included with the sources. +.Pp +Some sample configuration triplets are: +.Li m68k-hp-bsd , +.Li mips-dec-ultrix , +.Li sparc-sun-sunos . +.Pp +.Em Xr objdump Target +.Pp +Ways to specify: +.Pp +.Bl -enum +.It +command line option: +.Op -b +or +.Op --target +.Pp +.It +environment variable +.Li GNUTARGET +.Pp +.It +deduced from the input file +.El +.Pp +.Em Xr objcopy and Xr strip Input Target +.Pp +Ways to specify: +.Pp +.Bl -enum +.It +command line options: +.Op -I +or +.Op --input-target , +or +.Op -F +or +.Op --target +.Pp +.It +environment variable +.Li GNUTARGET +.Pp +.It +deduced from the input file +.El +.Pp +.Em Xr objcopy and Xr strip Output Target +.Pp +Ways to specify: +.Pp +.Bl -enum +.It +command line options: +.Op -O +or +.Op --output-target , +or +.Op -F +or +.Op --target +.Pp +.It +the input target (see \(lq +.Xr objcopy +and +.Xr strip +Input Target\(rq above) +.Pp +.It +environment variable +.Li GNUTARGET +.Pp +.It +deduced from the input file +.El +.Pp +.Em Xr nm, Xr size, and Xr strings Target +.Pp +Ways to specify: +.Pp +.Bl -enum +.It +command line option: +.Op --target +.Pp +.It +environment variable +.Li GNUTARGET +.Pp +.It +deduced from the input file +.El +.Pp +.Ss Architecture Selection +An +.Em architecture +is a type of cpu on which an object file is to run. Its name may contain a +colon, separating the name of the processor family from the name of the particular +cpu. +.Pp +The command to list valid architecture values is +.Li objdump -i +(the second column contains the relevant information). +.Pp +Sample values: +.Li m68k:68020 , +.Li mips:3000 , +.Li sparc . +.Pp +.Em Xr objdump Architecture +.Pp +Ways to specify: +.Pp +.Bl -enum +.It +command line option: +.Op -m +or +.Op --architecture +.Pp +.It +deduced from the input file +.El +.Pp +.Em Xr objcopy, Xr nm, Xr size, Xr strings Architecture +.Pp +Ways to specify: +.Pp +.Bl -enum +.It +deduced from the input file +.El +.Pp +.Sh Reporting Bugs +Your bug reports play an essential role in making the binary utilities reliable. +.Pp +Reporting a bug may help you by bringing a solution to your problem, or it +may not. But in any case the principal function of a bug report is to help +the entire community by making the next version of the binary utilities work +better. Bug reports are your contribution to their maintenance. +.Pp +In order for a bug report to serve its purpose, you must include the information +that enables us to fix the bug. +.Pp +.Ss Have You Found a Bug? +If you are not sure whether you have found a bug, here are some guidelines: +.Pp +.Bl -bullet +.It +If a binary utility gets a fatal signal, for any input whatever, that is a +bug. Reliable utilities never crash. +.Pp +.It +If a binary utility produces an error message for valid input, that is a bug. +.Pp +.It +If you are an experienced user of binary utilities, your suggestions for improvement +are welcome in any case. +.El +.Pp +.Ss How to Report Bugs +A number of companies and individuals offer support for GNU products. If you +obtained the binary utilities from a support organization, we recommend you +contact that organization first. +.Pp +You can find contact information for many support companies and individuals +in the file +.Pa etc/SERVICE +in the GNU Emacs distribution. +.Pp +The fundamental principle of reporting bugs usefully is this: +.Sy report all the facts . +If you are not sure whether to state a fact or leave it out, state it! +.Pp +Often people omit facts because they think they know what causes the problem +and assume that some details do not matter. Thus, you might assume that the +name of a file you use in an example does not matter. Well, probably it does +not, but one cannot be sure. Perhaps the bug is a stray memory reference which +happens to fetch from the location where that pathname is stored in memory; +perhaps, if the pathname were different, the contents of that location would +fool the utility into doing the right thing despite the bug. Play it safe +and give a specific, complete example. That is the easiest thing for you to +do, and the most helpful. +.Pp +Keep in mind that the purpose of a bug report is to enable us to fix the bug +if it is new to us. Therefore, always write your bug reports on the assumption +that the bug has not been reported previously. +.Pp +Sometimes people give a few sketchy facts and ask, \(lqDoes this ring a bell?\(rq +This cannot help us fix a bug, so it is basically useless. We respond by asking +for enough details to enable us to investigate. You might as well expedite +matters by sending them to begin with. +.Pp +To enable us to fix the bug, you should include all these things: +.Pp +.Bl -bullet +.It +The version of the utility. Each utility announces it if you start it with +the +.Op --version +argument. +.Pp +Without this, we will not know whether there is any point in looking for the +bug in the current version of the binary utilities. +.Pp +.It +Any patches you may have applied to the source, including any patches made +to the +.Li BFD +library. +.Pp +.It +The type of machine you are using, and the operating system name and version +number. +.Pp +.It +What compiler (and its version) was used to compile the utilities---e.g. \(lq +.Li gcc-2.7 +\(rq\&. +.Pp +.It +The command arguments you gave the utility to observe the bug. To guarantee +you will not omit something important, list them all. A copy of the Makefile +(or the output from make) is sufficient. +.Pp +If we were to try to guess the arguments, we would probably guess wrong and +then we might not encounter the bug. +.Pp +.It +A complete input file, or set of input files, that will reproduce the bug. +If the utility is reading an object file or files, then it is generally most +helpful to send the actual object files. +.Pp +If the source files were produced exclusively using GNU programs (e.g., +.Xr gcc , +.Xr gas , +and/or the GNU +.Xr ld ) , +then it may be OK to send the source files rather than the object files. In +this case, be sure to say exactly what version of +.Xr gcc , +or whatever, was used to produce the object files. Also say how +.Xr gcc , +or whatever, was configured. +.Pp +.It +A description of what behavior you observe that you believe is incorrect. +For example, \(lqIt gets a fatal signal.\(rq +.Pp +Of course, if the bug is that the utility gets a fatal signal, then we will +certainly notice it. But if the bug is incorrect output, we might not notice +unless it is glaringly wrong. You might as well not give us a chance to make +a mistake. +.Pp +Even if the problem you experience is a fatal signal, you should still say +so explicitly. Suppose something strange is going on, such as your copy of +the utility is out of sync, or you have encountered a bug in the C library +on your system. (This has happened!) Your copy might crash and ours would +not. If you told us to expect a crash, then when ours fails to crash, we would +know that the bug was not happening for us. If you had not told us to expect +a crash, then we would not be able to draw any conclusion from our observations. +.Pp +.It +If you wish to suggest changes to the source, send us context diffs, as generated +by +.Xr diff +with the +.Op -u , +.Op -c , +or +.Op -p +option. Always send diffs from the old file to the new file. If you wish to +discuss something in the +.Xr ld +source, refer to it by context, not by line number. +.Pp +The line numbers in our development sources will not match those in your sources. +Your line numbers would convey no useful information to us. +.El +.Pp +Here are some things that are not necessary: +.Pp +.Bl -bullet +.It +A description of the envelope of the bug. +.Pp +Often people who encounter a bug spend a lot of time investigating which changes +to the input file will make the bug go away and which changes will not affect +it. +.Pp +This is often time consuming and not very useful, because the way we will +find the bug is by running a single example under the debugger with breakpoints, +not by pure deduction from a series of examples. We recommend that you save +your time for something else. +.Pp +Of course, if you can find a simpler example to report +.Em instead +of the original one, that is a convenience for us. Errors in the output will +be easier to spot, running under the debugger will take less time, and so +on. +.Pp +However, simplification is not vital; if you do not want to do this, report +the bug anyway and send us the entire test case you used. +.Pp +.It +A patch for the bug. +.Pp +A patch for the bug does help us if it is a good one. But do not omit the +necessary information, such as the test case, on the assumption that a patch +is all we need. We might see problems with your patch and decide to fix the +problem another way, or we might not understand it at all. +.Pp +Sometimes with programs as complicated as the binary utilities it is very +hard to construct an example that will make the program follow a certain path +through the code. If you do not send us the example, we will not be able to +construct one, so we will not be able to verify that the bug is fixed. +.Pp +And if we cannot understand what bug you are trying to fix, or why your patch +should be an improvement, we will not install it. A test case will help us +to understand. +.Pp +.It +A guess about what the bug is or what it depends on. +.Pp +Such guesses are usually wrong. Even we cannot guess right about such things +without first using the debugger to find the facts. +.El +.Pp +.Sh GNU Free Documentation License +.Bd -filled -offset indent +Copyright (C) 2000, 2003 Free Software Foundation, Inc. 51 Franklin Street, +Fifth Floor, Boston, MA 02110-1301 USA +.Pp +Everyone is permitted to copy and distribute verbatim copies of this license +document, but changing it is not allowed. +.Ed +.Pp +.Bl -enum +.It +PREAMBLE +.Pp +The purpose of this License is to make a manual, textbook, or other written +document \(lqfree\(rq in the sense of freedom: to assure everyone the effective freedom +to copy and redistribute it, with or without modifying it, either commercially +or noncommercially. Secondarily, this License preserves for the author and +publisher a way to get credit for their work, while not being considered responsible +for modifications made by others. +.Pp +This License is a kind of \(lqcopyleft\(rq, which means that derivative works of the +document must themselves be free in the same sense. It complements the GNU +General Public License, which is a copyleft license designed for free software. +.Pp +We have designed this License in order to use it for manuals for free software, +because free software needs free documentation: a free program should come +with manuals providing the same freedoms that the software does. But this +License is not limited to software manuals; it can be used for any textual +work, regardless of subject matter or whether it is published as a printed +book. We recommend this License principally for works whose purpose is instruction +or reference. +.Pp +.It +APPLICABILITY AND DEFINITIONS +.Pp +This License applies to any manual or other work that contains a notice placed +by the copyright holder saying it can be distributed under the terms of this +License. The \(lqDocument\(rq, below, refers to any such manual or work. Any member +of the public is a licensee, and is addressed as \(lqyou.\(rq +.Pp +A \(lqModified Version\(rq of the Document means any work containing the Document +or a portion of it, either copied verbatim, or with modifications and/or translated +into another language. +.Pp +A \(lqSecondary Section\(rq is a named appendix or a front-matter section of the Document +that deals exclusively with the relationship of the publishers or authors +of the Document to the Document's overall subject (or to related matters) +and contains nothing that could fall directly within that overall subject. +(For example, if the Document is in part a textbook of mathematics, a Secondary +Section may not explain any mathematics.) The relationship could be a matter +of historical connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding them. +.Pp +The \(lqInvariant Sections\(rq are certain Secondary Sections whose titles are designated, +as being those of Invariant Sections, in the notice that says that the Document +is released under this License. +.Pp +The \(lqCover Texts\(rq are certain short passages of text that are listed, as Front-Cover +Texts or Back-Cover Texts, in the notice that says that the Document is released +under this License. +.Pp +A \(lqTransparent\(rq copy of the Document means a machine-readable copy, represented +in a format whose specification is available to the general public, whose +contents can be viewed and edited directly and straightforwardly with generic +text editors or (for images composed of pixels) generic paint programs or +(for drawings) some widely available drawing editor, and that is suitable +for input to text formatters or for automatic translation to a variety of +formats suitable for input to text formatters. A copy made in an otherwise +Transparent file format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is not +\(lqTransparent\(rq is called \(lqOpaque.\(rq +.Pp +Examples of suitable formats for Transparent copies include plain ASCII without +markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly +available DTD, and standard-conforming simple HTML designed for human modification. +Opaque formats include PostScript, PDF, proprietary formats that can be read +and edited only by proprietary word processors, SGML or XML for which the +DTD and/or processing tools are not generally available, and the machine-generated +HTML produced by some word processors for output purposes only. +.Pp +The \(lqTitle Page\(rq means, for a printed book, the title page itself, plus such +following pages as are needed to hold, legibly, the material this License +requires to appear in the title page. For works in formats which do not have +any title page as such, \(lqTitle Page\(rq means the text near the most prominent +appearance of the work's title, preceding the beginning of the body of the +text. +.Pp +.It +VERBATIM COPYING +.Pp +You may copy and distribute the Document in any medium, either commercially +or noncommercially, provided that this License, the copyright notices, and +the license notice saying this License applies to the Document are reproduced +in all copies, and that you add no other conditions whatsoever to those of +this License. You may not use technical measures to obstruct or control the +reading or further copying of the copies you make or distribute. However, +you may accept compensation in exchange for copies. If you distribute a large +enough number of copies you must also follow the conditions in section 3. +.Pp +You may also lend copies, under the same conditions stated above, and you +may publicly display copies. +.Pp +.It +COPYING IN QUANTITY +.Pp +If you publish printed copies of the Document numbering more than 100, and +the Document's license notice requires Cover Texts, you must enclose the copies +in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover +Texts on the front cover, and Back-Cover Texts on the back cover. Both covers +must also clearly and legibly identify you as the publisher of these copies. +The front cover must present the full title with all words of the title equally +prominent and visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve the title +of the Document and satisfy these conditions, can be treated as verbatim copying +in other respects. +.Pp +If the required texts for either cover are too voluminous to fit legibly, +you should put the first ones listed (as many as fit reasonably) on the actual +cover, and continue the rest onto adjacent pages. +.Pp +If you publish or distribute Opaque copies of the Document numbering more +than 100, you must either include a machine-readable Transparent copy along +with each Opaque copy, or state in or with each Opaque copy a publicly-accessible +computer-network location containing a complete Transparent copy of the Document, +free of added material, which the general network-using public has access +to download anonymously at no charge using public-standard network protocols. +If you use the latter option, you must take reasonably prudent steps, when +you begin distribution of Opaque copies in quantity, to ensure that this Transparent +copy will remain thus accessible at the stated location until at least one +year after the last time you distribute an Opaque copy (directly or through +your agents or retailers) of that edition to the public. +.Pp +It is requested, but not required, that you contact the authors of the Document +well before redistributing any large number of copies, to give them a chance +to provide you with an updated version of the Document. +.Pp +.It +MODIFICATIONS +.Pp +You may copy and distribute a Modified Version of the Document under the conditions +of sections 2 and 3 above, provided that you release the Modified Version +under precisely this License, with the Modified Version filling the role of +the Document, thus licensing distribution and modification of the Modified +Version to whoever possesses a copy of it. In addition, you must do these +things in the Modified Version: +.Pp +A. Use in the Title Page (and on the covers, if any) a title distinct from +that of the Document, and from those of previous versions (which should, if +there were any, be listed in the History section of the Document). You may +use the same title as a previous version if the original publisher of that +version gives permission. B. List on the Title Page, as authors, one or more +persons or entities responsible for authorship of the modifications in the +Modified Version, together with at least five of the principal authors of +the Document (all of its principal authors, if it has less than five). C. +State on the Title page the name of the publisher of the Modified Version, +as the publisher. D. Preserve all the copyright notices of the Document. +E. Add an appropriate copyright notice for your modifications adjacent to +the other copyright notices. F. Include, immediately after the copyright +notices, a license notice giving the public permission to use the Modified +Version under the terms of this License, in the form shown in the Addendum +below. G. Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. H. Include +an unaltered copy of this License. I. Preserve the section entitled \(lqHistory\(rq, +and its title, and add to it an item stating at least the title, year, new +authors, and publisher of the Modified Version as given on the Title Page. +If there is no section entitled \(lqHistory\(rq in the Document, create one stating +the title, year, authors, and publisher of the Document as given on its Title +Page, then add an item describing the Modified Version as stated in the previous +sentence. J. Preserve the network location, if any, given in the Document +for public access to a Transparent copy of the Document, and likewise the +network locations given in the Document for previous versions it was based +on. These may be placed in the \(lqHistory\(rq section. You may omit a network location +for a work that was published at least four years before the Document itself, +or if the original publisher of the version it refers to gives permission. +K. In any section entitled \(lqAcknowledgements\(rq or \(lqDedications\(rq, preserve the section's +title, and preserve in the section all the substance and tone of each of the +contributor acknowledgements and/or dedications given therein. L. Preserve +all the Invariant Sections of the Document, unaltered in their text and in +their titles. Section numbers or the equivalent are not considered part of +the section titles. M. Delete any section entitled \(lqEndorsements.\(rq Such a section +may not be included in the Modified Version. N. Do not retitle any existing +section as \(lqEndorsements\(rq or to conflict in title with any Invariant Section. +.Pp +If the Modified Version includes new front-matter sections or appendices that +qualify as Secondary Sections and contain no material copied from the Document, +you may at your option designate some or all of these sections as invariant. +To do this, add their titles to the list of Invariant Sections in the Modified +Version's license notice. These titles must be distinct from any other section +titles. +.Pp +You may add a section entitled \(lqEndorsements\(rq, provided it contains nothing +but endorsements of your Modified Version by various parties--for example, +statements of peer review or that the text has been approved by an organization +as the authoritative definition of a standard. +.Pp +You may add a passage of up to five words as a Front-Cover Text, and a passage +of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts +in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover +Text may be added by (or through arrangements made by) any one entity. If +the Document already includes a cover text for the same cover, previously +added by you or by arrangement made by the same entity you are acting on behalf +of, you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. +.Pp +The author(s) and publisher(s) of the Document do not by this License give +permission to use their names for publicity for or to assert or imply endorsement +of any Modified Version. +.Pp +.It +COMBINING DOCUMENTS +.Pp +You may combine the Document with other documents released under this License, +under the terms defined in section 4 above for modified versions, provided +that you include in the combination all of the Invariant Sections of all of +the original documents, unmodified, and list them all as Invariant Sections +of your combined work in its license notice. +.Pp +The combined work need only contain one copy of this License, and multiple +identical Invariant Sections may be replaced with a single copy. If there +are multiple Invariant Sections with the same name but different contents, +make the title of each such section unique by adding at the end of it, in +parentheses, the name of the original author or publisher of that section +if known, or else a unique number. Make the same adjustment to the section +titles in the list of Invariant Sections in the license notice of the combined +work. +.Pp +In the combination, you must combine any sections entitled \(lqHistory\(rq in the +various original documents, forming one section entitled \(lqHistory\(rq; likewise +combine any sections entitled \(lqAcknowledgements\(rq, and any sections entitled +\(lqDedications.\(rq You must delete all sections entitled \(lqEndorsements.\(rq +.Pp +.It +COLLECTIONS OF DOCUMENTS +.Pp +You may make a collection consisting of the Document and other documents released +under this License, and replace the individual copies of this License in the +various documents with a single copy that is included in the collection, provided +that you follow the rules of this License for verbatim copying of each of +the documents in all other respects. +.Pp +You may extract a single document from such a collection, and distribute it +individually under this License, provided you insert a copy of this License +into the extracted document, and follow this License in all other respects +regarding verbatim copying of that document. +.Pp +.It +AGGREGATION WITH INDEPENDENT WORKS +.Pp +A compilation of the Document or its derivatives with other separate and independent +documents or works, in or on a volume of a storage or distribution medium, +does not as a whole count as a Modified Version of the Document, provided +no compilation copyright is claimed for the compilation. Such a compilation +is called an \(lqaggregate\(rq, and this License does not apply to the other self-contained +works thus compiled with the Document, on account of their being thus compiled, +if they are not themselves derivative works of the Document. +.Pp +If the Cover Text requirement of section 3 is applicable to these copies of +the Document, then if the Document is less than one quarter of the entire +aggregate, the Document's Cover Texts may be placed on covers that surround +only the Document within the aggregate. Otherwise they must appear on covers +around the whole aggregate. +.Pp +.It +TRANSLATION +.Pp +Translation is considered a kind of modification, so you may distribute translations +of the Document under the terms of section 4. Replacing Invariant Sections +with translations requires special permission from their copyright holders, +but you may include translations of some or all Invariant Sections in addition +to the original versions of these Invariant Sections. You may include a translation +of this License provided that you also include the original English version +of this License. In case of a disagreement between the translation and the +original English version of this License, the original English version will +prevail. +.Pp +.It +TERMINATION +.Pp +You may not copy, modify, sublicense, or distribute the Document except as +expressly provided for under this License. Any other attempt to copy, modify, +sublicense or distribute the Document is void, and will automatically terminate +your rights under this License. However, parties who have received copies, +or rights, from you under this License will not have their licenses terminated +so long as such parties remain in full compliance. +.Pp +.It +FUTURE REVISIONS OF THIS LICENSE +.Pp +The Free Software Foundation may publish new, revised versions of the GNU +Free Documentation License from time to time. Such new versions will be similar +in spirit to the present version, but may differ in detail to address new +problems or concerns. See http://www.gnu.org/copyleft/. +.Pp +Each version of the License is given a distinguishing version number. If the +Document specifies that a particular numbered version of this License \(lqor any +later version\(rq applies to it, you have the option of following the terms and +conditions either of that specified version or of any later version that has +been published (not as a draft) by the Free Software Foundation. If the Document +does not specify a version number of this License, you may choose any version +ever published (not as a draft) by the Free Software Foundation. +.Pp +.El +.Ss ADDENDUM: How to use this License for your documents +To use this License in a document you have written, include a copy of the +License in the document and put the following copyright and license notices +just after the title page: +.Pp +.Bd -literal -offset indent + +Copyright (C) year your name. +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 +or any later version published by the Free Software Foundation; +with the Invariant Sections being list their titles, with the +Front-Cover Texts being list, and with the Back-Cover Texts being list. +A copy of the license is included in the section entitled "GNU +Free Documentation License." + +.Ed +.Pp +If you have no Invariant Sections, write \(lqwith no Invariant Sections\(rq instead +of saying which ones are invariant. If you have no Front-Cover Texts, write +\(lqno Front-Cover Texts\(rq instead of \(lqFront-Cover Texts being +.Va list +\(rq; likewise for Back-Cover Texts. +.Pp +If your document contains nontrivial examples of program code, we recommend +releasing these examples in parallel under your choice of free software license, +such as the GNU General Public License, to permit their use in free software. +.Pp +.Sh Binutils Index diff --git a/contrib/binutils/gas/doc/as.7 b/contrib/binutils/gas/doc/as.7 new file mode 100644 index 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 <name> STT_FUNCTION + .type <name> STT_OBJECT + + .type <name>,#function + .type <name>,#object + + .type <name>,@function + .type <name>,@object + + .type <name>,%function + .type <name>,%object + + .type <name>,"function" + .type <name>,"object" +.Ed +.Pp +.Ss Li .uleb128 Va expressions +.Va uleb128 +stands for \(lqunsigned little endian base 128.\(rq This is a compact, variable length +representation of numbers used by the DWARF symbolic debugging format.See Section +.Dq Sleb128 . +.Pp +.Ss Li .version " Va string" +This directive creates a +.Li .note +section and places into it an ELF formatted note of type NT_VERSION. The note's +name is set to +.Li string . +.Pp +.Ss Li .vtable_entry Va table, Va offset +This directive finds or creates a symbol +.Li table +and creates a +.Li VTABLE_ENTRY +relocation for it with an addend of +.Li offset . +.Pp +.Ss Li .vtable_inherit Va child, Va parent +This directive finds the symbol +.Li child +and finds or creates the symbol +.Li parent +and then creates a +.Li VTABLE_INHERIT +relocation for the parent whose addend is the value of the child symbol. As +a special case the parent name of +.Li 0 +is treated as referring to the +.Li *ABS* +section. +.Pp +.Ss Li .warning " Va string" +Similar to the directive +.Li .error +(see Section +.Dq Error ) , +but just emits a warning. +.Pp +.Ss Li .weak Va names +This directive sets the weak attribute on the comma separated list of symbol +.Li names . +If the symbols do not already exist, they will be created. +.Pp +On COFF targets other than PE, weak symbols are a GNU extension. This directive +sets the weak attribute on the comma separated list of symbol +.Li names . +If the symbols do not already exist, they will be created. +.Pp +On the PE target, weak symbols are supported natively as weak aliases. When +a weak symbol is created that is not an alias, GAS creates an alternate symbol +to hold the default value. +.Pp +.Ss Li .weakref Va alias, Va target +This directive creates an alias to the target symbol that enables the symbol +to be referenced with weak-symbol semantics, but without actually making it +weak. If direct references or definitions of the symbol are present, then +the symbol will not be weak, but if all references to it are through weak +references, the symbol will be marked as weak in the symbol table. +.Pp +The effect is equivalent to moving all references to the alias to a separate +assembly source file, renaming the alias to the symbol in it, declaring the +symbol as weak there, and running a reloadable link to merge the object files +resulting from the assembly of the new source file and the old source file +that had the references to the alias removed. +.Pp +The alias itself never makes to the symbol table, and is entirely handled +within the assembler. +.Pp +.Ss Li .word Va expressions +This directive expects zero or more +.Va expressions , +of any section, separated by commas. For each expression, +.Xr as +emits a 32-bit number. +.Pp +.Ss Deprecated Directives +One day these directives won't work. They are included for compatibility with +older assemblers. +.Bl -tag -width Ds +.It .abort +.It .line +.El +.Pp +.Sh ARM Dependent Features +.Ss Options +.Bl -tag -width Ds +.It -mcpu= Va processor[+ Va extension...] +This option specifies the target processor. The assembler will issue an error +message if an attempt is made to assemble an instruction which will not execute +on the target processor. The following processor names are recognized: +.Li arm1 , +.Li arm2 , +.Li arm250 , +.Li arm3 , +.Li arm6 , +.Li arm60 , +.Li arm600 , +.Li arm610 , +.Li arm620 , +.Li arm7 , +.Li arm7m , +.Li arm7d , +.Li arm7dm , +.Li arm7di , +.Li arm7dmi , +.Li arm70 , +.Li arm700 , +.Li arm700i , +.Li arm710 , +.Li arm710t , +.Li arm720 , +.Li arm720t , +.Li arm740t , +.Li arm710c , +.Li arm7100 , +.Li arm7500 , +.Li arm7500fe , +.Li arm7t , +.Li arm7tdmi , +.Li arm7tdmi-s , +.Li arm8 , +.Li arm810 , +.Li strongarm , +.Li strongarm1 , +.Li strongarm110 , +.Li strongarm1100 , +.Li strongarm1110 , +.Li arm9 , +.Li arm920 , +.Li arm920t , +.Li arm922t , +.Li arm940t , +.Li arm9tdmi , +.Li arm9e , +.Li arm926e , +.Li arm926ej-s , +.Li arm946e-r0 , +.Li arm946e , +.Li arm946e-s , +.Li arm966e-r0 , +.Li arm966e , +.Li arm966e-s , +.Li arm968e-s , +.Li arm10t , +.Li arm10tdmi , +.Li arm10e , +.Li arm1020 , +.Li arm1020t , +.Li arm1020e , +.Li arm1022e , +.Li arm1026ej-s , +.Li arm1136j-s , +.Li arm1136jf-s , +.Li arm1156t2-s , +.Li arm1156t2f-s , +.Li arm1176jz-s , +.Li arm1176jzf-s , +.Li mpcore , +.Li mpcorenovfp , +.Li cortex-a8 , +.Li cortex-r4 , +.Li cortex-m3 , +.Li ep9312 +(ARM920 with Cirrus Maverick coprocessor), +.Li i80200 +(Intel XScale processor) +.Li iwmmxt +(Intel(r) XScale processor with Wireless MMX(tm) technology coprocessor) and +.Li xscale . +The special name +.Li all +may be used to allow the assembler to accept instructions valid for any ARM +processor. +.Pp +In addition to the basic instruction set, the assembler can be told to accept +various extension mnemonics that extend the processor using the co-processor +instruction space. For example, +.Li -mcpu=arm920+maverick +is equivalent to specifying +.Li -mcpu=ep9312 . +The following extensions are currently supported: +.Li +maverick +.Li +iwmmxt +and +.Li +xscale . +.Pp +.It -march= Va architecture[+ Va extension...] +This option specifies the target architecture. The assembler will issue an +error message if an attempt is made to assemble an instruction which will +not execute on the target architecture. The following architecture names are +recognized: +.Li armv1 , +.Li armv2 , +.Li armv2a , +.Li armv2s , +.Li armv3 , +.Li armv3m , +.Li armv4 , +.Li armv4xm , +.Li armv4t , +.Li armv4txm , +.Li armv5 , +.Li armv5t , +.Li armv5txm , +.Li armv5te , +.Li armv5texp , +.Li armv6 , +.Li armv6j , +.Li armv6k , +.Li armv6z , +.Li armv6zk , +.Li armv7 , +.Li armv7-a , +.Li armv7-r , +.Li armv7-m , +.Li iwmmxt +and +.Li xscale . +If both +.Li -mcpu +and +.Li -march +are specified, the assembler will use the setting for +.Li -mcpu . +.Pp +The architecture option can be extended with the same instruction set extension +options as the +.Li -mcpu +option. +.Pp +.It -mfpu= Va floating-point-format +.Pp +This option specifies the floating point format to assemble for. The assembler +will issue an error message if an attempt is made to assemble an instruction +which will not execute on the target floating point unit. The following format +options are recognized: +.Li softfpa , +.Li fpe , +.Li fpe2 , +.Li fpe3 , +.Li fpa , +.Li fpa10 , +.Li fpa11 , +.Li arm7500fe , +.Li softvfp , +.Li softvfp+vfp , +.Li vfp , +.Li vfp10 , +.Li vfp10-r0 , +.Li vfp9 , +.Li vfpxd , +.Li arm1020t , +.Li arm1020e , +.Li arm1136jf-s +and +.Li maverick . +.Pp +In addition to determining which instructions are assembled, this option also +affects the way in which the +.Li .double +assembler directive behaves when assembling little-endian code. +.Pp +The default is dependent on the processor selected. For Architecture 5 or +later, the default is to assembler for VFP instructions; for earlier architectures +the default is to assemble for FPA instructions. +.Pp +.It -mthumb +This option specifies that the assembler should start assembling Thumb instructions; +that is, it should behave as though the file starts with a +.Li .code 16 +directive. +.Pp +.It -mthumb-interwork +This option specifies that the output generated by the assembler should be +marked as supporting interworking. +.Pp +.It -mapcs Li [26|32] +This option specifies that the output generated by the assembler should be +marked as supporting the indicated version of the Arm Procedure. Calling Standard. +.Pp +.It -matpcs +This option specifies that the output generated by the assembler should be +marked as supporting the Arm/Thumb Procedure Calling Standard. If enabled +this option will cause the assembler to create an empty debugging section +in the object file called .arm.atpcs. Debuggers can use this to determine +the ABI being used by. +.Pp +.It -mapcs-float +This indicates the floating point variant of the APCS should be used. In this +variant floating point arguments are passed in FP registers rather than integer +registers. +.Pp +.It -mapcs-reentrant +This indicates that the reentrant variant of the APCS should be used. This +variant supports position independent code. +.Pp +.It -mfloat-abi= Va abi +This option specifies that the output generated by the assembler should be +marked as using specified floating point ABI. The following values are recognized: +.Li soft , +.Li softfp +and +.Li hard . +.Pp +.It -meabi= Va ver +This option specifies which EABI version the produced object files should +conform to. The following values are recognized: +.Li GNU , +.Li 4 +and +.Li 5 . +.Pp +.It -EB +This option specifies that the output generated by the assembler should be +marked as being encoded for a big-endian processor. +.Pp +.It -EL +This option specifies that the output generated by the assembler should be +marked as being encoded for a little-endian processor. +.Pp +.It -k +This option specifies that the output of the assembler should be marked as +position-independent code (PIC). +.Pp +.El +.Ss Syntax +.Em Special Characters +.Pp +The presence of a +.Li @ +on a line indicates the start of a comment that extends to the end of the +current line. If a +.Li # +appears as the first character of a line, the whole line is treated as a comment. +.Pp +The +.Li ; +character can be used instead of a newline to separate statements. +.Pp +Either +.Li # +or +.Li $ +can be used to indicate immediate operands. +.Pp +*TODO* Explain about /data modifier on symbols. +.Pp +.Em Register Names +.Pp +*TODO* Explain about ARM register naming, and the predefined names. +.Pp +.Em ARM relocation generation +.Pp +Specific data relocations can be generated by putting the relocation name +in parentheses after the symbol name. For example: +.Pp +.Bd -literal -offset indent + .word foo(TARGET1) +.Ed +.Pp +This will generate an +.Li R_ARM_TARGET1 +relocation against the symbol +.Va foo . +The following relocations are supported: +.Li GOT , +.Li GOTOFF , +.Li TARGET1 , +.Li TARGET2 , +.Li SBREL , +.Li TLSGD , +.Li TLSLDM , +.Li TLSLDO , +.Li GOTTPOFF +and +.Li TPOFF . +.Pp +For compatibility with older toolchains the assembler also accepts +.Li (PLT) +after branch targets. This will generate the deprecated +.Li R_ARM_PLT32 +relocation. +.Pp +Relocations for +.Li MOVW +and +.Li MOVT +instructions can be generated by prefixing the value with +.Li #:lower16: +and +.Li #:upper16 +respectively. For example to load the 32-bit address of foo into r0: +.Pp +.Bd -literal -offset indent + MOVW r0, #:lower16:foo + MOVT r0, #:upper16:foo +.Ed +.Pp +.Ss Floating Point +The ARM family uses ieee floating-point numbers. +.Pp +.Ss ARM Machine Directives +.Bl -tag -width Ds +.It .align Va expression [, Va expression] +This is the generic +.Va .align +directive. For the ARM however if the first argument is zero (ie no alignment +is needed) the assembler will behave as if the argument had been 2 (ie pad +to the next four byte boundary). This is for compatibility with ARM's own +assembler. +.Pp +.It Va name .req Va register name +This creates an alias for +.Va register name +called +.Va name . +For example: +.Pp +.Bd -literal -offset indent + foo .req r0 +.Ed +.Pp +.It .unreq Va alias-name +This undefines a register alias which was previously defined using the +.Li req , +.Li dn +or +.Li qn +directives. For example: +.Pp +.Bd -literal -offset indent + foo .req r0 + .unreq foo +.Ed +.Pp +An error occurs if the name is undefined. Note - this pseudo op can be used +to delete builtin in register name aliases (eg 'r0'). This should only be +done if it is really necessary. +.Pp +.It Va name .dn Va register name [ Va .type] [ Va [index]] +.It Va name .qn Va register name [ Va .type] [ Va [index]] +.Pp +The +.Li dn +and +.Li qn +directives are used to create typed and/or indexed register aliases for use +in Advanced SIMD Extension (Neon) instructions. The former should be used +to create aliases of double-precision registers, and the latter to create +aliases of quad-precision registers. +.Pp +If these directives are used to create typed aliases, those aliases can be +used in Neon instructions instead of writing types after the mnemonic or after +each operand. For example: +.Pp +.Bd -literal -offset indent + x .dn d2.f32 + y .dn d3.f32 + z .dn d4.f32[1] + vmul x,y,z +.Ed +.Pp +This is equivalent to writing the following: +.Pp +.Bd -literal -offset indent + vmul.f32 d2,d3,d4[1] +.Ed +.Pp +Aliases created using +.Li dn +or +.Li qn +can be destroyed using +.Li unreq . +.Pp +.It .code Li [16|32] +This directive selects the instruction set being generated. The value 16 selects +Thumb, with the value 32 selecting ARM. +.Pp +.It .thumb +This performs the same action as +.Va .code 16 . +.Pp +.It .arm +This performs the same action as +.Va .code 32 . +.Pp +.It .force_thumb +This directive forces the selection of Thumb instructions, even if the target +processor does not support those instructions +.Pp +.It .thumb_func +This directive specifies that the following symbol is the name of a Thumb +encoded function. This information is necessary in order to allow the assembler +and linker to generate correct code for interworking between Arm and Thumb +instructions and should be used even if interworking is not going to be performed. +The presence of this directive also implies +.Li .thumb +.Pp +This directive is not neccessary when generating EABI objects. On these targets +the encoding is implicit when generating Thumb code. +.Pp +.It .thumb_set +This performs the equivalent of a +.Li .set +directive in that it creates a symbol which is an alias for another symbol +(possibly not yet defined). This directive also has the added property in +that it marks the aliased symbol as being a thumb function entry point, in +the same way that the +.Li .thumb_func +directive does. +.Pp +.It .ltorg +This directive causes the current contents of the literal pool to be dumped +into the current section (which is assumed to be the .text section) at the +current location (aligned to a word boundary). +.Li GAS +maintains a separate literal pool for each section and each sub-section. The +.Li .ltorg +directive will only affect the literal pool of the current section and sub-section. +At the end of assembly all remaining, un-empty literal pools will automatically +be dumped. +.Pp +Note - older versions of +.Li GAS +would dump the current literal pool any time a section change occurred. This +is no longer done, since it prevents accurate control of the placement of +literal pools. +.Pp +.It .pool +This is a synonym for .ltorg. +.Pp +.It .unwind_fnstart +Marks the start of a function with an unwind table entry. +.Pp +.It .unwind_fnend +Marks the end of a function with an unwind table entry. The unwind index table +entry is created when this directive is processed. +.Pp +If no personality routine has been specified then standard personality routine +0 or 1 will be used, depending on the number of unwind opcodes required. +.Pp +.It .cantunwind +Prevents unwinding through the current function. No personality routine or +exception table data is required or permitted. +.Pp +.It .personality Va name +Sets the personality routine for the current function to +.Va name . +.Pp +.It .personalityindex Va index +Sets the personality routine for the current function to the EABI standard +routine number +.Va index +.Pp +.It .handlerdata +Marks the end of the current function, and the start of the exception table +entry for that function. Anything between this directive and the +.Li .fnend +directive will be added to the exception table entry. +.Pp +Must be preceded by a +.Li .personality +or +.Li .personalityindex +directive. +.Pp +.It .save Va reglist +Generate unwinder annotations to restore the registers in +.Va reglist . +The format of +.Va reglist +is the same as the corresponding store-multiple instruction. +.Pp +.Bd -literal -offset indent + .save {r4, r5, r6, lr} + stmfd sp!, {r4, r5, r6, lr} + .save f4, 2 + sfmfd f4, 2, [sp]! + .save {d8, d9, d10} + fstmdx sp!, {d8, d9, d10} + .save {wr10, wr11} + wstrd wr11, [sp, #-8]! + wstrd wr10, [sp, #-8]! +or + .save wr11 + wstrd wr11, [sp, #-8]! + .save wr10 + wstrd wr10, [sp, #-8]! +.Ed +.Pp +.It .vsave Va vfp-reglist +Generate unwinder annotations to restore the VFP registers in +.Va vfp-reglist +using FLDMD. Also works for VFPv3 registers that are to be restored using +VLDM. The format of +.Va vfp-reglist +is the same as the corresponding store-multiple instruction. +.Pp +.Bd -literal -offset indent + .vsave {d8, d9, d10} + fstmdd sp!, {d8, d9, d10} + .vsave {d15, d16, d17} + vstm sp!, {d15, d16, d17} +.Ed +.Pp +Since FLDMX and FSTMX are now deprecated, this directive should be used in +favour of +.Li .save +for saving VFP registers for ARMv6 and above. +.Pp +.It .pad # Va count +Generate unwinder annotations for a stack adjustment of +.Va count +bytes. A positive value indicates the function prologue allocated stack space +by decrementing the stack pointer. +.Pp +.It .movsp Va reg [, # Va offset] +Tell the unwinder that +.Va reg +contains an offset from the current stack pointer. If +.Va offset +is not specified then it is assumed to be zero. +.Pp +.It .setfp Va fpreg, Va spreg [, # Va offset] +Make all unwinder annotations relaive to a frame pointer. Without this the +unwinder will use offsets from the stack pointer. +.Pp +The syntax of this directive is the same as the +.Li sub +or +.Li mov +instruction used to set the frame pointer. +.Va spreg +must be either +.Li sp +or mentioned in a previous +.Li .movsp +directive. +.Pp +.Bd -literal -offset indent +\&.movsp ip +mov ip, sp +\&... +\&.setfp fp, ip, #4 +sub fp, ip, #4 +.Ed +.Pp +.It .raw Va offset, Va byte1, ... +Insert one of more arbitary unwind opcode bytes, which are known to adjust +the stack pointer by +.Va offset +bytes. +.Pp +For example +.Li .unwind_raw 4, 0xb1, 0x01 +is equivalent to +.Li .save {r0} +.Pp +.It .cpu Va name +Select the target processor. Valid values for +.Va name +are the same as for the +.Op -mcpu +commandline option. +.Pp +.It .arch Va name +Select the target architecture. Valid values for +.Va name +are the same as for the +.Op -march +commandline option. +.Pp +.It .object_arch Va name +Override the architecture recorded in the EABI object attribute section. Valid +values for +.Va name +are the same as for the +.Li .arch +directive. Typically this is useful when code uses runtime detection of CPU +features. +.Pp +.It .fpu Va name +Select the floating point unit to assemble for. Valid values for +.Va name +are the same as for the +.Op -mfpu +commandline option. +.Pp +.It .eabi_attribute Va tag, Va value +Set the EABI object attribute number +.Va tag +to +.Va value . +The value is either a +.Li number , +.Li "string" , +or +.Li number, "string" +depending on the tag. +.Pp +.El +.Ss Opcodes +.Li as +implements all the standard ARM opcodes. It also implements several pseudo +opcodes, including several synthetic load instructions. +.Pp +.Bl -tag -width Ds +.It NOP +.Bd -literal -offset indent + nop +.Ed +.Pp +This pseudo op will always evaluate to a legal ARM instruction that does nothing. +Currently it will evaluate to MOV r0, r0. +.Pp +.It LDR +.Bd -literal -offset indent + ldr <register> , = <expression> +.Ed +.Pp +If expression evaluates to a numeric constant then a MOV or MVN instruction +will be used in place of the LDR instruction, if the constant can be generated +by either of these instructions. Otherwise the constant will be placed into +the nearest literal pool (if it not already there) and a PC relative LDR instruction +will be generated. +.Pp +.It ADR +.Bd -literal -offset indent + adr <register> <label> +.Ed +.Pp +This instruction will load the address of +.Va label +into the indicated register. The instruction will evaluate to a PC relative +ADD or SUB instruction depending upon where the label is located. If the label +is out of range, or if it is not defined in the same file (and section) as +the ADR instruction, then an error will be generated. This instruction will +not make use of the literal pool. +.Pp +.It ADRL +.Bd -literal -offset indent + adrl <register> <label> +.Ed +.Pp +This instruction will load the address of +.Va label +into the indicated register. The instruction will evaluate to one or two PC +relative ADD or SUB instructions depending upon where the label is located. +If a second instruction is not needed a NOP instruction will be generated +in its place, so that this instruction is always 8 bytes long. +.Pp +If the label is out of range, or if it is not defined in the same file (and +section) as the ADRL instruction, then an error will be generated. This instruction +will not make use of the literal pool. +.Pp +.El +For information on the ARM or Thumb instruction sets, see +.Em ARM Software Development Toolkit Reference Manual , +Advanced RISC Machines Ltd. +.Pp +.Ss Mapping Symbols +The ARM ELF specification requires that special symbols be inserted into object +files to mark certain features: +.Pp +.Bl -tag -width Ds +.It $a +At the start of a region of code containing ARM instructions. +.Pp +.It $t +At the start of a region of code containing THUMB instructions. +.Pp +.It $d +At the start of a region of data. +.Pp +.El +The assembler will automatically insert these symbols for you - there is no +need to code them yourself. Support for tagging symbols ($b, $f, $p and $m) +which is also mentioned in the current ARM ELF specification is not implemented. +This is because they have been dropped from the new EABI and so tools cannot +rely upon their presence. +.Pp +.Sh 80386 Dependent Features +The i386 version +.Li as +supports both the original Intel 386 architecture in both 16 and 32-bit mode +as well as AMD x86-64 architecture extending the Intel architecture to 64-bits. +.Pp +.Ss Options +The i386 version of +.Li as +has a few machine dependent options: +.Pp +.Bl -tag -width Ds +.It --32 | --64 +Select the word size, either 32 bits or 64 bits. Selecting 32-bit implies +Intel i386 architecture, while 64-bit implies AMD x86-64 architecture. +.Pp +These options are only available with the ELF object file format, and require +that the necessary BFD support has been included (on a 32-bit platform you +have to add --enable-64-bit-bfd to configure enable 64-bit usage and use x86-64 +as target platform). +.Pp +.It -n +By default, x86 GAS replaces multiple nop instructions used for alignment +within code sections with multi-byte nop instructions such as leal 0(%esi,1),%esi. +This switch disables the optimization. +.Pp +.It --divide +On SVR4-derived platforms, the character +.Li / +is treated as a comment character, which means that it cannot be used in expressions. +The +.Li --divide +option turns +.Li / +into a normal character. This does not disable +.Li / +at the beginning of a line starting a comment, or affect using +.Li # +for starting a comment. +.Pp +.It -march= Va CPU +This option specifies an instruction set architecture for generating instructions. +The following architectures are recognized: +.Li i8086 , +.Li i186 , +.Li i286 , +.Li i386 , +.Li i486 , +.Li i586 , +.Li i686 , +.Li pentium , +.Li pentiumpro , +.Li pentiumii , +.Li pentiumiii , +.Li pentium4 , +.Li prescott , +.Li nocona , +.Li core , +.Li core2 , +.Li k6 , +.Li k6_2 , +.Li athlon , +.Li sledgehammer , +.Li opteron , +.Li k8 , +.Li generic32 +and +.Li generic64 . +.Pp +This option only affects instructions generated by the assembler. The +.Li .arch +directive will take precedent. +.Pp +.It -mtune= Va CPU +This option specifies a processor to optimize for. When used in conjunction +with the +.Op -march +option, only instructions of the processor specified by the +.Op -march +option will be generated. +.Pp +Valid +.Va CPU +values are identical to +.Op -march= Va CPU . +.Pp +.El +.Ss AT&T Syntax versus Intel Syntax +.Li as +now supports assembly using Intel assembler syntax. +.Li .intel_syntax +selects Intel mode, and +.Li .att_syntax +switches back to the usual AT&T mode for compatibility with the output of +.Li gcc . +Either of these directives may have an optional argument, +.Li prefix , +or +.Li noprefix +specifying whether registers require a +.Li % +prefix. AT&T System V/386 assembler syntax is quite different from Intel syntax. +We mention these differences because almost all 80386 documents use Intel +syntax. Notable differences between the two syntaxes are: +.Pp +.Bl -bullet +.It +AT&T immediate operands are preceded by +.Li $ ; +Intel immediate operands are undelimited (Intel +.Li push 4 +is AT&T +.Li pushl $4 ) . +AT&T register operands are preceded by +.Li % ; +Intel register operands are undelimited. AT&T absolute (as opposed to PC relative) +jump/call operands are prefixed by +.Li * ; +they are undelimited in Intel syntax. +.Pp +.It +AT&T and Intel syntax use the opposite order for source and destination operands. +Intel +.Li add eax, 4 +is +.Li addl $4, %eax . +The +.Li source, dest +convention is maintained for compatibility with previous Unix assemblers. +Note that instructions with more than one source operand, such as the +.Li enter +instruction, do +.Em not +have reversed order. i386-Bugs. +.Pp +.It +In AT&T syntax the size of memory operands is determined from the last character +of the instruction mnemonic. Mnemonic suffixes of +.Li b , +.Li w , +.Li l +and +.Li q +specify byte (8-bit), word (16-bit), long (32-bit) and quadruple word (64-bit) +memory references. Intel syntax accomplishes this by prefixing memory operands +( +.Em not +the instruction mnemonics) with +.Li byte ptr , +.Li word ptr , +.Li dword ptr +and +.Li qword ptr . +Thus, Intel +.Li mov al, byte ptr Va foo +is +.Li movb Va foo, %al +in AT&T syntax. +.Pp +.It +Immediate form long jumps and calls are +.Li lcall/ljmp $ Va section, $ Va offset +in AT&T syntax; the Intel syntax is +.Li call/jmp far Va section: Va offset . +Also, the far return instruction is +.Li lret $ Va stack-adjust +in AT&T syntax; Intel syntax is +.Li ret far Va stack-adjust . +.Pp +.It +The AT&T assembler does not provide support for multiple section programs. +Unix style systems expect all programs to be single sections. +.El +.Pp +.Ss Instruction Naming +Instruction mnemonics are suffixed with one character modifiers which specify +the size of operands. The letters +.Li b , +.Li w , +.Li l +and +.Li q +specify byte, word, long and quadruple word operands. If no suffix is specified +by an instruction then +.Li as +tries to fill in the missing suffix based on the destination register operand +(the last one by convention). Thus, +.Li mov %ax, %bx +is equivalent to +.Li movw %ax, %bx ; +also, +.Li mov $1, %bx +is equivalent to +.Li movw $1, bx . +Note that this is incompatible with the AT&T Unix assembler which assumes +that a missing mnemonic suffix implies long operand size. (This incompatibility +does not affect compiler output since compilers always explicitly specify +the mnemonic suffix.) +.Pp +Almost all instructions have the same names in AT&T and Intel format. There +are a few exceptions. The sign extend and zero extend instructions need two +sizes to specify them. They need a size to sign/zero extend +.Em from +and a size to zero extend +.Em to . +This is accomplished by using two instruction mnemonic suffixes in AT&T syntax. +Base names for sign extend and zero extend are +.Li movs... +and +.Li movz... +in AT&T syntax ( +.Li movsx +and +.Li movzx +in Intel syntax). The instruction mnemonic suffixes are tacked on to this +base name, the +.Em from +suffix before the +.Em to +suffix. Thus, +.Li movsbl %al, %edx +is AT&T syntax for \(lqmove sign extend +.Em from +%al +.Em to +%edx.\(rq Possible suffixes, thus, are +.Li bl +(from byte to long), +.Li bw +(from byte to word), +.Li wl +(from word to long), +.Li bq +(from byte to quadruple word), +.Li wq +(from word to quadruple word), and +.Li lq +(from long to quadruple word). +.Pp +The Intel-syntax conversion instructions +.Pp +.Bl -bullet +.It +.Li cbw +--- sign-extend byte in +.Li %al +to word in +.Li %ax , +.Pp +.It +.Li cwde +--- sign-extend word in +.Li %ax +to long in +.Li %eax , +.Pp +.It +.Li cwd +--- sign-extend word in +.Li %ax +to long in +.Li %dx:%ax , +.Pp +.It +.Li cdq +--- sign-extend dword in +.Li %eax +to quad in +.Li %edx:%eax , +.Pp +.It +.Li cdqe +--- sign-extend dword in +.Li %eax +to quad in +.Li %rax +(x86-64 only), +.Pp +.It +.Li cqo +--- sign-extend quad in +.Li %rax +to octuple in +.Li %rdx:%rax +(x86-64 only), +.El +.Pp +are called +.Li cbtw , +.Li cwtl , +.Li cwtd , +.Li cltd , +.Li cltq , +and +.Li cqto +in AT&T naming. +.Li as +accepts either naming for these instructions. +.Pp +Far call/jump instructions are +.Li lcall +and +.Li ljmp +in AT&T syntax, but are +.Li call far +and +.Li jump far +in Intel convention. +.Pp +.Ss Register Naming +Register operands are always prefixed with +.Li % . +The 80386 registers consist of +.Pp +.Bl -bullet +.It +the 8 32-bit registers +.Li %eax +(the accumulator), +.Li %ebx , +.Li %ecx , +.Li %edx , +.Li %edi , +.Li %esi , +.Li %ebp +(the frame pointer), and +.Li %esp +(the stack pointer). +.Pp +.It +the 8 16-bit low-ends of these: +.Li %ax , +.Li %bx , +.Li %cx , +.Li %dx , +.Li %di , +.Li %si , +.Li %bp , +and +.Li %sp . +.Pp +.It +the 8 8-bit registers: +.Li %ah , +.Li %al , +.Li %bh , +.Li %bl , +.Li %ch , +.Li %cl , +.Li %dh , +and +.Li %dl +(These are the high-bytes and low-bytes of +.Li %ax , +.Li %bx , +.Li %cx , +and +.Li %dx ) +.Pp +.It +the 6 section registers +.Li %cs +(code section), +.Li %ds +(data section), +.Li %ss +(stack section), +.Li %es , +.Li %fs , +and +.Li %gs . +.Pp +.It +the 3 processor control registers +.Li %cr0 , +.Li %cr2 , +and +.Li %cr3 . +.Pp +.It +the 6 debug registers +.Li %db0 , +.Li %db1 , +.Li %db2 , +.Li %db3 , +.Li %db6 , +and +.Li %db7 . +.Pp +.It +the 2 test registers +.Li %tr6 +and +.Li %tr7 . +.Pp +.It +the 8 floating point register stack +.Li %st +or equivalently +.Li %st(0) , +.Li %st(1) , +.Li %st(2) , +.Li %st(3) , +.Li %st(4) , +.Li %st(5) , +.Li %st(6) , +and +.Li %st(7) . +These registers are overloaded by 8 MMX registers +.Li %mm0 , +.Li %mm1 , +.Li %mm2 , +.Li %mm3 , +.Li %mm4 , +.Li %mm5 , +.Li %mm6 +and +.Li %mm7 . +.Pp +.It +the 8 SSE registers registers +.Li %xmm0 , +.Li %xmm1 , +.Li %xmm2 , +.Li %xmm3 , +.Li %xmm4 , +.Li %xmm5 , +.Li %xmm6 +and +.Li %xmm7 . +.El +.Pp +The AMD x86-64 architecture extends the register set by: +.Pp +.Bl -bullet +.It +enhancing the 8 32-bit registers to 64-bit: +.Li %rax +(the accumulator), +.Li %rbx , +.Li %rcx , +.Li %rdx , +.Li %rdi , +.Li %rsi , +.Li %rbp +(the frame pointer), +.Li %rsp +(the stack pointer) +.Pp +.It +the 8 extended registers +.Li %r8 +-- +.Li %r15 . +.Pp +.It +the 8 32-bit low ends of the extended registers: +.Li %r8d +-- +.Li %r15d +.Pp +.It +the 8 16-bit low ends of the extended registers: +.Li %r8w +-- +.Li %r15w +.Pp +.It +the 8 8-bit low ends of the extended registers: +.Li %r8b +-- +.Li %r15b +.Pp +.It +the 4 8-bit registers: +.Li %sil , +.Li %dil , +.Li %bpl , +.Li %spl . +.Pp +.It +the 8 debug registers: +.Li %db8 +-- +.Li %db15 . +.Pp +.It +the 8 SSE registers: +.Li %xmm8 +-- +.Li %xmm15 . +.El +.Pp +.Ss Instruction Prefixes +Instruction prefixes are used to modify the following instruction. They are +used to repeat string instructions, to provide section overrides, to perform +bus lock operations, and to change operand and address sizes. (Most instructions +that normally operate on 32-bit operands will use 16-bit operands if the instruction +has an \(lqoperand size\(rq prefix.) Instruction prefixes are best written on the +same line as the instruction they act upon. For example, the +.Li scas +(scan string) instruction is repeated with: +.Pp +.Bd -literal -offset indent + repne scas %es:(%edi),%al +.Ed +.Pp +You may also place prefixes on the lines immediately preceding the instruction, +but this circumvents checks that +.Li as +does with prefixes, and will not work with all prefixes. +.Pp +Here is a list of instruction prefixes: +.Pp +.Bl -bullet +.It +Section override prefixes +.Li cs , +.Li ds , +.Li ss , +.Li es , +.Li fs , +.Li gs . +These are automatically added by specifying using the +.Va section +: +.Va memory-operand +form for memory references. +.Pp +.It +Operand/Address size prefixes +.Li data16 +and +.Li addr16 +change 32-bit operands/addresses into 16-bit operands/addresses, while +.Li data32 +and +.Li addr32 +change 16-bit ones (in a +.Li .code16 +section) into 32-bit operands/addresses. These prefixes +.Em must +appear on the same line of code as the instruction they modify. For example, +in a 16-bit +.Li .code16 +section, you might write: +.Pp +.Bd -literal -offset indent + addr32 jmpl *(%ebx) +.Ed +.Pp +.It +The bus lock prefix +.Li lock +inhibits interrupts during execution of the instruction it precedes. (This +is only valid with certain instructions; see a 80386 manual for details). +.Pp +.It +The wait for coprocessor prefix +.Li wait +waits for the coprocessor to complete the current instruction. This should +never be needed for the 80386/80387 combination. +.Pp +.It +The +.Li rep , +.Li repe , +and +.Li repne +prefixes are added to string instructions to make them repeat +.Li %ecx +times ( +.Li %cx +times if the current address size is 16-bits). +.It +The +.Li rex +family of prefixes is used by x86-64 to encode extensions to i386 instruction +set. The +.Li rex +prefix has four bits --- an operand size overwrite ( +.Li 64 ) +used to change operand size from 32-bit to 64-bit and X, Y and Z extensions +bits used to extend the register set. +.Pp +You may write the +.Li rex +prefixes directly. The +.Li rex64xyz +instruction emits +.Li rex +prefix with all the bits set. By omitting the +.Li 64 , +.Li x , +.Li y +or +.Li z +you may write other prefixes as well. Normally, there is no need to write +the prefixes explicitly, since gas will automatically generate them based +on the instruction operands. +.El +.Pp +.Ss Memory References +An Intel syntax indirect memory reference of the form +.Pp +.Bd -literal -offset indent +section:[base + index*scale + disp] +.Ed +.Pp +is translated into the AT&T syntax +.Pp +.Bd -literal -offset indent +section:disp(base, index, scale) +.Ed +.Pp +where +.Va base +and +.Va index +are the optional 32-bit base and index registers, +.Va disp +is the optional displacement, and +.Va scale , +taking the values 1, 2, 4, and 8, multiplies +.Va index +to calculate the address of the operand. If no +.Va scale +is specified, +.Va scale +is taken to be 1. +.Va section +specifies the optional section register for the memory operand, and may override +the default section register (see a 80386 manual for section register defaults). +Note that section overrides in AT&T syntax +.Em must +be preceded by a +.Li % . +If you specify a section override which coincides with the default section +register, +.Li as +does +.Em not +output any section register override prefixes to assemble the given instruction. +Thus, section overrides can be specified to emphasize which section register +is used for a given memory operand. +.Pp +Here are some examples of Intel and AT&T style memory references: +.Pp +.Bl -tag -width Ds +.It AT&T: Li -4(%ebp), Intel: Li [ebp - 4] +.Va base +is +.Li %ebp ; +.Va disp +is +.Li -4 . +.Va section +is missing, and the default section is used ( +.Li %ss +for addressing with +.Li %ebp +as the base register). +.Va index , +.Va scale +are both missing. +.Pp +.It AT&T: Li foo(,%eax,4), Intel: Li [foo + eax*4] +.Va index +is +.Li %eax +(scaled by a +.Va scale +4); +.Va disp +is +.Li foo . +All other fields are missing. The section register here defaults to +.Li %ds . +.Pp +.It AT&T: Li foo(,1); Intel Li [foo] +This uses the value pointed to by +.Li foo +as a memory operand. Note that +.Va base +and +.Va index +are both missing, but there is only +.Em one +.Li , . +This is a syntactic exception. +.Pp +.It AT&T: Li %gs:foo; Intel Li gs:foo +This selects the contents of the variable +.Li foo +with section register +.Va section +being +.Li %gs . +.El +.Pp +Absolute (as opposed to PC relative) call and jump operands must be prefixed +with +.Li * . +If no +.Li * +is specified, +.Li as +always chooses PC relative addressing for jump/call labels. +.Pp +Any instruction that has a memory operand, but no register operand, +.Em must +specify its size (byte, word, long, or quadruple) with an instruction mnemonic +suffix ( +.Li b , +.Li w , +.Li l +or +.Li q , +respectively). +.Pp +The x86-64 architecture adds an RIP (instruction pointer relative) addressing. +This addressing mode is specified by using +.Li rip +as a base register. Only constant offsets are valid. For example: +.Pp +.Bl -tag -width Ds +.It AT&T: Li 1234(%rip), Intel: Li [rip + 1234] +Points to the address 1234 bytes past the end of the current instruction. +.Pp +.It AT&T: Li symbol(%rip), Intel: Li [rip + symbol] +Points to the +.Li symbol +in RIP relative way, this is shorter than the default absolute addressing. +.El +.Pp +Other addressing modes remain unchanged in x86-64 architecture, except registers +used are 64-bit instead of 32-bit. +.Pp +.Ss Handling of Jump Instructions +Jump instructions are always optimized to use the smallest possible displacements. +This is accomplished by using byte (8-bit) displacement jumps whenever the +target is sufficiently close. If a byte displacement is insufficient a long +displacement is used. We do not support word (16-bit) displacement jumps in +32-bit mode (i.e. prefixing the jump instruction with the +.Li data16 +instruction prefix), since the 80386 insists upon masking +.Li %eip +to 16 bits after the word displacement is added. (See alsosee Section +.Dq i386-Arch ) +.Pp +Note that the +.Li jcxz , +.Li jecxz , +.Li loop , +.Li loopz , +.Li loope , +.Li loopnz +and +.Li loopne +instructions only come in byte displacements, so that if you use these instructions +( +.Li gcc +does not use them) you may get an error message (and incorrect code). The +AT&T 80386 assembler tries to get around this problem by expanding +.Li jcxz foo +to +.Pp +.Bd -literal -offset indent + jcxz cx_zero + jmp cx_nonzero +cx_zero: jmp foo +cx_nonzero: +.Ed +.Pp +.Ss Floating Point +All 80387 floating point types except packed BCD are supported. (BCD support +may be added without much difficulty). These data types are 16-, 32-, and +64- bit integers, and single (32-bit), double (64-bit), and extended (80-bit) +precision floating point. Each supported type has an instruction mnemonic +suffix and a constructor associated with it. Instruction mnemonic suffixes +specify the operand's data type. Constructors build these data types into +memory. +.Pp +.Bl -bullet +.It +Floating point constructors are +.Li .float +or +.Li .single , +.Li .double , +and +.Li .tfloat +for 32-, 64-, and 80-bit formats. These correspond to instruction mnemonic +suffixes +.Li s , +.Li l , +and +.Li t . +.Li t +stands for 80-bit (ten byte) real. The 80387 only supports this format via +the +.Li fldt +(load 80-bit real to stack top) and +.Li fstpt +(store 80-bit real and pop stack) instructions. +.Pp +.It +Integer constructors are +.Li .word , +.Li .long +or +.Li .int , +and +.Li .quad +for the 16-, 32-, and 64-bit integer formats. The corresponding instruction +mnemonic suffixes are +.Li s +(single), +.Li l +(long), and +.Li q +(quad). As with the 80-bit real format, the 64-bit +.Li q +format is only present in the +.Li fildq +(load quad integer to stack top) and +.Li fistpq +(store quad integer and pop stack) instructions. +.El +.Pp +Register to register operations should not use instruction mnemonic suffixes. +.Li fstl %st, %st(1) +will give a warning, and be assembled as if you wrote +.Li fst %st, %st(1) , +since all register to register operations use 80-bit floating point operands. +(Contrast this with +.Li fstl %st, mem , +which converts +.Li %st +from 80-bit to 64-bit floating point format, then stores the result in the +4 byte location +.Li mem ) +.Pp +.Ss Intel's MMX and AMD's 3DNow! SIMD Operations +.Li as +supports Intel's MMX instruction set (SIMD instructions for integer data), +available on Intel's Pentium MMX processors and Pentium II processors, AMD's +K6 and K6-2 processors, Cyrix' M2 processor, and probably others. It also +supports AMD's 3DNow! instruction set (SIMD instructions for 32-bit floating +point data) available on AMD's K6-2 processor and possibly others in the future. +.Pp +Currently, +.Li as +does not support Intel's floating point SIMD, Katmai (KNI). +.Pp +The eight 64-bit MMX operands, also used by 3DNow!, are called +.Li %mm0 , +.Li %mm1 , +\&... +.Li %mm7 . +They contain eight 8-bit integers, four 16-bit integers, two 32-bit integers, +one 64-bit integer, or two 32-bit floating point values. The MMX registers +cannot be used at the same time as the floating point stack. +.Pp +See Intel and AMD documentation, keeping in mind that the operand order in +instructions is reversed from the Intel syntax. +.Pp +.Ss Writing 16-bit Code +While +.Li as +normally writes only \(lqpure\(rq 32-bit i386 code or 64-bit x86-64 code depending +on the default configuration, it also supports writing code to run in real +mode or in 16-bit protected mode code segments. To do this, put a +.Li .code16 +or +.Li .code16gcc +directive before the assembly language instructions to be run in 16-bit mode. +You can switch +.Li as +back to writing normal 32-bit code with the +.Li .code32 +directive. +.Pp +.Li .code16gcc +provides experimental support for generating 16-bit code from gcc, and differs +from +.Li .code16 +in that +.Li call , +.Li ret , +.Li enter , +.Li leave , +.Li push , +.Li pop , +.Li pusha , +.Li popa , +.Li pushf , +and +.Li popf +instructions default to 32-bit size. This is so that the stack pointer is +manipulated in the same way over function calls, allowing access to function +parameters at the same stack offsets as in 32-bit mode. +.Li .code16gcc +also automatically adds address size prefixes where necessary to use the 32-bit +addressing modes that gcc generates. +.Pp +The code which +.Li as +generates in 16-bit mode will not necessarily run on a 16-bit pre-80386 processor. +To write code that runs on such a processor, you must refrain from using +.Em any +32-bit constructs which require +.Li as +to output address or operand size prefixes. +.Pp +Note that writing 16-bit code instructions by explicitly specifying a prefix +or an instruction mnemonic suffix within a 32-bit code section generates different +machine instructions than those generated for a 16-bit code segment. In a +32-bit code section, the following code generates the machine opcode bytes +.Li 66 6a 04 , +which pushes the value +.Li 4 +onto the stack, decrementing +.Li %esp +by 2. +.Pp +.Bd -literal -offset indent + pushw $4 +.Ed +.Pp +The same code in a 16-bit code section would generate the machine opcode bytes +.Li 6a 04 +(i.e., without the operand size prefix), which is correct since the processor +default operand size is assumed to be 16 bits in a 16-bit code section. +.Pp +.Ss AT&T Syntax bugs +The UnixWare assembler, and probably other AT&T derived ix86 Unix assemblers, +generate floating point instructions with reversed source and destination +registers in certain cases. Unfortunately, gcc and possibly many other programs +use this reversed syntax, so we're stuck with it. +.Pp +For example +.Pp +.Bd -literal -offset indent + fsub %st,%st(3) +.Ed +results in +.Li %st(3) +being updated to +.Li %st - %st(3) +rather than the expected +.Li %st(3) - %st . +This happens with all the non-commutative arithmetic floating point operations +with two register operands where the source register is +.Li %st +and the destination register is +.Li %st(i) . +.Pp +.Ss Specifying CPU Architecture +.Li as +may be told to assemble for a particular CPU (sub-)architecture with the +.Li .arch Va cpu_type +directive. This directive enables a warning when gas detects an instruction +that is not supported on the CPU specified. The choices for +.Va cpu_type +are: +.Pp +.TS +l l l l. + +i8086 i186 i286 i386 +i486 i586 i686 pentium +pentiumpro pentiumii pentiumiii pentium4 +prescott nocona core core2 +amdfam10 +k6 athlon sledgehammer k8 +\&.mmx .sse .sse2 .sse3 +\&.ssse3 .sse4.1 .sse4.2 .sse4 +\&.sse4a .3dnow .3dnowa .padlock +\&.pacifica .svme .abm +.TE +.Pp +Apart from the warning, there are only two other effects on +.Li as +operation; Firstly, if you specify a CPU other than +.Li i486 , +then shift by one instructions such as +.Li sarl $1, %eax +will automatically use a two byte opcode sequence. The larger three byte opcode +sequence is used on the 486 (and when no architecture is specified) because +it executes faster on the 486. Note that you can explicitly request the two +byte opcode by writing +.Li sarl %eax . +Secondly, if you specify +.Li i8086 , +.Li i186 , +or +.Li i286 , +.Em and +.Li .code16 +or +.Li .code16gcc +then byte offset conditional jumps will be promoted when necessary to a two +instruction sequence consisting of a conditional jump of the opposite sense +around an unconditional jump to the target. +.Pp +Following the CPU architecture (but not a sub-architecture, which are those +starting with a dot), you may specify +.Li jumps +or +.Li nojumps +to control automatic promotion of conditional jumps. +.Li jumps +is the default, and enables jump promotion; All external jumps will be of +the long variety, and file-local jumps will be promoted as necessary. (see Section +.Dq i386-Jumps ) +.Li nojumps +leaves external conditional jumps as byte offset jumps, and warns about file-local +conditional jumps that +.Li as +promotes. Unconditional jumps are treated as for +.Li jumps . +.Pp +For example +.Pp +.Bd -literal -offset indent + .arch i8086,nojumps +.Ed +.Pp +.Ss Notes +There is some trickery concerning the +.Li mul +and +.Li imul +instructions that deserves mention. The 16-, 32-, 64- and 128-bit expanding +multiplies (base opcode +.Li 0xf6 ; +extension 4 for +.Li mul +and 5 for +.Li imul ) +can be output only in the one operand form. Thus, +.Li imul %ebx, %eax +does +.Em not +select the expanding multiply; the expanding multiply would clobber the +.Li %edx +register, and this would confuse +.Li gcc +output. Use +.Li imul %ebx +to get the 64-bit product in +.Li %edx:%eax . +.Pp +We have added a two operand form of +.Li imul +when the first operand is an immediate mode expression and the second operand +is a register. This is just a shorthand, so that, multiplying +.Li %eax +by 69, for example, can be done with +.Li imul $69, %eax +rather than +.Li imul $69, %eax, %eax . +.Pp +.Sh IA-64 Dependent Features +.Ss Options +.Bl -tag -width Ds +.It -mconstant-gp +This option instructs the assembler to mark the resulting object file as using +the \(lqconstant GP\(rq model. With this model, it is assumed that the entire program +uses a single global pointer (GP) value. Note that this option does not in +any fashion affect the machine code emitted by the assembler. All it does +is turn on the EF_IA_64_CONS_GP flag in the ELF file header. +.Pp +.It -mauto-pic +This option instructs the assembler to mark the resulting object file as using +the \(lqconstant GP without function descriptor\(rq data model. This model is like +the \(lqconstant GP\(rq model, except that it additionally does away with function +descriptors. What this means is that the address of a function refers directly +to the function's code entry-point. Normally, such an address would refer +to a function descriptor, which contains both the code entry-point and the +GP-value needed by the function. Note that this option does not in any fashion +affect the machine code emitted by the assembler. All it does is turn on the +EF_IA_64_NOFUNCDESC_CONS_GP flag in the ELF file header. +.Pp +.It -milp32 +.It -milp64 +.It -mlp64 +.It -mp64 +These options select the data model. The assembler defaults to +.Li -mlp64 +(LP64 data model). +.Pp +.It -mle +.It -mbe +These options select the byte order. The +.Li -mle +option selects little-endian byte order (default) and +.Li -mbe +selects big-endian byte order. Note that IA-64 machine code always uses little-endian +byte order. +.Pp +.It -mtune=itanium1 +.It -mtune=itanium2 +Tune for a particular IA-64 CPU, +.Va itanium1 +or +.Va itanium2 . +The default is +.Va itanium2 . +.Pp +.It -munwind-check=warning +.It -munwind-check=error +These options control what the assembler will do when performing consistency +checks on unwind directives. +.Li -munwind-check=warning +will make the assembler issue a warning when an unwind directive check fails. +This is the default. +.Li -munwind-check=error +will make the assembler issue an error when an unwind directive check fails. +.Pp +.It -mhint.b=ok +.It -mhint.b=warning +.It -mhint.b=error +These options control what the assembler will do when the +.Li hint.b +instruction is used. +.Li -mhint.b=ok +will make the assembler accept +.Li hint.b . +.Li -mint.b=warning +will make the assembler issue a warning when +.Li hint.b +is used. +.Li -mhint.b=error +will make the assembler treat +.Li hint.b +as an error, which is the default. +.Pp +.It -x +.It -xexplicit +These options turn on dependency violation checking. +.Pp +.It -xauto +This option instructs the assembler to automatically insert stop bits where +necessary to remove dependency violations. This is the default mode. +.Pp +.It -xnone +This option turns off dependency violation checking. +.Pp +.It -xdebug +This turns on debug output intended to help tracking down bugs in the dependency +violation checker. +.Pp +.It -xdebugn +This is a shortcut for -xnone -xdebug. +.Pp +.It -xdebugx +This is a shortcut for -xexplicit -xdebug. +.Pp +.El +.Ss Syntax +The assembler syntax closely follows the IA-64 Assembly Language Reference +Guide. +.Pp +.Em Special Characters +.Pp +.Li // +is the line comment token. +.Pp +.Li ; +can be used instead of a newline to separate statements. +.Pp +.Em Register Names +.Pp +The 128 integer registers are referred to as +.Li r Va n . +The 128 floating-point registers are referred to as +.Li f Va n . +The 128 application registers are referred to as +.Li ar Va n . +The 128 control registers are referred to as +.Li cr Va n . +The 64 one-bit predicate registers are referred to as +.Li p Va n . +The 8 branch registers are referred to as +.Li b Va n . +In addition, the assembler defines a number of aliases: +.Li gp +( +.Li r1 ) , +.Li sp +( +.Li r12 ) , +.Li rp +( +.Li b0 ) , +.Li ret0 +( +.Li r8 ) , +.Li ret1 +( +.Li r9 ) , +.Li ret2 +( +.Li r10 ) , +.Li ret3 +( +.Li r9 ) , +.Li farg Va n +( +.Li f8+ Va n ) , +and +.Li fret Va n +( +.Li f8+ Va n ) . +.Pp +For convenience, the assembler also defines aliases for all named application +and control registers. For example, +.Li ar.bsp +refers to the register backing store pointer ( +.Li ar17 ) . +Similarly, +.Li cr.eoi +refers to the end-of-interrupt register ( +.Li cr67 ) . +.Pp +.Em IA-64 Processor-Status-Register (PSR) Bit Names +.Pp +The assembler defines bit masks for each of the bits in the IA-64 processor +status register. For example, +.Li psr.ic +corresponds to a value of 0x2000. These masks are primarily intended for use +with the +.Li ssm +/ +.Li sum +and +.Li rsm +/ +.Li rum +instructions, but they can be used anywhere else where an integer constant +is expected. +.Pp +.Ss Opcodes +For detailed information on the IA-64 machine instruction set, see the +.Lk http://developer.intel.com/design/itanium/arch_spec.htm . +.Pp +.Sh MIPS Dependent Features +GNU +.Li as +for mips architectures supports several different mips processors, and MIPS +ISA levels I through V, MIPS32, and MIPS64. For information about the mips +instruction set, see +.Em MIPS RISC Architecture , +by Kane and Heindrich (Prentice-Hall). For an overview of mips assembly conventions, +see \(lqAppendix D: Assembly Language Programming\(rq in the same work. +.Pp +.Ss Assembler options +The mips configurations of GNU +.Li as +support these special options: +.Pp +.Bl -tag -width Ds +.It -G Va num +This option sets the largest size of an object that can be referenced implicitly +with the +.Li gp +register. It is only accepted for targets that use ecoff format. The default +value is 8. +.Pp +.It -EB +.It -EL +Any mips configuration of +.Li as +can select big-endian or little-endian output at run time (unlike the other +GNU development tools, which must be configured for one or the other). Use +.Li -EB +to select big-endian output, and +.Li -EL +for little-endian. +.Pp +.It -KPIC +Generate SVR4-style PIC. This option tells the assembler to generate SVR4-style +position-independent macro expansions. It also tells the assembler to mark +the output file as PIC. +.Pp +.It -mvxworks-pic +Generate VxWorks PIC. This option tells the assembler to generate VxWorks-style +position-independent macro expansions. +.Pp +.It -mips1 +.It -mips2 +.It -mips3 +.It -mips4 +.It -mips5 +.It -mips32 +.It -mips32r2 +.It -mips64 +.It -mips64r2 +Generate code for a particular MIPS Instruction Set Architecture level. +.Li -mips1 +corresponds to the r2000 and r3000 processors, +.Li -mips2 +to the r6000 processor, +.Li -mips3 +to the r4000 processor, and +.Li -mips4 +to the r8000 and r10000 processors. +.Li -mips5 , +.Li -mips32 , +.Li -mips32r2 , +.Li -mips64 , +and +.Li -mips64r2 +correspond to generic MIPS V, MIPS32, MIPS32 Release 2, MIPS64, and MIPS64 +Release 2 ISA processors, respectively. You can also switch instruction sets +during the assembly; see MIPS ISA, Directives to override the ISA level. +.Pp +.It -mgp32 +.It -mfp32 +Some macros have different expansions for 32-bit and 64-bit registers. The +register sizes are normally inferred from the ISA and ABI, but these flags +force a certain group of registers to be treated as 32 bits wide at all times. +.Li -mgp32 +controls the size of general-purpose registers and +.Li -mfp32 +controls the size of floating-point registers. +.Pp +The +.Li .set gp=32 +and +.Li .set fp=32 +directives allow the size of registers to be changed for parts of an object. +The default value is restored by +.Li .set gp=default +and +.Li .set fp=default . +.Pp +On some MIPS variants there is a 32-bit mode flag; when this flag is set, +64-bit instructions generate a trap. Also, some 32-bit OSes only save the +32-bit registers on a context switch, so it is essential never to use the +64-bit registers. +.Pp +.It -mgp64 +.It -mfp64 +Assume that 64-bit registers are available. This is provided in the interests +of symmetry with +.Li -mgp32 +and +.Li -mfp32 . +.Pp +The +.Li .set gp=64 +and +.Li .set fp=64 +directives allow the size of registers to be changed for parts of an object. +The default value is restored by +.Li .set gp=default +and +.Li .set fp=default . +.Pp +.It -mips16 +.It -no-mips16 +Generate code for the MIPS 16 processor. This is equivalent to putting +.Li .set mips16 +at the start of the assembly file. +.Li -no-mips16 +turns off this option. +.Pp +.It -msmartmips +.It -mno-smartmips +Enables the SmartMIPS extensions to the MIPS32 instruction set, which provides +a number of new instructions which target smartcard and cryptographic applications. +This is equivalent to putting +.Li .set smartmips +at the start of the assembly file. +.Li -mno-smartmips +turns off this option. +.Pp +.It -mips3d +.It -no-mips3d +Generate code for the MIPS-3D Application Specific Extension. This tells the +assembler to accept MIPS-3D instructions. +.Li -no-mips3d +turns off this option. +.Pp +.It -mdmx +.It -no-mdmx +Generate code for the MDMX Application Specific Extension. This tells the +assembler to accept MDMX instructions. +.Li -no-mdmx +turns off this option. +.Pp +.It -mdsp +.It -mno-dsp +Generate code for the DSP Release 1 Application Specific Extension. This tells +the assembler to accept DSP Release 1 instructions. +.Li -mno-dsp +turns off this option. +.Pp +.It -mdspr2 +.It -mno-dspr2 +Generate code for the DSP Release 2 Application Specific Extension. This option +implies -mdsp. This tells the assembler to accept DSP Release 2 instructions. +.Li -mno-dspr2 +turns off this option. +.Pp +.It -mmt +.It -mno-mt +Generate code for the MT Application Specific Extension. This tells the assembler +to accept MT instructions. +.Li -mno-mt +turns off this option. +.Pp +.It -mfix7000 +.It -mno-fix7000 +Cause nops to be inserted if the read of the destination register of an mfhi +or mflo instruction occurs in the following two instructions. +.Pp +.It -mfix-vr4120 +.It -no-mfix-vr4120 +Insert nops to work around certain VR4120 errata. This option is intended +to be used on GCC-generated code: it is not designed to catch all problems +in hand-written assembler code. +.Pp +.It -mfix-vr4130 +.It -no-mfix-vr4130 +Insert nops to work around the VR4130 +.Li mflo +/ +.Li mfhi +errata. +.Pp +.It -m4010 +.It -no-m4010 +Generate code for the LSI r4010 chip. This tells the assembler to accept the +r4010 specific instructions ( +.Li addciu , +.Li ffc , +etc.), and to not schedule +.Li nop +instructions around accesses to the +.Li HI +and +.Li LO +registers. +.Li -no-m4010 +turns off this option. +.Pp +.It -m4650 +.It -no-m4650 +Generate code for the MIPS r4650 chip. This tells the assembler to accept +the +.Li mad +and +.Li madu +instruction, and to not schedule +.Li nop +instructions around accesses to the +.Li HI +and +.Li LO +registers. +.Li -no-m4650 +turns off this option. +.Pp +.It -m3900 +.It -no-m3900 +.It -m4100 +.It -no-m4100 +For each option +.Li -m Va nnnn , +generate code for the MIPS r +.Va nnnn +chip. This tells the assembler to accept instructions specific to that chip, +and to schedule for that chip's hazards. +.Pp +.It -march= Va cpu +Generate code for a particular MIPS cpu. It is exactly equivalent to +.Li -m Va cpu , +except that there are more value of +.Va cpu +understood. Valid +.Va cpu +value are: +.Pp +.Qo +2000, 3000, 3900, 4000, 4010, 4100, 4111, vr4120, vr4130, vr4181, 4300, 4400, +4600, 4650, 5000, rm5200, rm5230, rm5231, rm5261, rm5721, vr5400, vr5500, +6000, rm7000, 8000, rm9000, 10000, 12000, 4kc, 4km, 4kp, 4ksc, 4kec, 4kem, +4kep, 4ksd, m4k, m4kp, 24kc, 24kf, 24kx, 24kec, 24kef, 24kex, 34kc, 34kf, +34kx, 74kc, 74kf, 74kx, 5kc, 5kf, 20kc, 25kf, sb1, sb1a +.Qc +.Pp +.It -mtune= Va cpu +Schedule and tune for a particular MIPS cpu. Valid +.Va cpu +values are identical to +.Li -march= Va cpu . +.Pp +.It -mabi= Va abi +Record which ABI the source code uses. The recognized arguments are: +.Li 32 , +.Li n32 , +.Li o64 , +.Li 64 +and +.Li eabi . +.Pp +.It -msym32 +.It -mno-sym32 +Equivalent to adding +.Li .set sym32 +or +.Li .set nosym32 +to the beginning of the assembler input.See Section +.Dq MIPS symbol sizes . +.Pp +.It -nocpp +This option is ignored. It is accepted for command-line compatibility with +other assemblers, which use it to turn off C style preprocessing. With GNU +.Li as , +there is no need for +.Li -nocpp , +because the GNU assembler itself never runs the C preprocessor. +.Pp +.It --construct-floats +.It --no-construct-floats +The +.Li --no-construct-floats +option disables the construction of double width floating point constants +by loading the two halves of the value into the two single width floating +point registers that make up the double width register. This feature is useful +if the processor support the FR bit in its status register, and this bit is +known (by the programmer) to be set. This bit prevents the aliasing of the +double width register by the single width registers. +.Pp +By default +.Li --construct-floats +is selected, allowing construction of these floating point constants. +.Pp +.It --trap +.It --no-break +.Li as +automatically macro expands certain division and multiplication instructions +to check for overflow and division by zero. This option causes +.Li as +to generate code to take a trap exception rather than a break exception when +an error is detected. The trap instructions are only supported at Instruction +Set Architecture level 2 and higher. +.Pp +.It --break +.It --no-trap +Generate code to take a break exception rather than a trap exception when +an error is detected. This is the default. +.Pp +.It -mpdr +.It -mno-pdr +Control generation of +.Li .pdr +sections. Off by default on IRIX, on elsewhere. +.Pp +.It -mshared +.It -mno-shared +When generating code using the Unix calling conventions (selected by +.Li -KPIC +or +.Li -mcall_shared ) , +gas will normally generate code which can go into a shared library. The +.Li -mno-shared +option tells gas to generate code which uses the calling convention, but can +not go into a shared library. The resulting code is slightly more efficient. +This option only affects the handling of the +.Li .cpload +and +.Li .cpsetup +pseudo-ops. +.El +.Pp +.Ss MIPS ECOFF object code +Assembling for a mips ecoff target supports some additional sections besides +the usual +.Li .text , +.Li .data +and +.Li .bss . +The additional sections are +.Li .rdata , +used for read-only data, +.Li .sdata , +used for small data, and +.Li .sbss , +used for small common objects. +.Pp +When assembling for ecoff, the assembler uses the +.Li $gp +( +.Li $28 ) +register to form the address of a \(lqsmall object\(rq. Any object in the +.Li .sdata +or +.Li .sbss +sections is considered \(lqsmall\(rq in this sense. For external objects, or for objects +in the +.Li .bss +section, you can use the +.Li gcc +.Li -G +option to control the size of objects addressed via +.Li $gp ; +the default value is 8, meaning that a reference to any object eight bytes +or smaller uses +.Li $gp . +Passing +.Li -G 0 +to +.Li as +prevents it from using the +.Li $gp +register on the basis of object size (but the assembler uses +.Li $gp +for objects in +.Li .sdata +or +.Li sbss +in any case). The size of an object in the +.Li .bss +section is set by the +.Li .comm +or +.Li .lcomm +directive that defines it. The size of an external object may be set with +the +.Li .extern +directive. For example, +.Li .extern sym,4 +declares that the object at +.Li sym +is 4 bytes in length, whie leaving +.Li sym +otherwise undefined. +.Pp +Using small ecoff objects requires linker support, and assumes that the +.Li $gp +register is correctly initialized (normally done automatically by the startup +code). mips ecoff assembly code must not modify the +.Li $gp +register. +.Pp +.Ss Directives for debugging information +mips ecoff +.Li as +supports several directives used for generating debugging information which +are not support by traditional mips assemblers. These are +.Li .def , +.Li .endef , +.Li .dim , +.Li .file , +.Li .scl , +.Li .size , +.Li .tag , +.Li .type , +.Li .val , +.Li .stabd , +.Li .stabn , +and +.Li .stabs . +The debugging information generated by the three +.Li .stab +directives can only be read by gdb, not by traditional mips debuggers (this +enhancement is required to fully support C++ debugging). These directives +are primarily used by compilers, not assembly language programmers! +.Pp +.Ss Directives to override the size of symbols +The n64 ABI allows symbols to have any 64-bit value. Although this provides +a great deal of flexibility, it means that some macros have much longer expansions +than their 32-bit counterparts. For example, the non-PIC expansion of +.Li dla $4,sym +is usually: +.Pp +.Bd -literal -offset indent +lui $4,%highest(sym) +lui $1,%hi(sym) +daddiu $4,$4,%higher(sym) +daddiu $1,$1,%lo(sym) +dsll32 $4,$4,0 +daddu $4,$4,$1 +.Ed +.Pp +whereas the 32-bit expansion is simply: +.Pp +.Bd -literal -offset indent +lui $4,%hi(sym) +daddiu $4,$4,%lo(sym) +.Ed +.Pp +n64 code is sometimes constructed in such a way that all symbolic constants +are known to have 32-bit values, and in such cases, it's preferable to use +the 32-bit expansion instead of the 64-bit expansion. +.Pp +You can use the +.Li .set sym32 +directive to tell the assembler that, from this point on, all expressions +of the form +.Li Va symbol +or +.Li Va symbol + Va offset +have 32-bit values. For example: +.Pp +.Bd -literal -offset indent +\&.set sym32 +dla $4,sym +lw $4,sym+16 +sw $4,sym+0x8000($4) +.Ed +.Pp +will cause the assembler to treat +.Li sym , +.Li sym+16 +and +.Li sym+0x8000 +as 32-bit values. The handling of non-symbolic addresses is not affected. +.Pp +The directive +.Li .set nosym32 +ends a +.Li .set sym32 +block and reverts to the normal behavior. It is also possible to change the +symbol size using the command-line options +.Op -msym32 +and +.Op -mno-sym32 . +.Pp +These options and directives are always accepted, but at present, they have +no effect for anything other than n64. +.Pp +.Ss Directives to override the ISA level +GNU +.Li as +supports an additional directive to change the mips Instruction Set Architecture +level on the fly: +.Li .set mips Va n . +.Va n +should be a number from 0 to 5, or 32, 32r2, 64 or 64r2. The values other +than 0 make the assembler accept instructions for the corresponding isa level, +from that point on in the assembly. +.Li .set mips Va n +affects not only which instructions are permitted, but also how certain macros +are expanded. +.Li .set mips0 +restores the isa level to its original level: either the level you selected +with command line options, or the default for your configuration. You can +use this feature to permit specific mips3 instructions while assembling in +32 bit mode. Use this directive with care! +.Pp +The +.Li .set arch= Va cpu +directive provides even finer control. It changes the effective CPU target +and allows the assembler to use instructions specific to a particular CPU. +All CPUs supported by the +.Li -march +command line option are also selectable by this directive. The original value +is restored by +.Li .set arch=default . +.Pp +The directive +.Li .set mips16 +puts the assembler into MIPS 16 mode, in which it will assemble instructions +for the MIPS 16 processor. Use +.Li .set nomips16 +to return to normal 32 bit mode. +.Pp +Traditional mips assemblers do not support this directive. +.Pp +.Ss Directives for extending MIPS 16 bit instructions +By default, MIPS 16 instructions are automatically extended to 32 bits when +necessary. The directive +.Li .set noautoextend +will turn this off. When +.Li .set noautoextend +is in effect, any 32 bit instruction must be explicitly extended with the +.Li .e +modifier (e.g., +.Li li.e $4,1000 ) . +The directive +.Li .set autoextend +may be used to once again automatically extend instructions when necessary. +.Pp +This directive is only meaningful when in MIPS 16 mode. Traditional mips assemblers +do not support this directive. +.Pp +.Ss Directive to mark data as an instruction +The +.Li .insn +directive tells +.Li as +that the following data is actually instructions. This makes a difference +in MIPS 16 mode: when loading the address of a label which precedes instructions, +.Li as +automatically adds 1 to the value, so that jumping to the loaded address will +do the right thing. +.Pp +.Ss Directives to save and restore options +The directives +.Li .set push +and +.Li .set pop +may be used to save and restore the current settings for all the options which +are controlled by +.Li .set . +The +.Li .set push +directive saves the current settings on a stack. The +.Li .set pop +directive pops the stack and restores the settings. +.Pp +These directives can be useful inside an macro which must change an option +such as the ISA level or instruction reordering but does not want to change +the state of the code which invoked the macro. +.Pp +Traditional mips assemblers do not support these directives. +.Pp +.Ss Directives to control generation of MIPS ASE instructions +The directive +.Li .set mips3d +makes the assembler accept instructions from the MIPS-3D Application Specific +Extension from that point on in the assembly. The +.Li .set nomips3d +directive prevents MIPS-3D instructions from being accepted. +.Pp +The directive +.Li .set smartmips +makes the assembler accept instructions from the SmartMIPS Application Specific +Extension to the MIPS32 isa from that point on in the assembly. The +.Li .set nosmartmips +directive prevents SmartMIPS instructions from being accepted. +.Pp +The directive +.Li .set mdmx +makes the assembler accept instructions from the MDMX Application Specific +Extension from that point on in the assembly. The +.Li .set nomdmx +directive prevents MDMX instructions from being accepted. +.Pp +The directive +.Li .set dsp +makes the assembler accept instructions from the DSP Release 1 Application +Specific Extension from that point on in the assembly. The +.Li .set nodsp +directive prevents DSP Release 1 instructions from being accepted. +.Pp +The directive +.Li .set dspr2 +makes the assembler accept instructions from the DSP Release 2 Application +Specific Extension from that point on in the assembly. This dirctive implies +.Li .set dsp . +The +.Li .set nodspr2 +directive prevents DSP Release 2 instructions from being accepted. +.Pp +The directive +.Li .set mt +makes the assembler accept instructions from the MT Application Specific Extension +from that point on in the assembly. The +.Li .set nomt +directive prevents MT instructions from being accepted. +.Pp +Traditional mips assemblers do not support these directives. +.Pp +.Sh PowerPC Dependent Features +.Ss Options +The PowerPC chip family includes several successive levels, using the same +core instruction set, but including a few additional instructions at each +level. There are exceptions to this however. For details on what instructions +each variant supports, please see the chip's architecture reference manual. +.Pp +The following table lists all available PowerPC options. +.Pp +.Bl -tag -width Ds +.It -mpwrx | -mpwr2 +Generate code for POWER/2 (RIOS2). +.Pp +.It -mpwr +Generate code for POWER (RIOS1) +.Pp +.It -m601 +Generate code for PowerPC 601. +.Pp +.It -mppc, -mppc32, -m603, -m604 +Generate code for PowerPC 603/604. +.Pp +.It -m403, -m405 +Generate code for PowerPC 403/405. +.Pp +.It -m440 +Generate code for PowerPC 440. BookE and some 405 instructions. +.Pp +.It -m7400, -m7410, -m7450, -m7455 +Generate code for PowerPC 7400/7410/7450/7455. +.Pp +.It -mppc64, -m620 +Generate code for PowerPC 620/625/630. +.Pp +.It -me500, -me500x2 +Generate code for Motorola e500 core complex. +.Pp +.It -mspe +Generate code for Motorola SPE instructions. +.Pp +.It -mppc64bridge +Generate code for PowerPC 64, including bridge insns. +.Pp +.It -mbooke64 +Generate code for 64-bit BookE. +.Pp +.It -mbooke, mbooke32 +Generate code for 32-bit BookE. +.Pp +.It -me300 +Generate code for PowerPC e300 family. +.Pp +.It -maltivec +Generate code for processors with AltiVec instructions. +.Pp +.It -mpower4 +Generate code for Power4 architecture. +.Pp +.It -mpower5 +Generate code for Power5 architecture. +.Pp +.It -mpower6 +Generate code for Power6 architecture. +.Pp +.It -mcell +Generate code for Cell Broadband Engine architecture. +.Pp +.It -mcom +Generate code Power/PowerPC common instructions. +.Pp +.It -many +Generate code for any architecture (PWR/PWRX/PPC). +.Pp +.It -mregnames +Allow symbolic names for registers. +.Pp +.It -mno-regnames +Do not allow symbolic names for registers. +.Pp +.It -mrelocatable +Support for GCC's -mrelocatable option. +.Pp +.It -mrelocatable-lib +Support for GCC's -mrelocatable-lib option. +.Pp +.It -memb +Set PPC_EMB bit in ELF flags. +.Pp +.It -mlittle, -mlittle-endian +Generate code for a little endian machine. +.Pp +.It -mbig, -mbig-endian +Generate code for a big endian machine. +.Pp +.It -msolaris +Generate code for Solaris. +.Pp +.It -mno-solaris +Do not generate code for Solaris. +.El +.Pp +.Ss PowerPC Assembler Directives +A number of assembler directives are available for PowerPC. The following +table is far from complete. +.Pp +.Bl -tag -width Ds +.It .machine "string" +This directive allows you to change the machine for which code is generated. +.Li "string" +may be any of the -m cpu selection options (without the -m) enclosed in double +quotes, +.Li "push" , +or +.Li "pop" . +.Li .machine "push" +saves the currently selected cpu, which may be restored with +.Li .machine "pop" . +.El +.Pp +.Sh SPARC Dependent Features +.Ss Options +The SPARC chip family includes several successive levels, using the same core +instruction set, but including a few additional instructions at each level. +There are exceptions to this however. For details on what instructions each +variant supports, please see the chip's architecture reference manual. +.Pp +By default, +.Li as +assumes the core instruction set (SPARC v6), but \(lqbumps\(rq the architecture level +as needed: it switches to successively higher architectures as it encounters +instructions that only exist in the higher levels. +.Pp +If not configured for SPARC v9 ( +.Li sparc64-*-* ) +GAS will not bump passed sparclite by default, an option must be passed to +enable the v9 instructions. +.Pp +GAS treats sparclite as being compatible with v8, unless an architecture is +explicitly requested. SPARC v9 is always incompatible with sparclite. +.Pp +.Bl -tag -width Ds +.It -Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite +.It -Av8plus | -Av8plusa | -Av9 | -Av9a +Use one of the +.Li -A +options to select one of the SPARC architectures explicitly. If you select +an architecture explicitly, +.Li as +reports a fatal error if it encounters an instruction or feature requiring +an incompatible or higher level. +.Pp +.Li -Av8plus +and +.Li -Av8plusa +select a 32 bit environment. +.Pp +.Li -Av9 +and +.Li -Av9a +select a 64 bit environment and are not available unless GAS is explicitly +configured with 64 bit environment support. +.Pp +.Li -Av8plusa +and +.Li -Av9a +enable the SPARC V9 instruction set with UltraSPARC extensions. +.Pp +.It -xarch=v8plus | -xarch=v8plusa +For compatibility with the Solaris v9 assembler. These options are equivalent +to -Av8plus and -Av8plusa, respectively. +.Pp +.It -bump +Warn whenever it is necessary to switch to another level. If an architecture +level is explicitly requested, GAS will not issue warnings until that level +is reached, and will then bump the level as required (except between incompatible +levels). +.Pp +.It -32 | -64 +Select the word size, either 32 bits or 64 bits. These options are only available +with the ELF object file format, and require that the necessary BFD support +has been included. +.El +.Pp +.Ss Enforcing aligned data +SPARC GAS normally permits data to be misaligned. For example, it permits +the +.Li .long +pseudo-op to be used on a byte boundary. However, the native SunOS and Solaris +assemblers issue an error when they see misaligned data. +.Pp +You can use the +.Li --enforce-aligned-data +option to make SPARC GAS also issue an error about misaligned data, just as +the SunOS and Solaris assemblers do. +.Pp +The +.Li --enforce-aligned-data +option is not the default because gcc issues misaligned data pseudo-ops when +it initializes certain packed data structures (structures defined using the +.Li packed +attribute). You may have to assemble with GAS in order to initialize packed +data structures in your own code. +.Pp +.Ss Floating Point +The Sparc uses ieee floating-point numbers. +.Pp +.Ss Sparc Machine Directives +The Sparc version of +.Li as +supports the following additional machine directives: +.Pp +.Bl -tag -width Ds +.It .align +This must be followed by the desired alignment in bytes. +.Pp +.It .common +This must be followed by a symbol name, a positive number, and +.Li "bss" . +This behaves somewhat like +.Li .comm , +but the syntax is different. +.Pp +.It .half +This is functionally identical to +.Li .short . +.Pp +.It .nword +On the Sparc, the +.Li .nword +directive produces native word sized value, ie. if assembling with -32 it +is equivalent to +.Li .word , +if assembling with -64 it is equivalent to +.Li .xword . +.Pp +.It .proc +This directive is ignored. Any text following it on the same line is also +ignored. +.Pp +.It .register +This directive declares use of a global application or system register. It +must be followed by a register name %g2, %g3, %g6 or %g7, comma and the symbol +name for that register. If symbol name is +.Li #scratch , +it is a scratch register, if it is +.Li #ignore , +it just suppresses any errors about using undeclared global register, but +does not emit any information about it into the object file. This can be useful +e.g. if you save the register before use and restore it after. +.Pp +.It .reserve +This must be followed by a symbol name, a positive number, and +.Li "bss" . +This behaves somewhat like +.Li .lcomm , +but the syntax is different. +.Pp +.It .seg +This must be followed by +.Li "text" , +.Li "data" , +or +.Li "data1" . +It behaves like +.Li .text , +.Li .data , +or +.Li .data 1 . +.Pp +.It .skip +This is functionally identical to the +.Li .space +directive. +.Pp +.It .word +On the Sparc, the +.Li .word +directive produces 32 bit values, instead of the 16 bit values it produces +on many other machines. +.Pp +.It .xword +On the Sparc V9 processor, the +.Li .xword +directive produces 64 bit values. +.El +.Pp +.Sh Reporting Bugs +Your bug reports play an essential role in making +.Xr as +reliable. +.Pp +Reporting a bug may help you by bringing a solution to your problem, or it +may not. But in any case the principal function of a bug report is to help +the entire community by making the next version of +.Xr as +work better. Bug reports are your contribution to the maintenance of +.Xr as . +.Pp +In order for a bug report to serve its purpose, you must include the information +that enables us to fix the bug. +.Pp +.Ss Have You Found a Bug? +If you are not sure whether you have found a bug, here are some guidelines: +.Pp +.Bl -bullet +.It +If the assembler gets a fatal signal, for any input whatever, that is a +.Xr as +bug. Reliable assemblers never crash. +.Pp +.It +If +.Xr as +produces an error message for valid input, that is a bug. +.Pp +.It +If +.Xr as +does not produce an error message for invalid input, that is a bug. However, +you should note that your idea of \(lqinvalid input\(rq might be our idea of \(lqan extension\(rq +or \(lqsupport for traditional practice\(rq. +.Pp +.It +If you are an experienced user of assemblers, your suggestions for improvement +of +.Xr as +are welcome in any case. +.El +.Pp +.Ss How to Report Bugs +A number of companies and individuals offer support for GNU products. If you +obtained +.Xr as +from a support organization, we recommend you contact that organization first. +.Pp +You can find contact information for many support companies and individuals +in the file +.Pa etc/SERVICE +in the GNU Emacs distribution. +.Pp +The fundamental principle of reporting bugs usefully is this: +.Sy report all the facts . +If you are not sure whether to state a fact or leave it out, state it! +.Pp +Often people omit facts because they think they know what causes the problem +and assume that some details do not matter. Thus, you might assume that the +name of a symbol you use in an example does not matter. Well, probably it +does not, but one cannot be sure. Perhaps the bug is a stray memory reference +which happens to fetch from the location where that name is stored in memory; +perhaps, if the name were different, the contents of that location would fool +the assembler into doing the right thing despite the bug. Play it safe and +give a specific, complete example. That is the easiest thing for you to do, +and the most helpful. +.Pp +Keep in mind that the purpose of a bug report is to enable us to fix the bug +if it is new to us. Therefore, always write your bug reports on the assumption +that the bug has not been reported previously. +.Pp +Sometimes people give a few sketchy facts and ask, \(lqDoes this ring a bell?\(rq +This cannot help us fix a bug, so it is basically useless. We respond by asking +for enough details to enable us to investigate. You might as well expedite +matters by sending them to begin with. +.Pp +To enable us to fix the bug, you should include all these things: +.Pp +.Bl -bullet +.It +The version of +.Xr as . +.Xr as +announces it if you start it with the +.Li --version +argument. +.Pp +Without this, we will not know whether there is any point in looking for the +bug in the current version of +.Xr as . +.Pp +.It +Any patches you may have applied to the +.Xr as +source. +.Pp +.It +The type of machine you are using, and the operating system name and version +number. +.Pp +.It +What compiler (and its version) was used to compile +.Xr as +---e.g. \(lq +.Li gcc-2.7 +\(rq\&. +.Pp +.It +The command arguments you gave the assembler to assemble your example and +observe the bug. To guarantee you will not omit something important, list +them all. A copy of the Makefile (or the output from make) is sufficient. +.Pp +If we were to try to guess the arguments, we would probably guess wrong and +then we might not encounter the bug. +.Pp +.It +A complete input file that will reproduce the bug. If the bug is observed +when the assembler is invoked via a compiler, send the assembler source, not +the high level language source. Most compilers will produce the assembler +source when run with the +.Li -S +option. If you are using +.Li gcc , +use the options +.Li -v --save-temps ; +this will save the assembler source in a file with an extension of +.Pa .s , +and also show you exactly how +.Xr as +is being run. +.Pp +.It +A description of what behavior you observe that you believe is incorrect. +For example, \(lqIt gets a fatal signal.\(rq +.Pp +Of course, if the bug is that +.Xr as +gets a fatal signal, then we will certainly notice it. But if the bug is incorrect +output, we might not notice unless it is glaringly wrong. You might as well +not give us a chance to make a mistake. +.Pp +Even if the problem you experience is a fatal signal, you should still say +so explicitly. Suppose something strange is going on, such as, your copy of +.Xr as +is out of sync, or you have encountered a bug in the C library on your system. +(This has happened!) Your copy might crash and ours would not. If you told +us to expect a crash, then when ours fails to crash, we would know that the +bug was not happening for us. If you had not told us to expect a crash, then +we would not be able to draw any conclusion from our observations. +.Pp +.It +If you wish to suggest changes to the +.Xr as +source, send us context diffs, as generated by +.Li diff +with the +.Li -u , +.Li -c , +or +.Li -p +option. Always send diffs from the old file to the new file. If you even discuss +something in the +.Xr as +source, refer to it by context, not by line number. +.Pp +The line numbers in our development sources will not match those in your sources. +Your line numbers would convey no useful information to us. +.El +.Pp +Here are some things that are not necessary: +.Pp +.Bl -bullet +.It +A description of the envelope of the bug. +.Pp +Often people who encounter a bug spend a lot of time investigating which changes +to the input file will make the bug go away and which changes will not affect +it. +.Pp +This is often time consuming and not very useful, because the way we will +find the bug is by running a single example under the debugger with breakpoints, +not by pure deduction from a series of examples. We recommend that you save +your time for something else. +.Pp +Of course, if you can find a simpler example to report +.Em instead +of the original one, that is a convenience for us. Errors in the output will +be easier to spot, running under the debugger will take less time, and so +on. +.Pp +However, simplification is not vital; if you do not want to do this, report +the bug anyway and send us the entire test case you used. +.Pp +.It +A patch for the bug. +.Pp +A patch for the bug does help us if it is a good one. But do not omit the +necessary information, such as the test case, on the assumption that a patch +is all we need. We might see problems with your patch and decide to fix the +problem another way, or we might not understand it at all. +.Pp +Sometimes with a program as complicated as +.Xr as +it is very hard to construct an example that will make the program follow +a certain path through the code. If you do not send us the example, we will +not be able to construct one, so we will not be able to verify that the bug +is fixed. +.Pp +And if we cannot understand what bug you are trying to fix, or why your patch +should be an improvement, we will not install it. A test case will help us +to understand. +.Pp +.It +A guess about what the bug is or what it depends on. +.Pp +Such guesses are usually wrong. Even we cannot guess right about such things +without first using the debugger to find the facts. +.El +.Pp +.Sh Acknowledgements +If you have contributed to GAS and your name isn't listed here, it is not +meant as a slight. We just don't know about it. Send mail to the maintainer, +and we'll correct the situation. Currently the maintainer is Ken Raeburn (email +address +.Li raeburn@cyGNUs.com ) . +.Pp +Dean Elsner wrote the original GNU assembler for the VAX. +.Pp +Jay Fenlason maintained GAS for a while, adding support for GDB-specific debug +information and the 68k series machines, most of the preprocessing pass, and +extensive changes in +.Pa messages.c , +.Pa input-file.c , +.Pa write.c . +.Pp +K. Richard Pixley maintained GAS for a while, adding various enhancements +and many bug fixes, including merging support for several processors, breaking +GAS up to handle multiple object file format back ends (including heavy rewrite, +testing, an integration of the coff and b.out back ends), adding configuration +including heavy testing and verification of cross assemblers and file splits +and renaming, converted GAS to strictly ANSI C including full prototypes, +added support for m680[34]0 and cpu32, did considerable work on i960 including +a COFF port (including considerable amounts of reverse engineering), a SPARC +opcode file rewrite, DECstation, rs6000, and hp300hpux host ports, updated +\(lqknow\(rq assertions and made them work, much other reorganization, cleanup, and +lint. +.Pp +Ken Raeburn wrote the high-level BFD interface code to replace most of the +code in format-specific I/O modules. +.Pp +The original VMS support was contributed by David L. Kashtan. Eric Youngdale +has done much work with it since. +.Pp +The Intel 80386 machine description was written by Eliot Dresselhaus. +.Pp +Minh Tran-Le at IntelliCorp contributed some AIX 386 support. +.Pp +The Motorola 88k machine description was contributed by Devon Bowen of Buffalo +University and Torbjorn Granlund of the Swedish Institute of Computer Science. +.Pp +Keith Knowles at the Open Software Foundation wrote the original MIPS back +end ( +.Pa tc-mips.c , +.Pa tc-mips.h ) , +and contributed Rose format support (which hasn't been merged in yet). Ralph +Campbell worked with the MIPS code to support a.out format. +.Pp +Support for the Zilog Z8k and Renesas H8/300 processors (tc-z8k, tc-h8300), +and IEEE 695 object file format (obj-ieee), was written by Steve Chamberlain +of CyGNUs Support. Steve also modified the COFF back end to use BFD for some +low-level operations, for use with the H8/300 and AMD 29k targets. +.Pp +John Gilmore built the AMD 29000 support, added +.Li .include +support, and simplified the configuration of which versions accept which directives. +He updated the 68k machine description so that Motorola's opcodes always produced +fixed-size instructions (e.g., +.Li jsr ) , +while synthetic instructions remained shrinkable ( +.Li jbsr ) . +John fixed many bugs, including true tested cross-compilation support, and +one bug in relaxation that took a week and required the proverbial one-bit +fix. +.Pp +Ian Lance Taylor of CyGNUs Support merged the Motorola and MIT syntax for +the 68k, completed support for some COFF targets (68k, i386 SVR3, and SCO +Unix), added support for MIPS ECOFF and ELF targets, wrote the initial RS/6000 +and PowerPC assembler, and made a few other minor patches. +.Pp +Steve Chamberlain made GAS able to generate listings. +.Pp +Hewlett-Packard contributed support for the HP9000/300. +.Pp +Jeff Law wrote GAS and BFD support for the native HPPA object format (SOM) +along with a fairly extensive HPPA testsuite (for both SOM and ELF object +formats). This work was supported by both the Center for Software Science +at the University of Utah and CyGNUs Support. +.Pp +Support for ELF format files has been worked on by Mark Eichin of CyGNUs Support +(original, incomplete implementation for SPARC), Pete Hoogenboom and Jeff +Law at the University of Utah (HPPA mainly), Michael Meissner of the Open +Software Foundation (i386 mainly), and Ken Raeburn of CyGNUs Support (sparc, +and some initial 64-bit support). +.Pp +Linas Vepstas added GAS support for the ESA/390 \(lqIBM 370\(rq architecture. +.Pp +Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote GAS and +BFD support for openVMS/Alpha. +.Pp +Timothy Wall, Michael Hayes, and Greg Smart contributed to the various tic* +flavors. +.Pp +David Heine, Sterling Augustine, Bob Wilson and John Ruttenberg from Tensilica, +Inc. added support for Xtensa processors. +.Pp +Several engineers at CyGNUs Support have also provided many small bug fixes +and configuration enhancements. +.Pp +Many others have contributed large or small bugfixes and enhancements. If +you have contributed significant work and are not mentioned on this list, +and want to be, let us know. Some of the history has been lost; we are not +intentionally leaving anyone out. +.Pp +.Sh GNU Free Documentation License +.Bd -filled -offset indent +Copyright (C) 2000, 2003 Free Software Foundation, Inc. 51 Franklin Street, +Fifth Floor, Boston, MA 02110-1301 USA +.Pp +Everyone is permitted to copy and distribute verbatim copies of this license +document, but changing it is not allowed. +.Ed +.Pp +.Bl -enum +.It +PREAMBLE +.Pp +The purpose of this License is to make a manual, textbook, or other written +document \(lqfree\(rq in the sense of freedom: to assure everyone the effective freedom +to copy and redistribute it, with or without modifying it, either commercially +or noncommercially. Secondarily, this License preserves for the author and +publisher a way to get credit for their work, while not being considered responsible +for modifications made by others. +.Pp +This License is a kind of \(lqcopyleft\(rq, which means that derivative works of the +document must themselves be free in the same sense. It complements the GNU +General Public License, which is a copyleft license designed for free software. +.Pp +We have designed this License in order to use it for manuals for free software, +because free software needs free documentation: a free program should come +with manuals providing the same freedoms that the software does. But this +License is not limited to software manuals; it can be used for any textual +work, regardless of subject matter or whether it is published as a printed +book. We recommend this License principally for works whose purpose is instruction +or reference. +.Pp +.It +APPLICABILITY AND DEFINITIONS +.Pp +This License applies to any manual or other work that contains a notice placed +by the copyright holder saying it can be distributed under the terms of this +License. The \(lqDocument\(rq, below, refers to any such manual or work. Any member +of the public is a licensee, and is addressed as \(lqyou.\(rq +.Pp +A \(lqModified Version\(rq of the Document means any work containing the Document +or a portion of it, either copied verbatim, or with modifications and/or translated +into another language. +.Pp +A \(lqSecondary Section\(rq is a named appendix or a front-matter section of the Document +that deals exclusively with the relationship of the publishers or authors +of the Document to the Document's overall subject (or to related matters) +and contains nothing that could fall directly within that overall subject. +(For example, if the Document is in part a textbook of mathematics, a Secondary +Section may not explain any mathematics.) The relationship could be a matter +of historical connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding them. +.Pp +The \(lqInvariant Sections\(rq are certain Secondary Sections whose titles are designated, +as being those of Invariant Sections, in the notice that says that the Document +is released under this License. +.Pp +The \(lqCover Texts\(rq are certain short passages of text that are listed, as Front-Cover +Texts or Back-Cover Texts, in the notice that says that the Document is released +under this License. +.Pp +A \(lqTransparent\(rq copy of the Document means a machine-readable copy, represented +in a format whose specification is available to the general public, whose +contents can be viewed and edited directly and straightforwardly with generic +text editors or (for images composed of pixels) generic paint programs or +(for drawings) some widely available drawing editor, and that is suitable +for input to text formatters or for automatic translation to a variety of +formats suitable for input to text formatters. A copy made in an otherwise +Transparent file format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is not +\(lqTransparent\(rq is called \(lqOpaque.\(rq +.Pp +Examples of suitable formats for Transparent copies include plain ASCII without +markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly +available DTD, and standard-conforming simple HTML designed for human modification. +Opaque formats include PostScript, PDF, proprietary formats that can be read +and edited only by proprietary word processors, SGML or XML for which the +DTD and/or processing tools are not generally available, and the machine-generated +HTML produced by some word processors for output purposes only. +.Pp +The \(lqTitle Page\(rq means, for a printed book, the title page itself, plus such +following pages as are needed to hold, legibly, the material this License +requires to appear in the title page. For works in formats which do not have +any title page as such, \(lqTitle Page\(rq means the text near the most prominent +appearance of the work's title, preceding the beginning of the body of the +text. +.Pp +.It +VERBATIM COPYING +.Pp +You may copy and distribute the Document in any medium, either commercially +or noncommercially, provided that this License, the copyright notices, and +the license notice saying this License applies to the Document are reproduced +in all copies, and that you add no other conditions whatsoever to those of +this License. You may not use technical measures to obstruct or control the +reading or further copying of the copies you make or distribute. However, +you may accept compensation in exchange for copies. If you distribute a large +enough number of copies you must also follow the conditions in section 3. +.Pp +You may also lend copies, under the same conditions stated above, and you +may publicly display copies. +.Pp +.It +COPYING IN QUANTITY +.Pp +If you publish printed copies of the Document numbering more than 100, and +the Document's license notice requires Cover Texts, you must enclose the copies +in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover +Texts on the front cover, and Back-Cover Texts on the back cover. Both covers +must also clearly and legibly identify you as the publisher of these copies. +The front cover must present the full title with all words of the title equally +prominent and visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve the title +of the Document and satisfy these conditions, can be treated as verbatim copying +in other respects. +.Pp +If the required texts for either cover are too voluminous to fit legibly, +you should put the first ones listed (as many as fit reasonably) on the actual +cover, and continue the rest onto adjacent pages. +.Pp +If you publish or distribute Opaque copies of the Document numbering more +than 100, you must either include a machine-readable Transparent copy along +with each Opaque copy, or state in or with each Opaque copy a publicly-accessible +computer-network location containing a complete Transparent copy of the Document, +free of added material, which the general network-using public has access +to download anonymously at no charge using public-standard network protocols. +If you use the latter option, you must take reasonably prudent steps, when +you begin distribution of Opaque copies in quantity, to ensure that this Transparent +copy will remain thus accessible at the stated location until at least one +year after the last time you distribute an Opaque copy (directly or through +your agents or retailers) of that edition to the public. +.Pp +It is requested, but not required, that you contact the authors of the Document +well before redistributing any large number of copies, to give them a chance +to provide you with an updated version of the Document. +.Pp +.It +MODIFICATIONS +.Pp +You may copy and distribute a Modified Version of the Document under the conditions +of sections 2 and 3 above, provided that you release the Modified Version +under precisely this License, with the Modified Version filling the role of +the Document, thus licensing distribution and modification of the Modified +Version to whoever possesses a copy of it. In addition, you must do these +things in the Modified Version: +.Pp +A. Use in the Title Page (and on the covers, if any) a title distinct from +that of the Document, and from those of previous versions (which should, if +there were any, be listed in the History section of the Document). You may +use the same title as a previous version if the original publisher of that +version gives permission. B. List on the Title Page, as authors, one or more +persons or entities responsible for authorship of the modifications in the +Modified Version, together with at least five of the principal authors of +the Document (all of its principal authors, if it has less than five). C. +State on the Title page the name of the publisher of the Modified Version, +as the publisher. D. Preserve all the copyright notices of the Document. +E. Add an appropriate copyright notice for your modifications adjacent to +the other copyright notices. F. Include, immediately after the copyright +notices, a license notice giving the public permission to use the Modified +Version under the terms of this License, in the form shown in the Addendum +below. G. Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. H. Include +an unaltered copy of this License. I. Preserve the section entitled \(lqHistory\(rq, +and its title, and add to it an item stating at least the title, year, new +authors, and publisher of the Modified Version as given on the Title Page. +If there is no section entitled \(lqHistory\(rq in the Document, create one stating +the title, year, authors, and publisher of the Document as given on its Title +Page, then add an item describing the Modified Version as stated in the previous +sentence. J. Preserve the network location, if any, given in the Document +for public access to a Transparent copy of the Document, and likewise the +network locations given in the Document for previous versions it was based +on. These may be placed in the \(lqHistory\(rq section. You may omit a network location +for a work that was published at least four years before the Document itself, +or if the original publisher of the version it refers to gives permission. +K. In any section entitled \(lqAcknowledgements\(rq or \(lqDedications\(rq, preserve the section's +title, and preserve in the section all the substance and tone of each of the +contributor acknowledgements and/or dedications given therein. L. Preserve +all the Invariant Sections of the Document, unaltered in their text and in +their titles. Section numbers or the equivalent are not considered part of +the section titles. M. Delete any section entitled \(lqEndorsements.\(rq Such a section +may not be included in the Modified Version. N. Do not retitle any existing +section as \(lqEndorsements\(rq or to conflict in title with any Invariant Section. +.Pp +If the Modified Version includes new front-matter sections or appendices that +qualify as Secondary Sections and contain no material copied from the Document, +you may at your option designate some or all of these sections as invariant. +To do this, add their titles to the list of Invariant Sections in the Modified +Version's license notice. These titles must be distinct from any other section +titles. +.Pp +You may add a section entitled \(lqEndorsements\(rq, provided it contains nothing +but endorsements of your Modified Version by various parties--for example, +statements of peer review or that the text has been approved by an organization +as the authoritative definition of a standard. +.Pp +You may add a passage of up to five words as a Front-Cover Text, and a passage +of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts +in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover +Text may be added by (or through arrangements made by) any one entity. If +the Document already includes a cover text for the same cover, previously +added by you or by arrangement made by the same entity you are acting on behalf +of, you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. +.Pp +The author(s) and publisher(s) of the Document do not by this License give +permission to use their names for publicity for or to assert or imply endorsement +of any Modified Version. +.Pp +.It +COMBINING DOCUMENTS +.Pp +You may combine the Document with other documents released under this License, +under the terms defined in section 4 above for modified versions, provided +that you include in the combination all of the Invariant Sections of all of +the original documents, unmodified, and list them all as Invariant Sections +of your combined work in its license notice. +.Pp +The combined work need only contain one copy of this License, and multiple +identical Invariant Sections may be replaced with a single copy. If there +are multiple Invariant Sections with the same name but different contents, +make the title of each such section unique by adding at the end of it, in +parentheses, the name of the original author or publisher of that section +if known, or else a unique number. Make the same adjustment to the section +titles in the list of Invariant Sections in the license notice of the combined +work. +.Pp +In the combination, you must combine any sections entitled \(lqHistory\(rq in the +various original documents, forming one section entitled \(lqHistory\(rq; likewise +combine any sections entitled \(lqAcknowledgements\(rq, and any sections entitled +\(lqDedications.\(rq You must delete all sections entitled \(lqEndorsements.\(rq +.Pp +.It +COLLECTIONS OF DOCUMENTS +.Pp +You may make a collection consisting of the Document and other documents released +under this License, and replace the individual copies of this License in the +various documents with a single copy that is included in the collection, provided +that you follow the rules of this License for verbatim copying of each of +the documents in all other respects. +.Pp +You may extract a single document from such a collection, and distribute it +individually under this License, provided you insert a copy of this License +into the extracted document, and follow this License in all other respects +regarding verbatim copying of that document. +.Pp +.It +AGGREGATION WITH INDEPENDENT WORKS +.Pp +A compilation of the Document or its derivatives with other separate and independent +documents or works, in or on a volume of a storage or distribution medium, +does not as a whole count as a Modified Version of the Document, provided +no compilation copyright is claimed for the compilation. Such a compilation +is called an \(lqaggregate\(rq, and this License does not apply to the other self-contained +works thus compiled with the Document, on account of their being thus compiled, +if they are not themselves derivative works of the Document. +.Pp +If the Cover Text requirement of section 3 is applicable to these copies of +the Document, then if the Document is less than one quarter of the entire +aggregate, the Document's Cover Texts may be placed on covers that surround +only the Document within the aggregate. Otherwise they must appear on covers +around the whole aggregate. +.Pp +.It +TRANSLATION +.Pp +Translation is considered a kind of modification, so you may distribute translations +of the Document under the terms of section 4. Replacing Invariant Sections +with translations requires special permission from their copyright holders, +but you may include translations of some or all Invariant Sections in addition +to the original versions of these Invariant Sections. You may include a translation +of this License provided that you also include the original English version +of this License. In case of a disagreement between the translation and the +original English version of this License, the original English version will +prevail. +.Pp +.It +TERMINATION +.Pp +You may not copy, modify, sublicense, or distribute the Document except as +expressly provided for under this License. Any other attempt to copy, modify, +sublicense or distribute the Document is void, and will automatically terminate +your rights under this License. However, parties who have received copies, +or rights, from you under this License will not have their licenses terminated +so long as such parties remain in full compliance. +.Pp +.It +FUTURE REVISIONS OF THIS LICENSE +.Pp +The Free Software Foundation may publish new, revised versions of the GNU +Free Documentation License from time to time. Such new versions will be similar +in spirit to the present version, but may differ in detail to address new +problems or concerns. See http://www.gnu.org/copyleft/. +.Pp +Each version of the License is given a distinguishing version number. If the +Document specifies that a particular numbered version of this License \(lqor any +later version\(rq applies to it, you have the option of following the terms and +conditions either of that specified version or of any later version that has +been published (not as a draft) by the Free Software Foundation. If the Document +does not specify a version number of this License, you may choose any version +ever published (not as a draft) by the Free Software Foundation. +.Pp +.El +.Ss ADDENDUM: How to use this License for your documents +To use this License in a document you have written, include a copy of the +License in the document and put the following copyright and license notices +just after the title page: +.Pp +.Bd -literal -offset indent + +Copyright (C) year your name. +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 +or any later version published by the Free Software Foundation; +with the Invariant Sections being list their titles, with the +Front-Cover Texts being list, and with the Back-Cover Texts being list. +A copy of the license is included in the section entitled "GNU +Free Documentation License." + +.Ed +.Pp +If you have no Invariant Sections, write \(lqwith no Invariant Sections\(rq instead +of saying which ones are invariant. If you have no Front-Cover Texts, write +\(lqno Front-Cover Texts\(rq instead of \(lqFront-Cover Texts being +.Va list +\(rq; likewise for Back-Cover Texts. +.Pp +If your document contains nontrivial examples of program code, we recommend +releasing these examples in parallel under your choice of free software license, +such as the GNU General Public License, to permit their use in free software. +.Pp +.Sh AS Index diff --git a/contrib/binutils/gas/doc/as.txt b/contrib/binutils/gas/doc/as.txt deleted file mode 100644 index 91334b842db9..000000000000 --- a/contrib/binutils/gas/doc/as.txt +++ /dev/null @@ -1,13924 +0,0 @@ -START-INFO-DIR-ENTRY -* As: (as). The GNU assembler. -* Gas: (as). The GNU assembler. -END-INFO-DIR-ENTRY - -Using as -1 Overview - 1.1 Structure of this Manual - 1.2 The GNU Assembler - 1.3 Object File Formats - 1.4 Command Line - 1.5 Input Files - 1.6 Output (Object) File - 1.7 Error and Warning Messages -2 Command-Line Options - 2.1 Enable Listings: '-a[cdhlns]' - 2.2 '--alternate' - 2.3 '-D' - 2.4 Work Faster: '-f' - 2.5 '.include' Search Path: '-I' PATH - 2.6 Difference Tables: '-K' - 2.7 Include Local Symbols: '-L' - 2.8 Configuring listing output: '--listing' - 2.9 Assemble in MRI Compatibility Mode: '-M' - 2.10 Dependency Tracking: '--MD' - 2.11 Name the Object File: '-o' - 2.12 Join Data and Text Sections: '-R' - 2.13 Display Assembly Statistics: '--statistics' - 2.14 Compatible Output: '--traditional-format' - 2.15 Announce Version: '-v' - 2.16 Control Warnings: '-W', '--warn', '--no-warn', '--fatal-warnings' - 2.17 Generate Object File in Spite of Errors: '-Z' -3 Syntax - 3.1 Preprocessing - 3.2 Whitespace - 3.3 Comments - 3.4 Symbols - 3.5 Statements - 3.6 Constants - 3.6.1 Character Constants - 3.6.1.1 Strings - 3.6.1.2 Characters - 3.6.2 Number Constants - 3.6.2.1 Integers - 3.6.2.2 Bignums - 3.6.2.3 Flonums -4 Sections and Relocation - 4.1 Background - 4.2 Linker Sections - 4.3 Assembler Internal Sections - 4.4 Sub-Sections - 4.5 bss Section -5 Symbols - 5.1 Labels - 5.2 Giving Symbols Other Values - 5.3 Symbol Names - 5.4 The Special Dot Symbol - 5.5 Symbol Attributes - 5.5.1 Value - 5.5.2 Type -6 Expressions - 6.1 Empty Expressions - 6.2 Integer Expressions - 6.2.1 Arguments - 6.2.2 Operators - 6.2.3 Prefix Operator - 6.2.4 Infix Operators -7 Assembler Directives - 7.1 '.abort' - 7.2 '.align ABS-EXPR, ABS-EXPR, ABS-EXPR' - 7.3 '.ascii "STRING"'... - 7.4 '.asciz "STRING"'... - 7.5 '.balign[wl] ABS-EXPR, ABS-EXPR, ABS-EXPR' - 7.6 '.byte EXPRESSIONS' - 7.7 '.comm SYMBOL , LENGTH ' - 7.8 '.cfi_startproc [simple]' - 7.9 '.cfi_endproc' - 7.10 '.cfi_personality ENCODING [, EXP]' - 7.11 '.cfi_lsda ENCODING [, EXP]' - 7.12 '.cfi_def_cfa REGISTER, OFFSET' - 7.13 '.cfi_def_cfa_register REGISTER' - 7.14 '.cfi_def_cfa_offset OFFSET' - 7.15 '.cfi_adjust_cfa_offset OFFSET' - 7.16 '.cfi_offset REGISTER, OFFSET' - 7.17 '.cfi_rel_offset REGISTER, OFFSET' - 7.18 '.cfi_register REGISTER1, REGISTER2' - 7.19 '.cfi_restore REGISTER' - 7.20 '.cfi_undefined REGISTER' - 7.21 '.cfi_same_value REGISTER' - 7.22 '.cfi_remember_state', - 7.23 '.cfi_return_column REGISTER' - 7.24 '.cfi_signal_frame' - 7.25 '.cfi_window_save' - 7.26 '.cfi_escape' EXPRESSION[, ...] - 7.27 '.file FILENO FILENAME' - 7.28 '.loc FILENO LINENO [COLUMN] [OPTIONS]' - 7.29 '.loc_mark_blocks ENABLE' - 7.30 '.data SUBSECTION' - 7.31 '.double FLONUMS' - 7.32 '.eject' - 7.33 '.else' - 7.34 '.elseif' - 7.35 '.end' - 7.36 '.endfunc' - 7.37 '.endif' - 7.38 '.equ SYMBOL, EXPRESSION' - 7.39 '.equiv SYMBOL, EXPRESSION' - 7.40 '.eqv SYMBOL, EXPRESSION' - 7.41 '.err' - 7.42 '.error "STRING"' - 7.43 '.exitm' - 7.44 '.extern' - 7.45 '.fail EXPRESSION' - 7.46 '.file STRING' - 7.47 '.fill REPEAT , SIZE , VALUE' - 7.48 '.float FLONUMS' - 7.49 '.func NAME[,LABEL]' - 7.50 '.global SYMBOL', '.globl SYMBOL' - 7.51 '.hidden NAMES' - 7.52 '.hword EXPRESSIONS' - 7.53 '.ident' - 7.54 '.if ABSOLUTE EXPRESSION' - 7.55 '.incbin "FILE"[,SKIP[,COUNT]]' - 7.56 '.include "FILE"' - 7.57 '.int EXPRESSIONS' - 7.58 '.internal NAMES' - 7.59 '.irp SYMBOL,VALUES'... - 7.60 '.irpc SYMBOL,VALUES'... - 7.61 '.lcomm SYMBOL , LENGTH' - 7.62 '.lflags' - 7.63 '.line LINE-NUMBER' - 7.64 '.linkonce [TYPE]' - 7.65 '.ln LINE-NUMBER' - 7.66 '.mri VAL' - 7.67 '.list' - 7.68 '.long EXPRESSIONS' - 7.69 '.macro' - 7.70 '.altmacro' - 7.71 '.noaltmacro' - 7.72 '.nolist' - 7.73 '.octa BIGNUMS' - 7.74 '.org NEW-LC , FILL' - 7.75 '.p2align[wl] ABS-EXPR, ABS-EXPR, ABS-EXPR' - 7.76 '.previous' - 7.77 '.popsection' - 7.78 '.print STRING' - 7.79 '.protected NAMES' - 7.80 '.psize LINES , COLUMNS' - 7.81 '.purgem NAME' - 7.82 '.pushsection NAME , SUBSECTION' - 7.83 '.quad BIGNUMS' - 7.84 '.reloc OFFSET, RELOC_NAME[, EXPRESSION]' - 7.85 '.rept COUNT' - 7.86 '.sbttl "SUBHEADING"' - 7.87 '.section NAME' - 7.88 '.set SYMBOL, EXPRESSION' - 7.89 '.short EXPRESSIONS' - 7.90 '.single FLONUMS' - 7.91 '.size' - 7.92 '.sleb128 EXPRESSIONS' - 7.93 '.skip SIZE , FILL' - 7.94 '.space SIZE , FILL' - 7.95 '.stabd, .stabn, .stabs' - 7.96 '.string' "STR" - 7.97 '.struct EXPRESSION' - 7.98 '.subsection NAME' - 7.99 '.symver' - 7.100 '.text SUBSECTION' - 7.101 '.title "HEADING"' - 7.102 '.type' - 7.103 '.uleb128 EXPRESSIONS' - 7.104 '.version "STRING"' - 7.105 '.vtable_entry TABLE, OFFSET' - 7.106 '.vtable_inherit CHILD, PARENT' - 7.107 '.warning "STRING"' - 7.108 '.weak NAMES' - 7.109 '.weakref ALIAS, TARGET' - 7.110 '.word EXPRESSIONS' - 7.111 Deprecated Directives -8 ARM Dependent Features - 8.1 Options - 8.2 Syntax - 8.2.1 Special Characters - 8.2.2 Register Names - 8.2.3 ARM relocation generation - 8.3 Floating Point - 8.4 ARM Machine Directives - 8.5 Opcodes - 8.6 Mapping Symbols -9 80386 Dependent Features - 9.1 Options - 9.2 AT&T Syntax versus Intel Syntax - 9.3 Instruction Naming - 9.4 Register Naming - 9.5 Instruction Prefixes - 9.6 Memory References - 9.7 Handling of Jump Instructions - 9.8 Floating Point - 9.9 Intel's MMX and AMD's 3DNow! SIMD Operations - 9.10 Writing 16-bit Code - 9.11 AT&T Syntax bugs - 9.12 Specifying CPU Architecture - 9.13 Notes -10 IA-64 Dependent Features - 10.1 Options - 10.2 Syntax - 10.2.1 Special Characters - 10.2.2 Register Names - 10.2.3 IA-64 Processor-Status-Register (PSR) Bit Names - 10.3 Opcodes -11 MIPS Dependent Features - 11.1 Assembler options - 11.2 MIPS ECOFF object code - 11.3 Directives for debugging information - 11.4 Directives to override the size of symbols - 11.5 Directives to override the ISA level - 11.6 Directives for extending MIPS 16 bit instructions - 11.7 Directive to mark data as an instruction - 11.8 Directives to save and restore options - 11.9 Directives to control generation of MIPS ASE instructions -12 PowerPC Dependent Features - 12.1 Options - 12.2 PowerPC Assembler Directives -13 SPARC Dependent Features - 13.1 Options - 13.2 Enforcing aligned data - 13.3 Floating Point - 13.4 Sparc Machine Directives -14 Reporting Bugs - 14.1 Have You Found a Bug? - 14.2 How to Report Bugs -15 Acknowledgements -Appendix A GNU Free Documentation License - ADDENDUM: How to use this License for your documents -AS Index -Using as -******** - -This file is a user guide to the GNU assembler 'as' version "2.17.50 -[FreeBSD] 2007-07-03". This version of the file describes 'as' -configured to generate code for machine specific architectures. - - 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". - -1 Overview -********** - -Here is a brief summary of how to invoke 'as'. For details, see *note -Command-Line Options: Invoking. - - 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] - - - -'@FILE' - Read command-line options from FILE. The options read are inserted - in place of the original @FILE option. If FILE does not exist, or - cannot be read, then the option will be treated literally, and not - removed. - - Options in 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 FILE may itself contain additional - @FILE options; any such options will be processed recursively. - -'-a[cdhlmns]' - Turn on listings, in any of a variety of ways: - - '-ac' - omit false conditionals - - '-ad' - omit debugging directives - - '-ah' - include high-level source - - '-al' - include assembly - - '-am' - include macro expansions - - '-an' - omit forms processing - - '-as' - include symbols - - '=file' - set the name of the listing file - - You may combine these options; for example, use '-aln' for assembly - listing without forms processing. The '=file' option, if used, - must be the last one. By itself, '-a' defaults to '-ahls'. - -'--alternate' - Begin in alternate macro mode. *Note '.altmacro': Altmacro. - -'-D' - Ignored. This option is accepted for script compatibility with - calls to other assemblers. - -'--defsym SYM=VALUE' - Define the symbol SYM to be VALUE before assembling the input file. - VALUE must be an integer constant. As in C, a leading '0x' - indicates a hexadecimal value, and a leading '0' indicates an octal - value. The value of the symbol can be overridden inside a source - file via the use of a '.set' pseudo-op. - -'-f' - "fast"--skip whitespace and comment preprocessing (assume source is - compiler output). - -'-g' -'--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. - -'--gstabs' - Generate stabs debugging information for each assembler line. This - may help debugging assembler code, if the debugger can handle 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. - -'--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. - -'--help' - Print a summary of the command line options and exit. - -'--target-help' - Print a summary of all target specific options and exit. - -'-I DIR' - Add directory DIR to the search list for '.include' directives. - -'-J' - Don't warn about signed overflow. - -'-K' - This option is accepted but has no effect on the machine specific - family. - -'-L' -'--keep-locals' - Keep (in the symbol table) local symbols. These symbols start with - system-specific local label prefixes, typically '.L' for ELF - systems or 'L' for traditional a.out systems. *Note Symbol - Names::. - -'--listing-lhs-width=NUMBER' - Set the maximum width, in words, of the output data column for an - assembler listing to NUMBER. - -'--listing-lhs-width2=NUMBER' - Set the maximum width, in words, of the output data column for - continuation lines in an assembler listing to NUMBER. - -'--listing-rhs-width=NUMBER' - Set the maximum width of an input source line, as displayed in a - listing, to NUMBER bytes. - -'--listing-cont-lines=NUMBER' - Set the maximum number of lines printed in a listing for a single - line of input to NUMBER + 1. - -'-o OBJFILE' - Name the object-file output from 'as' OBJFILE. - -'-R' - Fold the data section into the text section. - - Set the default size of GAS's hash tables to a prime number close - to 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. - -'--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 '--hash-size=4051', but in the future it may have other - effects as well. - -'--statistics' - Print the maximum space (in bytes) and total time (in seconds) used - by assembly. - -'--strip-local-absolute' - Remove local absolute symbols from the outgoing symbol table. - -'-v' -'-version' - Print the 'as' version. - -'--version' - Print the 'as' version and exit. - -'-W' -'--no-warn' - Suppress warning messages. - -'--fatal-warnings' - Treat warnings as errors. - -'--warn' - Don't suppress warning messages or treat them as errors. - -'-w' - Ignored. - -'-x' - Ignored. - -'-Z' - Generate an object file even after errors. - -'-- | FILES ...' - Standard input, or source files to assemble. - - The following options are available when as is configured for the ARM -processor family. - -'-mcpu=PROCESSOR[+EXTENSION...]' - Specify which ARM processor variant is the target. -'-march=ARCHITECTURE[+EXTENSION...]' - Specify which ARM architecture variant is used by the target. -'-mfpu=FLOATING-POINT-FORMAT' - Select which Floating Point architecture is the target. -'-mfloat-abi=ABI' - Select which floating point ABI is in use. -'-mthumb' - Enable Thumb only instruction decoding. -'-mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant' - Select which procedure calling convention is in use. -'-EB | -EL' - Select either big-endian (-EB) or little-endian (-EL) output. -'-mthumb-interwork' - Specify that the code has been generated with interworking between - Thumb and ARM code in mind. -'-k' - Specify that PIC code has been generated. - - The following options are available when 'as' is configured for the -SPARC architecture: - -'-Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite' -'-Av8plus | -Av8plusa | -Av9 | -Av9a' - Explicitly select a variant of the SPARC architecture. - - '-Av8plus' and '-Av8plusa' select a 32 bit environment. '-Av9' and - '-Av9a' select a 64 bit environment. - - '-Av8plusa' and '-Av9a' enable the SPARC V9 instruction set with - UltraSPARC extensions. - -'-xarch=v8plus | -xarch=v8plusa' - For compatibility with the Solaris v9 assembler. These options are - equivalent to -Av8plus and -Av8plusa, respectively. - -'-bump' - Warn when the assembler switches to another architecture. - - The following options are available when as is configured for a MIPS -processor. - -'-G NUM' - This option sets the largest size of an object that can be - referenced implicitly with the 'gp' register. It is only accepted - for targets that use ECOFF format, such as a DECstation running - Ultrix. The default value is 8. - -'-EB' - Generate "big endian" format output. - -'-EL' - Generate "little endian" format output. - -'-mips1' -'-mips2' -'-mips3' -'-mips4' -'-mips5' -'-mips32' -'-mips32r2' -'-mips64' -'-mips64r2' - Generate code for a particular MIPS Instruction Set Architecture - level. '-mips1' is an alias for '-march=r3000', '-mips2' is an - alias for '-march=r6000', '-mips3' is an alias for '-march=r4000' - and '-mips4' is an alias for '-march=r8000'. '-mips5', '-mips32', - '-mips32r2', '-mips64', and '-mips64r2' correspond to generic 'MIPS - V', 'MIPS32', 'MIPS32 Release 2', 'MIPS64', and 'MIPS64 Release 2' - ISA processors, respectively. - -'-march=CPU' - Generate code for a particular MIPS cpu. - -'-mtune=CPU' - Schedule and tune for a particular MIPS cpu. - -'-mfix7000' -'-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. - -'-mdebug' -'-no-mdebug' - Cause stabs-style debugging output to go into an ECOFF-style - .mdebug section instead of the standard ELF .stabs sections. - -'-mpdr' -'-mno-pdr' - Control generation of '.pdr' sections. - -'-mgp32' -'-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. '-mgp32' controls the size of - general-purpose registers and '-mfp32' controls the size of - floating-point registers. - -'-mips16' -'-no-mips16' - Generate code for the MIPS 16 processor. This is equivalent to - putting '.set mips16' at the start of the assembly file. - '-no-mips16' turns off this option. - -'-msmartmips' -'-mno-smartmips' - Enables the SmartMIPS extension to the MIPS32 instruction set. - This is equivalent to putting '.set smartmips' at the start of the - assembly file. '-mno-smartmips' turns off this option. - -'-mips3d' -'-no-mips3d' - Generate code for the MIPS-3D Application Specific Extension. This - tells the assembler to accept MIPS-3D instructions. '-no-mips3d' - turns off this option. - -'-mdmx' -'-no-mdmx' - Generate code for the MDMX Application Specific Extension. This - tells the assembler to accept MDMX instructions. '-no-mdmx' turns - off this option. - -'-mdsp' -'-mno-dsp' - Generate code for the DSP Release 1 Application Specific Extension. - This tells the assembler to accept DSP Release 1 instructions. - '-mno-dsp' turns off this option. - -'-mdspr2' -'-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. '-mno-dspr2' turns off this option. - -'-mmt' -'-mno-mt' - Generate code for the MT Application Specific Extension. This - tells the assembler to accept MT instructions. '-mno-mt' turns off - this option. - -'--construct-floats' -'--no-construct-floats' - The '--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 '--construct-floats' - is selected, allowing construction of these floating point - constants. - -'--emulation=NAME' - This option causes 'as' to emulate '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: - 'mipsecoff', 'mipself', 'mipslecoff', 'mipsbecoff', 'mipslelf', - '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 'b' or 'l' in the name. Using '-EB' or '-EL' will override - the endianness selection in any case. - - This option is currently supported only when the primary target - 'as' is configured for is a MIPS ELF or ECOFF target. Furthermore, - the primary target or others specified with '--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. - - Eventually, this option will support more configurations, with more - fine-grained control over the assembler's behavior, and will be - supported for more processors. - -'-nocpp' - 'as' ignores this option. It is accepted for compatibility with - the native tools. - -'--trap' -'--no-trap' -'--break' -'--no-break' - Control how to deal with multiplication overflow and division by - zero. '--trap' or '--no-break' (which are synonyms) take a trap - exception (and only work for Instruction Set Architecture level 2 - and higher); '--break' or '--no-trap' (also synonyms, and the - default) take a break exception. - -'-n' - When this option is used, 'as' will issue a warning every time it - generates a nop instruction from a macro. - -1.1 Structure of this Manual -============================ - -This manual is intended to describe what you need to know to use GNU -'as'. We cover the syntax expected in source files, including notation -for symbols, constants, and expressions; the directives that 'as' -understands; and of course how to invoke 'as'. - - We also cover special features in the machine specific configuration -of 'as', including assembler directives. - - On the other hand, this manual is _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 _not_ describe the instruction set, standard -mnemonics, registers or addressing modes that are standard to a -particular architecture. - -1.2 The GNU Assembler -===================== - -GNU 'as' is really a family of assemblers. This manual describes '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 "pseudo-ops") and assembler syntax. - - 'as' is primarily intended to assemble the output of the GNU C -compiler 'gcc' for use by the linker 'ld'. Nevertheless, we've tried to -make 'as' assemble correctly everything that other assemblers for the -same machine would assemble. - - Unlike older assemblers, 'as' is designed to assemble a source -program in one pass of the source file. This has a subtle impact on the -'.org' directive (*note '.org': Org.). - -1.3 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. *Note Symbol -Attributes: Symbol Attributes. For the machine specific target, 'as' is -configured to produce ELF format object files. - -1.4 Command Line -================ - -After the program name '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. - - '--' (two hyphens) by itself names the standard input file -explicitly, as one of the files for 'as' to assemble. - - Except for '--' any command line argument that begins with a hyphen -('-') is an option. Each option changes the behavior of 'as'. No -option changes the way another option works. An option is a '-' -followed by one or more letters; the case of the letter is important. -All options are optional. - - 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: - - as -o my-object-file.o mumble.s - as -omy-object-file.o mumble.s - -1.5 Input Files -=============== - -We use the phrase "source program", abbreviated "source", to describe -the program input to one run of '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. - - The source program is a concatenation of the text in all the files, -in the order specified. - - Each time you run '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.) - - You give '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. - - If you give 'as' no file names it attempts to read one input file -from the 'as' standard input, which is normally your terminal. You may -have to type <ctl-D> to tell 'as' there is no more program to assemble. - - Use '--' if you need to explicitly name the standard input file in -your command line. - - If the source is empty, 'as' produces a small, empty object file. - -Filenames and Line-numbers --------------------------- - -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 -"logical" file. *Note Error and Warning Messages: Errors. - - "Physical files" are those files named in the command line given to -'as'. - - "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 'as' source -is itself synthesized from other files. 'as' understands the '#' -directives emitted by the 'gcc' preprocessor. See also *note '.file': -File. - -1.6 Output (Object) File -======================== - -Every time you run '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 'a.out'. You can give it another name -by using the '-o' option. Conventionally, object file names end with -'.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 'a.out' format.) - - The object file is meant for input to the linker 'ld'. It contains -assembled program code, information to help 'ld' integrate the assembled -program into a runnable file, and (optionally) symbolic information for -the debugger. - -1.7 Error and Warning Messages -============================== - -'as' may write warnings and error messages to the standard error file -(usually your terminal). This should not happen when a compiler runs -'as' automatically. Warnings report an assumption made so that 'as' -could keep assembling a flawed program; errors report a grave problem -that stops the assembly. - - Warning messages have the format - - file_name:NNN:Warning Message Text - -(where NNN is a line number). If a logical file name has been given -(*note '.file': 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). - - Error messages have the format - file_name:NNN:FATAL:Error Message Text - 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. - -2 Command-Line Options -********************** - -This chapter describes command-line options available in _all_ versions -of the GNU assembler; see *note Machine Dependencies::, for options -specific to the machine specific target. - - If you are invoking 'as' via the GNU C compiler, you can use the -'-Wa' option to pass arguments through to the assembler. The assembler -arguments must be separated from each other (and the '-Wa') by commas. -For example: - - gcc -c -g -O -Wa,-alh,-L file.c - -This passes two options to the assembler: '-alh' (emit a listing to -standard output with high-level and assembly source) and '-L' (retain -local symbols in the symbol table). - - Usually you do not need to use this '-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 '-v' -option to see precisely what options it passes to each compilation pass, -including the assembler.) - -2.1 Enable Listings: '-a[cdhlns]' -================================= - -These options enable listing output from the assembler. By itself, '-a' -requests high-level, assembly, and symbols listing. You can use other -letters to select specific options for the list: '-ah' requests a -high-level language listing, '-al' requests an output-program assembly -listing, and '-as' requests a symbol table listing. High-level listings -require that a compiler debugging option like '-g' be used, and that -assembly listings ('-al') be requested also. - - Use the '-ac' option to omit false conditionals from a listing. Any -lines which are not assembled because of a false '.if' (or '.ifdef', or -any other conditional), or a true '.if' followed by an '.else', will be -omitted from the listing. - - Use the '-ad' option to omit debugging directives from the listing. - - Once you have specified one of these options, you can further control -listing output and its appearance using the directives '.list', -'.nolist', '.psize', '.eject', '.title', and '.sbttl'. The '-an' option -turns off all forms processing. If you do not request listing output -with one of the '-a' options, the listing-control directives have no -effect. - - The letters after '-a' may be combined into one option, _e.g._, -'-aln'. - - Note if the assembler source is coming from the standard input (e.g., -because it is being created by 'gcc' and the '-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. - -2.2 '--alternate' -================= - -Begin in alternate macro mode, see *note '.altmacro': Altmacro. - -2.3 '-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 'as'. - -2.4 Work Faster: '-f' -===================== - -'-f' should only be used when assembling programs written by a (trusted) -compiler. '-f' stops the assembler from doing whitespace and comment -preprocessing on the input file(s) before assembling them. *Note -Preprocessing: Preprocessing. - - _Warning:_ if you use '-f' when the files actually need to be - preprocessed (if they contain comments, for example), 'as' does not - work correctly. - -2.5 '.include' Search Path: '-I' PATH -===================================== - -Use this option to add a PATH to the list of directories 'as' searches -for files specified in '.include' directives (*note '.include': -Include.). You may use '-I' as many times as necessary to include a -variety of paths. The current working directory is always searched -first; after that, 'as' searches any '-I' directories in the same order -as they were specified (left to right) on the command line. - -2.6 Difference Tables: '-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 '.word' directives in difference tables. -The machine specific family does not have the addressing limitations -that sometimes lead to this alteration on other platforms. - -2.7 Include Local Symbols: '-L' -=============================== - -Symbols beginning with system-specific local label prefixes, typically -'.L' for ELF systems or 'L' for traditional a.out systems, are called -"local symbols". *Note 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 'as' and 'ld' discard such symbols, so you do not -normally debug with them. - - This option tells 'as' to retain those local symbols in the object -file. Usually if you do this you also tell the linker 'ld' to preserve -those symbols. - -2.8 Configuring listing output: '--listing' -=========================================== - -The listing feature of the assembler can be enabled via the command line -switch '-a' (*note 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., -'.list' (*note List::), '.title' (*note Title::), '.sbttl' (*note -Sbttl::), '.psize' (*note Psize::), and '.eject' (*note Eject::) and -also by the following switches: - -'--listing-lhs-width='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. - -'--listing-lhs-width2='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 - '--listing-lhs-width'. If neither switch is used the default is to - one. - -'--listing-rhs-width='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. - -'--listing-cont-lines='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. - -2.9 Assemble in MRI Compatibility Mode: '-M' -============================================ - -The '-M' or '--mri' option selects MRI compatibility mode. This changes -the syntax and pseudo-op handling of 'as' to make it compatible with the -'ASM68K' or the '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 'as'. - - 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: - - * global symbols in common section - - The m68k MRI assembler supports common sections which are merged by - the linker. Other object file formats do not support this. '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. - - * complex relocations - - 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. - - * 'END' pseudo-op specifying start address - - The MRI '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 '-e' option to the - linker, or in a linker script. - - * 'IDNT', '.ident' and 'NAME' pseudo-ops - - The MRI 'IDNT', '.ident' and 'NAME' pseudo-ops assign a module name - to the output file. This is not supported by other object file - formats. - - * 'ORG' pseudo-op - - The m68k MRI 'ORG' pseudo-op begins an absolute section at a given - address. This differs from the usual 'as' '.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. - - There are some other features of the MRI assembler which are not -supported by 'as', typically either because they are difficult or -because they seem of little consequence. Some of these may be supported -in future releases. - - * EBCDIC strings - - EBCDIC strings are not supported. - - * packed binary coded decimal - - Packed binary coded decimal is not supported. This means that the - 'DC.P' and 'DCB.P' pseudo-ops are not supported. - - * 'FEQU' pseudo-op - - The m68k 'FEQU' pseudo-op is not supported. - - * 'NOOBJ' pseudo-op - - The m68k 'NOOBJ' pseudo-op is not supported. - - * 'OPT' branch control options - - The m68k 'OPT' branch control options--'B', 'BRS', 'BRB', 'BRL', - and 'BRW'--are ignored. 'as' automatically relaxes all branches, - whether forward or backward, to an appropriate size, so these - options serve no purpose. - - * 'OPT' list control options - - The following m68k 'OPT' list control options are ignored: 'C', - 'CEX', 'CL', 'CRE', 'E', 'G', 'I', 'M', 'MEX', 'MC', 'MD', 'X'. - - * other 'OPT' options - - The following m68k 'OPT' options are ignored: 'NEST', 'O', 'OLD', - 'OP', 'P', 'PCO', 'PCR', 'PCS', 'R'. - - * 'OPT' 'D' option is default - - The m68k 'OPT' 'D' option is the default, unlike the MRI assembler. - 'OPT NOD' may be used to turn it off. - - * 'XREF' pseudo-op. - - The m68k 'XREF' pseudo-op is ignored. - - * '.debug' pseudo-op - - The i960 '.debug' pseudo-op is not supported. - - * '.extended' pseudo-op - - The i960 '.extended' pseudo-op is not supported. - - * '.list' pseudo-op. - - The various options of the i960 '.list' pseudo-op are not - supported. - - * '.optimize' pseudo-op - - The i960 '.optimize' pseudo-op is not supported. - - * '.output' pseudo-op - - The i960 '.output' pseudo-op is not supported. - - * '.setreal' pseudo-op - - The i960 '.setreal' pseudo-op is not supported. - -2.10 Dependency Tracking: '--MD' -================================ - -'as' can generate a dependency file for the file it creates. This file -consists of a single rule suitable for 'make' describing the -dependencies of the main source file. - - The rule is written to the file named in its argument. - - This feature is used in the automatic updating of makefiles. - -2.11 Name the Object File: '-o' -=============================== - -There is always one object file output when you run 'as'. By default it -has the name 'a.out'. You use this option (which takes exactly one -filename) to give the object file a different name. - - Whatever the object file is called, 'as' overwrites any existing file -of the same name. - -2.12 Join Data and Text Sections: '-R' -====================================== - -'-R' tells '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. (*Note -Sections and Relocation: Sections.) - - When you specify '-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 'as'. In future, '-R' may work this way. - - When 'as' is configured for COFF or ELF output, this option is only -useful if you use sections named '.text' and '.data'. - -2.13 Display Assembly Statistics: '--statistics' -================================================ - -Use '--statistics' to display two statistics about the resources used by -'as': the maximum amount of space allocated during the assembly (in -bytes), and the total execution time taken for the assembly (in CPU -seconds). - -2.14 Compatible Output: '--traditional-format' -============================================== - -For some targets, the output of 'as' is different in some ways from the -output of some existing assembler. This switch requests 'as' to use the -traditional format instead. - - For example, it disables the exception frame optimizations which 'as' -normally does by default on 'gcc' output. - -2.15 Announce Version: '-v' -=========================== - -You can find out what version of as is running by including the option -'-v' (which you can also spell as '-version') on the command line. - -2.16 Control Warnings: '-W', '--warn', '--no-warn', '--fatal-warnings' -====================================================================== - -'as' should never give a warning or error message when assembling -compiler output. But programs written by people often cause 'as' to -give a warning that a particular assumption was made. All such warnings -are directed to the standard error file. - - If you use the '-W' and '--no-warn' options, no warnings are issued. -This only affects the warning messages: it does not change any -particular of how 'as' assembles your file. Errors, which stop the -assembly, are still reported. - - If you use the '--fatal-warnings' option, 'as' considers files that -generate warnings to be in error. - - You can switch these options off again by specifying '--warn', which -causes warnings to be output as usual. - -2.17 Generate Object File in Spite of Errors: '-Z' -================================================== - -After an error message, 'as' normally produces no output. If for some -reason you are interested in object file output even after 'as' gives an -error message on your program, use the '-Z' option. If there are any -errors, 'as' continues anyways, and writes an object file after a final -warning message of the form 'N errors, M warnings, generating bad object -file.' - -3 Syntax -******** - -This chapter describes the machine-independent syntax allowed in a -source file. 'as' syntax is similar to what many other assemblers use; -it is inspired by the BSD 4.2 assembler. - -3.1 Preprocessing -================= - -The 'as' internal preprocessor: - * 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. - - * removes all comments, replacing them with a single space, or an - appropriate number of newlines. - - * converts character constants into the appropriate numeric values. - - 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 '.include' directive (*note '.include': -Include.). You can use the GNU C compiler driver to get other "CPP" -style preprocessing by giving the input file a '.S' suffix. *Note -Options Controlling the Kind of Output: (gcc.info)Overall Options. - - Excess whitespace, comments, and character constants cannot be used -in the portions of the input text that are not preprocessed. - - If the first line of an input file is '#NO_APP' or if you use the -'-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 '#APP' -before the text that may contain whitespace or comments, and putting a -line that says '#NO_APP' after this text. This feature is mainly intend -to support 'asm' statements in compilers whose output is otherwise free -of comments and whitespace. - -3.2 Whitespace -============== - -"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 (*note Character Constants: -Characters.), any whitespace means the same as exactly one space. - -3.3 Comments -============ - -There are two ways of rendering comments to 'as'. In both cases the -comment is equivalent to one space. - - Anything from '/*' through the next '*/' is a comment. This means -you may not nest these comments. - - /* - The only way to include a newline ('\n') in a comment - is to use this sort of comment. - */ - - /* This sort of comment does not nest. */ - - Anything from the "line comment" character to the next newline is -considered a comment and is ignored. The line comment character is '@' -on the ARM; '#' on the i386 and x86-64; '#' for Motorola PowerPC; '!' on -the SPARC; see *note Machine Dependencies::. - - To be compatible with past assemblers, lines that begin with '#' have -a special interpretation. Following the '#' should be an absolute -expression (*note Expressions::): the logical line number of the _next_ -line. Then a string (*note Strings: Strings.) is allowed: if present it -is a new logical file name. The rest of the line, if any, should be -whitespace. - - If the first non-whitespace characters on the line are not numeric, -the line is ignored. (Just like a comment.) - - # This is an ordinary comment. - # 42-6 "new_file_name" # New logical file name - # This is logical line # 36. - This feature is deprecated, and may disappear from future versions of -'as'. - -3.4 Symbols -=========== - -A "symbol" is one or more characters chosen from the set of all letters -(both upper and lower case), digits and the three characters '_.$'. 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). *Note Symbols::. - -3.5 Statements -============== - -A "statement" ends at a newline character ('\n') or at a semicolon -(';'). 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. - - It is an error to end any statement with end-of-file: the last -character of any input file should be a newline. - - An empty statement is allowed, and may include whitespace. It is -ignored. - - 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 '.' 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 "instruction": it -assembles into a machine language instruction. - - A label is a symbol immediately followed by a colon (':'). -Whitespace before a label or after a colon is permitted, but you may not -have whitespace between a label's symbol and its colon. *Note Labels::. - - label: .directive followed by something - another_label: # This is an empty statement. - instruction operand_1, operand_2, ... - -3.6 Constants -============= - -A constant is a number, written so that its value is known by -inspection, without knowing any context. Like this: - .byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value. - .ascii "Ring the bell\7" # A string constant. - .octa 0x123456789abcdef0123456789ABCDEF0 # A bignum. - .float 0f-314159265358979323846264338327\ - 95028841971.693993751E-40 # - pi, a flonum. - -3.6.1 Character Constants -------------------------- - -There are two kinds of character constants. A "character" stands for -one character in one byte and its value may be used in numeric -expressions. String constants (properly called string _literals_) are -potentially many bytes and their values may not be used in arithmetic -expressions. - -3.6.1.1 Strings -............... - -A "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 "escape" these characters: precede them with a -backslash '\' character. For example '\\' represents one backslash: the -first '\' is an escape which tells 'as' to interpret the second -character literally as a backslash (which prevents 'as' from recognizing -the second '\' as an escape character). The complete list of escapes -follows. - -'\b' - Mnemonic for backspace; for ASCII this is octal code 010. - -'\f' - Mnemonic for FormFeed; for ASCII this is octal code 014. - -'\n' - Mnemonic for newline; for ASCII this is octal code 012. - -'\r' - Mnemonic for carriage-Return; for ASCII this is octal code 015. - -'\t' - Mnemonic for horizontal Tab; for ASCII this is octal code 011. - -'\ DIGIT DIGIT 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, '\008' has the value 010, and '\009' the value - 011. - -'\x HEX-DIGITS...' - A hex character code. All trailing hex digits are combined. - Either upper or lower case 'x' works. - -'\\' - Represents one '\' character. - -'\"' - Represents one '"' character. Needed in strings to represent this - character, because an unescaped '"' would end the string. - -'\ ANYTHING-ELSE' - Any other character when escaped by '\' gives a warning, but - assembles as if the '\' 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 'as' has no - other interpretation, so 'as' knows it is giving you the wrong code - and warns you of the fact. - - 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. - -3.6.1.2 Characters -.................. - -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 ''\\' -where the first '\' escapes the second '\'. As you can see, the quote -is an acute accent, not a grave accent. A newline (or semicolon ';') -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. 'as' assumes your character code is ASCII: ''A' means -65, ''B' means 66, and so on. - -3.6.2 Number Constants ----------------------- - -'as' distinguishes three kinds of numbers according to how they are -stored in the target machine. _Integers_ are numbers that would fit -into an 'int' in the C language. _Bignums_ are integers, but they are -stored in more than 32 bits. _Flonums_ are floating point numbers, -described below. - -3.6.2.1 Integers -................ - -A binary integer is '0b' or '0B' followed by zero or more of the binary -digits '01'. - - An octal integer is '0' followed by zero or more of the octal digits -('01234567'). - - A decimal integer starts with a non-zero digit followed by zero or -more digits ('0123456789'). - - A hexadecimal integer is '0x' or '0X' followed by one or more -hexadecimal digits chosen from '0123456789abcdefABCDEF'. - - Integers have the usual values. To denote a negative integer, use -the prefix operator '-' discussed under expressions (*note Prefix -Operators: Prefix Ops.). - -3.6.2.2 Bignums -............... - -A "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. - -3.6.2.3 Flonums -............... - -A "flonum" represents a floating point number. The translation is -indirect: a decimal floating point number from the text is converted by -'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 -'as' specialized to that computer. - - A flonum is written by writing (in order) - * The digit '0'. - - * A letter, to tell 'as' the rest of the number is a flonum. - - * An optional sign: either '+' or '-'. - - * An optional "integer part": zero or more decimal digits. - - * An optional "fractional part": '.' followed by zero or more decimal - digits. - - * An optional exponent, consisting of: - - * An 'E' or 'e'. - * Optional sign: either '+' or '-'. - * One or more decimal digits. - - At least one of the integer part or the fractional part must be -present. The floating point number has the usual base-10 value. - - 'as' does all processing using integers. Flonums are computed -independently of any floating point hardware in the computer running -'as'. - -4 Sections and Relocation -************************* - -4.1 Background -============== - -Roughly, a section is a range of addresses, with no gaps; all data "in" -those addresses is treated the same for some particular purpose. For -example there may be a "read only" section. - - The linker 'ld' reads many object files (partial programs) and -combines their contents to form a runnable program. When 'as' emits an -object file, the partial program is assumed to start at address 0. '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 'as' uses sections. - - '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 _section_. Assigning -run-time addresses to sections is called "relocation". It includes the -task of adjusting mentions of object-file addresses so they refer to the -proper run-time addresses. - - An object file written by 'as' has at least three sections, any of -which may be empty. These are named "text", "data" and "bss" sections. - - 'as' can also generate whatever other named sections you specify -using the '.section' directive (*note '.section': Section.). If you do -not use any directives that place output in the '.text' or '.data' -sections, these sections still exist, but are empty. - - Within the object file, the text section starts at address '0', the -data section follows, and the bss section follows the data section. - - To let 'ld' know which data changes when the sections are relocated, -and how to change that data, 'as' also writes to the object file details -of the relocation needed. To perform relocation 'ld' must know, each -time an address in the object file is mentioned: - * Where in the object file is the beginning of this reference to an - address? - * How long (in bytes) is this reference? - * Which section does the address refer to? What is the numeric value - of - (ADDRESS) - (START-ADDRESS OF SECTION)? - * Is the reference to an address "Program-Counter relative"? - - In fact, every address 'as' ever uses is expressed as - (SECTION) + (OFFSET INTO SECTION) -Further, most expressions 'as' computes have this section-relative -nature. - - In this manual we use the notation {SECNAME N} to mean "offset N into -section SECNAME." - - Apart from text, data and bss sections you need to know about the -"absolute" section. When 'ld' mixes partial programs, addresses in the -absolute section remain unchanged. For example, address '{absolute 0}' -is "relocated" to run-time address 0 by 'ld'. Although the linker never -arranges two partial programs' data sections with overlapping addresses -after linking, _by definition_ their absolute sections must overlap. -Address '{absolute 239}' in one part of a program is always the same -address when the program is running as address '{absolute 239}' in any -other part of the program. - - The idea of sections is extended to the "undefined" section. Any -address whose section is unknown at assembly time is by definition -rendered {undefined U}--where 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 _undefined_. - - By analogy the word _section_ is used to describe groups of sections -in the linked program. 'ld' puts all partial programs' text sections in -contiguous addresses in the linked program. It is customary to refer to -the _text section_ of a program, meaning all the addresses of all -partial programs' text sections. Likewise for data and bss sections. - - Some sections are manipulated by 'ld'; others are invented for use of -'as' and have no meaning except during assembly. - -4.2 Linker Sections -=================== - -'ld' deals with just four kinds of sections, summarized below. - -*named sections* - These sections hold your program. 'as' and '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. - -*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. - -*absolute section* - Address 0 of this section is always "relocated" to runtime address - 0. This is useful if you want to refer to an address that 'ld' - must not change when relocating. In this sense we speak of - absolute addresses being "unrelocatable": they do not change during - relocation. - -*undefined section* - This "section" is a catch-all for address references to objects not - in the preceding sections. - - An idealized example of three relocatable sections follows. The -example uses the traditional section names '.text' and '.data'. Memory -addresses are on the horizontal axis. - - +-----+----+--+ - 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 ... - -4.3 Assembler Internal Sections -=============================== - -These sections are meant only for the internal use of '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 'as' warning -messages, so it might be helpful to have an idea of their meanings to -'as'. These sections are used to permit the value of every expression -in your assembly language program to be a section-relative address. - -ASSEMBLER-INTERNAL-LOGIC-ERROR! - An internal assembler logic error has been found. This means there - is a bug in the assembler. - -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. - -4.4 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. 'as' allows you to use -"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 '.text 0' before each section of code being -output, and a '.text 1' before each group of constants being output. - - Subsections are optional. If you do not use subsections, everything -goes in subsection number zero. - - 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; -'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. - - To specify which subsection you want subsequent statements assembled -into, use a numeric argument to specify it, in a '.text EXPRESSION' or a -'.data EXPRESSION' statement. You can also use the '.subsection' -directive (*note SubSection::) to specify a subsection: '.subsection -EXPRESSION'. EXPRESSION should be an absolute expression (*note -Expressions::). If you just say '.text' then '.text 0' is assumed. -Likewise '.data' means '.data 0'. Assembly begins in 'text 0'. For -instance: - .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 (*)." - - Each section has a "location counter" incremented by one for every -byte assembled into that section. Because subsections are merely a -convenience restricted to 'as' there is no concept of a subsection -location counter. There is no way to directly manipulate a location -counter--but the '.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 "active" location -counter. - -4.5 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. - - The '.lcomm' pseudo-op defines a symbol in the bss section; see *note -'.lcomm': Lcomm. - - The '.comm' pseudo-op may be used to declare a common symbol, which -is another form of uninitialized symbol; see *note '.comm': Comm. - -5 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. - - _Warning:_ 'as' does not place symbols in the object file in the - same order they were declared. This may break some debuggers. - -5.1 Labels -========== - -A "label" is written as a symbol immediately followed by a colon ':'. -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. - -5.2 Giving Symbols Other Values -=============================== - -A symbol can be given an arbitrary value by writing a symbol, followed -by an equals sign '=', followed by an expression (*note Expressions::). -This is equivalent to using the '.set' directive. *Note '.set': Set. -In the same way, using a double equals sign '=''=' here represents an -equivalent of the '.eqv' directive. *Note '.eqv': Eqv. - -5.3 Symbol Names -================ - -Symbol names begin with a letter or with one of '._'. On most machines, -you can also use '$' in symbol names; exceptions are noted in *note -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. - - Case of letters is significant: 'foo' is a different symbol name than -'Foo'. - - 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. - -Local Symbol Names ------------------- - -A local symbol is any symbol beginning with certain local label -prefixes. By default, the local label prefix is '.L' for ELF systems or -'L' for traditional a.out systems, but each target may have its own set -of local label prefixes. - - 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 '-L' option (*note Include Local Symbols: -'-L': L.) to retain the local symbols in the object files. - -Local Labels ------------- - -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 'N:' -(where N represents any positive integer). To refer to the most recent -previous definition of that label write 'Nb', using the same number as -when you defined the label. To refer to the next definition of a local -label, write 'Nf'--the 'b' stands for "backwards" and the 'f' stands for -"forwards". - - 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 '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 ('0:'...'9:') are implemented in a slightly more efficient manner -than the others. - - Here is an example: - - 1: branch 1f - 2: branch 1b - 1: branch 2f - 2: branch 1b - - Which is the equivalent of: - - label_1: branch label_3 - label_2: branch label_1 - label_3: branch label_4 - label_4: branch label_3 - - 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: - -'_local label prefix_' - All local symbols begin with the system-specific local label - prefix. Normally both 'as' and '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 '-L' option then 'as' - retains these symbols in the object file. If you also instruct - 'ld' to retain these symbols, you may use them in debugging. - -'NUMBER' - This is the number that was used in the local label definition. So - if the label is written '55:' then the number is '55'. - -'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 - '\002' (control-B). - -'_ordinal number_' - This is a serial number to keep the labels distinct. The first - definition of '0:' gets the number '1'. The 15th definition of - '0:' gets the number '15', and so on. Likewise the first - definition of '1:' gets the number '1' and its 15th definition gets - '15' as well. - - So for example, the first '1:' may be named '.L1C-B1', and the 44th -'3:' may be named '.L3C-B44'. - -Dollar Local Labels -------------------- - -'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. - - 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., '55$'. - - They can also be distinguished from ordinary local labels by their -transformed names which use ASCII character '\001' (control-A) as the -magic character to distinguish them from ordinary labels. For example, -the fifth definition of '6$' may be named '.L6'C-A'5'. - -5.4 The Special Dot Symbol -========================== - -The special symbol '.' refers to the current address that 'as' is -assembling into. Thus, the expression 'melvin: .long .' defines -'melvin' to contain its own address. Assigning a value to '.' is -treated the same as a '.org' directive. Thus, the expression '.=.+4' is -the same as saying '.space 4'. - -5.5 Symbol Attributes -===================== - -Every symbol has, as well as its name, the attributes "Value" and -"Type". Depending on output format, symbols can also have auxiliary -attributes. The detailed definitions are in 'a.out.h'. - - If you use a symbol without defining it, '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. - -5.5.1 Value ------------ - -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 'ld' changes section base addresses during linking. Absolute -symbols' values do not change during linking: that is why they are -called absolute. - - 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 -'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 '.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. - -5.5.2 Type ----------- - -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. - -6 Expressions -************* - -An "expression" specifies an address or numeric value. Whitespace may -precede and/or follow an expression. - - 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 '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. 'as' aborts with an error message in this situation. - -6.1 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 'as' assumes a value of (absolute) 0. This is -compatible with other assemblers. - -6.2 Integer Expressions -======================= - -An "integer expression" is one or more _arguments_ delimited by -_operators_. - -6.2.1 Arguments ---------------- - -"Arguments" are symbols, numbers or subexpressions. In other contexts -arguments are sometimes called "arithmetic operands". In this manual, -to avoid confusing them with the "instruction operands" of the machine -language, we use the term "argument" to refer to parts of expressions -only, reserving the word "operand" to refer only to machine instruction -operands. - - Symbols are evaluated to yield {SECTION NNN} where SECTION is one of -text, data, bss, absolute, or undefined. NNN is a signed, 2's -complement 32 bit integer. - - Numbers are usually integers. - - A number can be a flonum or bignum. In this case, you are warned -that only the low order 32 bits are used, and 'as' pretends these 32 -bits are an integer. You may write integer-manipulating instructions -that act on exotic constants, compatible with other assemblers. - - Subexpressions are a left parenthesis '(' followed by an integer -expression, followed by a right parenthesis ')'; or a prefix operator -followed by an argument. - -6.2.2 Operators ---------------- - -"Operators" are arithmetic functions, like '+' or '%'. Prefix operators -are followed by an argument. Infix operators appear between their -arguments. Operators may be preceded and/or followed by whitespace. - -6.2.3 Prefix Operator ---------------------- - -'as' has the following "prefix operators". They each take one argument, -which must be absolute. - -'-' - "Negation". Two's complement negation. -'~' - "Complementation". Bitwise not. - -6.2.4 Infix Operators ---------------------- - -"Infix operators" take two arguments, one on either side. Operators -have precedence, but operations with equal precedence are performed left -to right. Apart from '+' or '-', both arguments must be absolute, and -the result is absolute. - - 1. Highest Precedence - - '*' - "Multiplication". - - '/' - "Division". Truncation is the same as the C operator '/' - - '%' - "Remainder". - - '<<' - "Shift Left". Same as the C operator '<<'. - - '>>' - "Shift Right". Same as the C operator '>>'. - - 2. Intermediate precedence - - '|' - - "Bitwise Inclusive Or". - - '&' - "Bitwise And". - - '^' - "Bitwise Exclusive Or". - - '!' - "Bitwise Or Not". - - 3. Low Precedence - - '+' - "Addition". If either argument is absolute, the result has - the section of the other argument. You may not add together - arguments from different sections. - - '-' - "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. - - '==' - "Is Equal To" - '<>' - '!=' - "Is Not Equal To" - '<' - "Is Less Than" - '>' - "Is Greater Than" - '>=' - "Is Greater Than Or Equal To" - '<=' - "Is Less Than Or Equal To" - - 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. - - 4. Lowest Precedence - - '&&' - "Logical And". - - '||' - "Logical Or". - - 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. - - In short, it's only meaningful to add or subtract the _offsets_ in an -address; you can only have a defined section in one of the two -arguments. - -7 Assembler Directives -********************** - -All assembler directives have names that begin with a period ('.'). The -rest of the name is letters, usually in lower case. - - This chapter discusses directives that are available regardless of -the target machine configuration for the GNU assembler. - -7.1 '.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 'as' to quit also. One day -'.abort' will not be supported. - -7.2 '.align ABS-EXPR, ABS-EXPR, 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. - - 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. - - 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. - - 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 '.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. - - 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 '.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. - - This inconsistency is due to the different behaviors of the various -native assemblers for these systems which GAS must emulate. GAS also -provides '.balign' and '.p2align' directives, described later, which -have a consistent behavior across all architectures (but are specific to -GAS). - -7.3 '.ascii "STRING"'... -======================== - -'.ascii' expects zero or more string literals (*note Strings::) -separated by commas. It assembles each string (with no automatic -trailing zero byte) into consecutive addresses. - -7.4 '.asciz "STRING"'... -======================== - -'.asciz' is just like '.ascii', but each string is followed by a zero -byte. The "z" in '.asciz' stands for "zero". - -7.5 '.balign[wl] ABS-EXPR, ABS-EXPR, 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 '.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. - - 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. - - 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. - - The '.balignw' and '.balignl' directives are variants of the -'.balign' directive. The '.balignw' directive treats the fill pattern -as a two byte word value. The '.balignl' directives treats the fill -pattern as a four byte longword value. For example, '.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. - -7.6 '.byte EXPRESSIONS' -======================= - -'.byte' expects zero or more expressions, separated by commas. Each -expression is assembled into the next byte. - -7.7 '.comm SYMBOL , LENGTH ' -============================ - -'.comm' declares a common symbol named 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 'ld' does not see a -definition for the symbol-just one or more common symbols-then it will -allocate LENGTH bytes of uninitialized memory. LENGTH must be an -absolute expression. If '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. - - When using ELF, the '.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 'ld' -allocates uninitialized memory for the common symbol, it will use the -alignment when placing the symbol. If no alignment is specified, '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. - -7.8 '.cfi_startproc [simple]' -============================= - -'.cfi_startproc' is used at the beginning of each function that should -have an entry in '.eh_frame'. It initializes some internal data -structures. Don't forget to close the function by '.cfi_endproc'. - - Unless '.cfi_startproc' is used along with parameter 'simple' it also -emits some architecture dependent initial CFI instructions. - -7.9 '.cfi_endproc' -================== - -'.cfi_endproc' is used at the end of a function where it closes its -unwind entry previously opened by '.cfi_startproc', and emits it to -'.eh_frame'. - -7.10 '.cfi_personality ENCODING [, EXP]' -======================================== - -'.cfi_personality' defines personality routine and its encoding. -ENCODING must be a constant determining how the personality should be -encoded. If it is 255 ('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 '.cfi_startproc' is '.cfi_personality -0xff', no personality routine. - -7.11 '.cfi_lsda ENCODING [, EXP]' -================================= - -'.cfi_lsda' defines LSDA and its encoding. ENCODING must be a constant -determining how the LSDA should be encoded. If it is 255 -('DW_EH_PE_omit'), second argument is not present, otherwise second -argument should be a constant or a symbol name. The default after -'.cfi_startproc' is '.cfi_lsda 0xff', no LSDA. - -7.12 '.cfi_def_cfa REGISTER, OFFSET' -==================================== - -'.cfi_def_cfa' defines a rule for computing CFA as: take address from -REGISTER and add OFFSET to it. - -7.13 '.cfi_def_cfa_register REGISTER' -===================================== - -'.cfi_def_cfa_register' modifies a rule for computing CFA. From now on -REGISTER will be used instead of the old one. Offset remains the same. - -7.14 '.cfi_def_cfa_offset OFFSET' -================================= - -'.cfi_def_cfa_offset' modifies a rule for computing CFA. Register -remains the same, but OFFSET is new. Note that it is the absolute -offset that will be added to a defined register to compute CFA address. - -7.15 '.cfi_adjust_cfa_offset OFFSET' -==================================== - -Same as '.cfi_def_cfa_offset' but OFFSET is a relative value that is -added/substracted from the previous offset. - -7.16 '.cfi_offset REGISTER, OFFSET' -=================================== - -Previous value of REGISTER is saved at offset OFFSET from CFA. - -7.17 '.cfi_rel_offset REGISTER, OFFSET' -======================================= - -Previous value of REGISTER is saved at offset OFFSET from the current -CFA register. This is transformed to '.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. - -7.18 '.cfi_register REGISTER1, REGISTER2' -========================================= - -Previous value of REGISTER1 is saved in register REGISTER2. - -7.19 '.cfi_restore REGISTER' -============================ - -'.cfi_restore' says that the rule for REGISTER is now the same as it was -at the beginning of the function, after all initial instruction added by -'.cfi_startproc' were executed. - -7.20 '.cfi_undefined REGISTER' -============================== - -From now on the previous value of REGISTER can't be restored anymore. - -7.21 '.cfi_same_value REGISTER' -=============================== - -Current value of REGISTER is the same like in the previous frame, i.e. -no restoration needed. - -7.22 '.cfi_remember_state', -=========================== - -First save all current rules for all registers by '.cfi_remember_state', -then totally screw them up by subsequent '.cfi_*' directives and when -everything is hopelessly bad, use '.cfi_restore_state' to restore the -previous saved state. - -7.23 '.cfi_return_column REGISTER' -================================== - -Change return column REGISTER, i.e. the return address is either -directly in REGISTER or can be accessed by rules for REGISTER. - -7.24 '.cfi_signal_frame' -======================== - -Mark current function as signal trampoline. - -7.25 '.cfi_window_save' -======================= - -SPARC register window has been saved. - -7.26 '.cfi_escape' 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. - -7.27 '.file FILENO FILENAME' -============================ - -When emitting dwarf2 line number information '.file' assigns filenames -to the '.debug_line' file name table. The FILENO operand should be a -unique positive integer to use as the index of the entry in the table. -The FILENAME operand is a C string literal. - - The detail of filename indices is exposed to the user because the -filename table is shared with the '.debug_info' section of the dwarf2 -debugging information, and thus the user must know the exact indices -that table entries will have. - -7.28 '.loc FILENO LINENO [COLUMN] [OPTIONS]' -============================================ - -The '.loc' directive will add row to the '.debug_line' line number -matrix corresponding to the immediately following assembly instruction. -The FILENO, LINENO, and optional COLUMN arguments will be applied to the -'.debug_line' state machine before the row is added. - - The OPTIONS are a sequence of the following tokens in any order: - -'basic_block' - This option will set the 'basic_block' register in the - '.debug_line' state machine to 'true'. - -'prologue_end' - This option will set the 'prologue_end' register in the - '.debug_line' state machine to 'true'. - -'epilogue_begin' - This option will set the 'epilogue_begin' register in the - '.debug_line' state machine to 'true'. - -'is_stmt VALUE' - This option will set the 'is_stmt' register in the '.debug_line' - state machine to 'value', which must be either 0 or 1. - -'isa VALUE' - This directive will set the 'isa' register in the '.debug_line' - state machine to VALUE, which must be an unsigned integer. - -7.29 '.loc_mark_blocks ENABLE' -============================== - -The '.loc_mark_blocks' directive makes the assembler emit an entry to -the '.debug_line' line number matrix with the 'basic_block' register in -the state machine set whenever a code label is seen. The ENABLE -argument should be either 1 or 0, to enable or disable this function -respectively. - -7.30 '.data SUBSECTION' -======================= - -'.data' tells 'as' to assemble the following statements onto the end of -the data subsection numbered SUBSECTION (which is an absolute -expression). If SUBSECTION is omitted, it defaults to zero. - -7.31 '.double FLONUMS' -====================== - -'.double' expects zero or more flonums, separated by commas. It -assembles floating point numbers. - -7.32 '.eject' -============= - -Force a page break at this point, when generating assembly listings. - -7.33 '.else' -============ - -'.else' is part of the 'as' support for conditional assembly; see *note -'.if': If. It marks the beginning of a section of code to be assembled -if the condition for the preceding '.if' was false. - -7.34 '.elseif' -============== - -'.elseif' is part of the 'as' support for conditional assembly; see -*note '.if': If. It is shorthand for beginning a new '.if' block that -would otherwise fill the entire '.else' section. - -7.35 '.end' -=========== - -'.end' marks the end of the assembly file. 'as' does not process -anything in the file past the '.end' directive. - -7.36 '.endfunc' -=============== - -'.endfunc' marks the end of a function specified with '.func'. - -7.37 '.endif' -============= - -'.endif' is part of the 'as' support for conditional assembly; it marks -the end of a block of code that is only assembled conditionally. *Note -'.if': If. - -7.38 '.equ SYMBOL, EXPRESSION' -============================== - -This directive sets the value of SYMBOL to EXPRESSION. It is synonymous -with '.set'; see *note '.set': Set. - -7.39 '.equiv SYMBOL, EXPRESSION' -================================ - -The '.equiv' directive is like '.equ' and '.set', except that the -assembler will signal an error if SYMBOL is already defined. Note a -symbol which has been referenced but not actually defined is considered -to be undefined. - - Except for the contents of the error message, this is roughly -equivalent to - .ifdef SYM - .err - .endif - .equ SYM,VAL - plus it protects the symbol from later redefinition. - -7.40 '.eqv SYMBOL, EXPRESSION' -============================== - -The '.eqv' directive is like '.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. - -7.41 '.err' -=========== - -If 'as' assembles a '.err' directive, it will print an error message -and, unless the '-Z' option was used, it will not generate an object -file. This can be used to signal an error in conditionally compiled -code. - -7.42 '.error "STRING"' -====================== - -Similarly to '.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 '".error directive invoked in source -file"'. *Note Error and Warning Messages: Errors. - - .error "This code has not been assembled and tested." - -7.43 '.exitm' -============= - -Exit early from the current macro definition. *Note Macro::. - -7.44 '.extern' -============== - -'.extern' is accepted in the source program--for compatibility with -other assemblers--but it is ignored. 'as' treats all undefined symbols -as external. - -7.45 '.fail EXPRESSION' -======================= - -Generates an error or a warning. If the value of the EXPRESSION is 500 -or more, 'as' will print a warning message. If the value is less than -500, 'as' will print an error message. The message will include the -value of EXPRESSION. This can occasionally be useful inside complex -nested macros or conditional assembly. - -7.46 '.file STRING' -=================== - -'.file' tells 'as' that we are about to start a new logical file. -STRING is the new file name. In general, the filename is recognized -whether or not it is surrounded by quotes '"'; but if you wish to -specify an empty file name, you must give the quotes-'""'. This -statement may go away in future: it is only recognized to be compatible -with old 'as' programs. - -7.47 '.fill REPEAT , SIZE , VALUE' -================================== - -REPEAT, SIZE and VALUE are absolute expressions. This emits REPEAT -copies of SIZE bytes. REPEAT may be zero or more. 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 REPEAT -bytes is taken from an 8-byte number. The highest order 4 bytes are -zero. The lowest order 4 bytes are VALUE rendered in the byte-order of -an integer on the computer 'as' is assembling for. Each SIZE bytes in a -repetition is taken from the lowest order SIZE bytes of this number. -Again, this bizarre behavior is compatible with other people's -assemblers. - - SIZE and VALUE are optional. If the second comma and VALUE are -absent, VALUE is assumed zero. If the first comma and following tokens -are absent, SIZE is assumed to be 1. - -7.48 '.float FLONUMS' -===================== - -This directive assembles zero or more flonums, separated by commas. It -has the same effect as '.single'. - -7.49 '.func NAME[,LABEL]' -========================= - -'.func' emits debugging information to denote function NAME, and is -ignored unless the file is assembled with debugging enabled. Only -'--gstabs[+]' is currently supported. LABEL is the entry point of the -function and if omitted NAME prepended with the 'leading char' is used. -'leading char' is usually '_' or nothing, depending on the target. All -functions are currently defined to have 'void' return type. The -function must be terminated with '.endfunc'. - -7.50 '.global SYMBOL', '.globl SYMBOL' -====================================== - -'.global' makes the symbol visible to 'ld'. If you define SYMBOL in -your partial program, its value is made available to other partial -programs that are linked with it. Otherwise, SYMBOL takes its -attributes from a symbol of the same name from another file linked into -the same program. - - Both spellings ('.globl' and '.global') are accepted, for -compatibility with other assemblers. - -7.51 '.hidden NAMES' -==================== - -This is one of the ELF visibility directives. The other two are -'.internal' (*note '.internal': Internal.) and '.protected' (*note -'.protected': Protected.). - - This directive overrides the named symbols default visibility (which -is set by their binding: local, global or weak). The directive sets the -visibility to 'hidden' which means that the symbols are not visible to -other components. Such symbols are always considered to be 'protected' -as well. - -7.52 '.hword EXPRESSIONS' -========================= - -This expects zero or more EXPRESSIONS, and emits a 16 bit number for -each. - - This directive is a synonym for '.short'. - -7.53 '.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, '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 -'.comment' or '.rdata' section, depending on the target. When using -ELF, comments are emitted to the '.comment' section. - -7.54 '.if ABSOLUTE EXPRESSION' -============================== - -'.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 ABSOLUTE EXPRESSION) is non-zero. The end of the conditional -section of code must be marked by '.endif' (*note '.endif': Endif.); -optionally, you may include code for the alternative condition, flagged -by '.else' (*note '.else': Else.). If you have several conditions to -check, '.elseif' may be used to avoid nesting blocks if/else within each -subsequent '.else' block. - - The following variants of '.if' are also supported: -'.ifdef SYMBOL' - Assembles the following section of code if the specified SYMBOL has - been defined. Note a symbol which has been referenced but not yet - defined is considered to be undefined. - -'.ifb TEXT' - Assembles the following section of code if the operand is blank - (empty). - -'.ifc STRING1,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. - -'.ifeq ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is zero. - -'.ifeqs STRING1,STRING2' - Another form of '.ifc'. The strings must be quoted using double - quotes. - -'.ifge ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is greater - than or equal to zero. - -'.ifgt ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is greater - than zero. - -'.ifle ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is less - than or equal to zero. - -'.iflt ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is less - than zero. - -'.ifnb TEXT' - Like '.ifb', but the sense of the test is reversed: this assembles - the following section of code if the operand is non-blank - (non-empty). - -'.ifnc STRING1,STRING2.' - Like '.ifc', but the sense of the test is reversed: this assembles - the following section of code if the two strings are not the same. - -'.ifndef SYMBOL' -'.ifnotdef SYMBOL' - Assembles the following section of code if the specified 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. - -'.ifne ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is not - equal to zero (in other words, this is equivalent to '.if'). - -'.ifnes STRING1,STRING2' - Like '.ifeqs', but the sense of the test is reversed: this - assembles the following section of code if the two strings are not - the same. - -7.55 '.incbin "FILE"[,SKIP[,COUNT]]' -==================================== - -The 'incbin' directive includes FILE verbatim at the current location. -You can control the search paths used with the '-I' command-line option -(*note Command-Line Options: Invoking.). Quotation marks are required -around FILE. - - The SKIP argument skips a number of bytes from the start of the FILE. -The 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 'incbin' directive. - -7.56 '.include "FILE"' -====================== - -This directive provides a way to include supporting files at specified -points in your source program. The code from FILE is assembled as if it -followed the point of the '.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 '-I' command-line option (*note -Command-Line Options: Invoking.). Quotation marks are required around -FILE. - -7.57 '.int EXPRESSIONS' -======================= - -Expect zero or more 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. - -7.58 '.internal NAMES' -====================== - -This is one of the ELF visibility directives. The other two are -'.hidden' (*note '.hidden': Hidden.) and '.protected' (*note -'.protected': Protected.). - - This directive overrides the named symbols default visibility (which -is set by their binding: local, global or weak). The directive sets the -visibility to 'internal' which means that the symbols are considered to -be 'hidden' (i.e., not visible to other components), and that some -extra, processor specific processing must also be performed upon the -symbols as well. - -7.59 '.irp SYMBOL,VALUES'... -============================ - -Evaluate a sequence of statements assigning different values to SYMBOL. -The sequence of statements starts at the '.irp' directive, and is -terminated by an '.endr' directive. For each VALUE, SYMBOL is set to -VALUE, and the sequence of statements is assembled. If no VALUE is -listed, the sequence of statements is assembled once, with SYMBOL set to -the null string. To refer to SYMBOL within the sequence of statements, -use \SYMBOL. - - For example, assembling - - .irp param,1,2,3 - move d\param,sp@- - .endr - - is equivalent to assembling - - move d1,sp@- - move d2,sp@- - move d3,sp@- - - For some caveats with the spelling of SYMBOL, see also *note Macro::. - -7.60 '.irpc SYMBOL,VALUES'... -============================= - -Evaluate a sequence of statements assigning different values to SYMBOL. -The sequence of statements starts at the '.irpc' directive, and is -terminated by an '.endr' directive. For each character in VALUE, SYMBOL -is set to the character, and the sequence of statements is assembled. -If no VALUE is listed, the sequence of statements is assembled once, -with SYMBOL set to the null string. To refer to SYMBOL within the -sequence of statements, use \SYMBOL. - - For example, assembling - - .irpc param,123 - move d\param,sp@- - .endr - - is equivalent to assembling - - move d1,sp@- - move d2,sp@- - move d3,sp@- - - For some caveats with the spelling of SYMBOL, see also the discussion -at *Note Macro::. - -7.61 '.lcomm SYMBOL , LENGTH' -============================= - -Reserve LENGTH (an absolute expression) bytes for a local common denoted -by SYMBOL. The section and value of 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. SYMBOL is not declared global -(*note '.global': Global.), so is normally not visible to 'ld'. - -7.62 '.lflags' -============== - -'as' accepts this directive, for compatibility with other assemblers, -but ignores it. - -7.63 '.line LINE-NUMBER' -======================== - -Even though this is a directive associated with the 'a.out' or 'b.out' -object-code formats, 'as' still recognizes it when producing COFF -output, and treats '.line' as though it were the COFF '.ln' _if_ it is -found outside a '.def'/'.endef' pair. - - Inside a '.def', '.line' is, instead, one of the directives used by -compilers to generate auxiliary symbol information for debugging. - -7.64 '.linkonce [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 '.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. - - 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. - - The TYPE argument is optional. If specified, it must be one of the -following strings. For example: - .linkonce same_size - Not all types may be supported on all object file formats. - -'discard' - Silently discard duplicate sections. This is the default. - -'one_only' - Warn if there are duplicate sections, but still keep only one copy. - -'same_size' - Warn if any of the duplicates have different sizes. - -'same_contents' - Warn if any of the duplicates do not have exactly the same - contents. - -7.65 '.ln LINE-NUMBER' -====================== - -'.ln' is a synonym for '.line'. - -7.66 '.mri VAL' -=============== - -If VAL is non-zero, this tells 'as' to enter MRI mode. If VAL is zero, -this tells 'as' to exit MRI mode. This change affects code assembled -until the next '.mri' directive, or until the end of the file. *Note -MRI mode: M. - -7.67 '.list' -============ - -Control (in conjunction with the '.nolist' directive) whether or not -assembly listings are generated. These two directives maintain an -internal counter (which is zero initially). '.list' increments the -counter, and '.nolist' decrements it. Assembly listings are generated -whenever the counter is greater than zero. - - By default, listings are disabled. When you enable them (with the -'-a' command line option; *note Command-Line Options: Invoking.), the -initial value of the listing counter is one. - -7.68 '.long EXPRESSIONS' -======================== - -'.long' is the same as '.int'. *Note '.int': Int. - -7.69 '.macro' -============= - -The commands '.macro' and '.endm' allow you to define macros that -generate assembly output. For example, this definition specifies a -macro 'sum' that puts a sequence of numbers into memory: - - .macro sum from=0, to=5 - .long \from - .if \to-\from - sum "(\from+1)",\to - .endif - .endm - -With that definition, 'SUM 0,5' is equivalent to this assembly input: - - .long 0 - .long 1 - .long 2 - .long 3 - .long 4 - .long 5 - -'.macro MACNAME' -'.macro MACNAME MACARGS ...' - Begin the definition of a macro called 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 ':'req''), or whether it takes all of the - remaining arguments (through ':'vararg''). You can supply a - default value for any macro argument by following the name with - '=DEFLT'. You cannot define two macros with the same MACNAME - unless it has been subject to the '.purgem' directive (*note - Purgem::) between the two definitions. For example, these are all - valid '.macro' statements: - - '.macro comm' - Begin the definition of a macro called 'comm', which takes no - arguments. - - '.macro plus1 p, p1' - '.macro plus1 p p1' - Either statement begins the definition of a macro called - 'plus1', which takes two arguments; within the macro - definition, write '\p' or '\p1' to evaluate the arguments. - - '.macro reserve_str p1=0 p2' - Begin the definition of a macro called '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 'reserve_str A,B' (with '\p1' evaluating - to A and '\p2' evaluating to B), or as 'reserve_str ,B' (with - '\p1' evaluating as the default, in this case '0', and '\p2' - evaluating to B). - - '.macro m p1:req, p2=0, p3:vararg' - Begin the definition of a macro called '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. - - When you call a macro, you can specify the argument values - either by position, or by keyword. For example, 'sum 9,17' is - equivalent to 'sum to=17, from=9'. - - Note that since each of the 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 (':') 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: - - .macro label l - \l: - .endm - - might not work as expected. Invoking 'label foo' might not create - a label called 'foo' but instead just insert the text '\l:' into - the assembler source, probably generating an error about an - unrecognised identifier. - - Similarly problems might occur with the period character ('.') - 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: - - .macro opcode base length - \base.\length - .endm - - and invoking it as 'opcode store l' will not create a 'store.l' - instruction but instead generate some kind of error as the - assembler tries to interpret the text '\base.\length'. - - There are several possible ways around this problem: - - 'Insert white space' - If it is possible to use white space characters then this is - the simplest solution. eg: - - .macro label l - \l : - .endm - - 'Use '\()'' - The string '\()' can be used to separate the end of a macro - argument from the following text. eg: - - .macro opcode base length - \base\().\length - .endm - - 'Use the alternate macro syntax mode' - In the alternative macro syntax mode the ampersand character - ('&') can be used as a separator. eg: - - .altmacro - .macro label l - l&: - .endm - - Note: this problem of correctly identifying string parameters to - pseudo ops also applies to the identifiers used in '.irp' (*note - Irp::) and '.irpc' (*note Irpc::) as well. - -'.endm' - Mark the end of a macro definition. - -'.exitm' - Exit early from the current macro definition. - -'\@' - 'as' maintains a counter of how many macros it has executed in this - pseudo-variable; you can copy that number to your output with '\@', - but _only within a macro definition_. - -'LOCAL NAME [ , ... ]' - _Warning: 'LOCAL' is only available if you select "alternate macro - syntax" with '--alternate' or '.altmacro'._ *Note '.altmacro': - Altmacro. - -7.70 '.altmacro' -================ - -Enable alternate macro mode, enabling: - -'LOCAL NAME [ , ... ]' - One additional directive, 'LOCAL', is available. It is used to - generate a string replacement for each of the NAME arguments, and - replace any instances of NAME in each macro expansion. The - replacement string is unique in the assembly, and different for - each separate macro expansion. 'LOCAL' allows you to write macros - that define symbols, without fear of conflict between separate - macro expansions. - -'String delimiters' - You can write strings delimited in these other ways besides - '"STRING"': - - ''STRING'' - You can delimit strings with single-quote characters. - - '<STRING>' - You can delimit strings with matching angle brackets. - -'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 '!' (an exclamation mark). For example, - you can write '<4.3 !> 5.4!!>' to get the literal text '4.3 > - 5.4!'. - -'Expression results as strings' - You can write '%EXPR' to evaluate the expression EXPR and use the - result as a string. - -7.71 '.noaltmacro' -================== - -Disable alternate macro mode. *Note Altmacro::. - -7.72 '.nolist' -============== - -Control (in conjunction with the '.list' directive) whether or not -assembly listings are generated. These two directives maintain an -internal counter (which is zero initially). '.list' increments the -counter, and '.nolist' decrements it. Assembly listings are generated -whenever the counter is greater than zero. - -7.73 '.octa BIGNUMS' -==================== - -This directive expects zero or more bignums, separated by commas. For -each bignum, it emits a 16-byte integer. - - The term "octa" comes from contexts in which a "word" is two bytes; -hence _octa_-word for 16 bytes. - -7.74 '.org NEW-LC , FILL' -========================= - -Advance the location counter of the current section to NEW-LC. NEW-LC -is either an absolute expression or an expression with the same section -as the current subsection. That is, you can't use '.org' to cross -sections: if NEW-LC has the wrong section, the '.org' directive is -ignored. To be compatible with former assemblers, if the section of -NEW-LC is absolute, 'as' issues a warning, then pretends the section of -NEW-LC is the same as the current subsection. - - '.org' may only increase the location counter, or leave it unchanged; -you cannot use '.org' to move the location counter backwards. - - Because 'as' tries to assemble programs in one pass, NEW-LC may not -be undefined. If you really detest this restriction we eagerly await a -chance to share your improved assembler. - - 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. - - When the location counter (of the current subsection) is advanced, -the intervening bytes are filled with FILL which should be an absolute -expression. If the comma and FILL are omitted, FILL defaults to zero. - -7.75 '.p2align[wl] ABS-EXPR, ABS-EXPR, 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 '.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. - - 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. - - 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. - - The '.p2alignw' and '.p2alignl' directives are variants of the -'.p2align' directive. The '.p2alignw' directive treats the fill pattern -as a two byte word value. The '.p2alignl' directives treats the fill -pattern as a four byte longword value. For example, '.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. - -7.76 '.previous' -================ - -This is one of the ELF section stack manipulation directives. The -others are '.section' (*note Section::), '.subsection' (*note -SubSection::), '.pushsection' (*note PushSection::), and '.popsection' -(*note PopSection::). - - This directive swaps the current section (and subsection) with most -recently referenced section (and subsection) prior to this one. -Multiple '.previous' directives in a row will flip between two sections -(and their subsections). - - In terms of the section stack, this directive swaps the current -section with the top section on the section stack. - -7.77 '.popsection' -================== - -This is one of the ELF section stack manipulation directives. The -others are '.section' (*note Section::), '.subsection' (*note -SubSection::), '.pushsection' (*note PushSection::), and '.previous' -(*note Previous::). - - 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. - -7.78 '.print STRING' -==================== - -'as' will print STRING on the standard output during assembly. You must -put STRING in double quotes. - -7.79 '.protected NAMES' -======================= - -This is one of the ELF visibility directives. The other two are -'.hidden' (*note Hidden::) and '.internal' (*note Internal::). - - This directive overrides the named symbols default visibility (which -is set by their binding: local, global or weak). The directive sets the -visibility to '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. - -7.80 '.psize LINES , COLUMNS' -============================= - -Use this directive to declare the number of lines--and, optionally, the -number of columns--to use for each page, when generating listings. - - If you do not use '.psize', listings use a default line-count of 60. -You may omit the comma and COLUMNS specification; the default width is -200 columns. - - 'as' generates formfeeds whenever the specified number of lines is -exceeded (or whenever you explicitly request one, using '.eject'). - - If you specify LINES as '0', no formfeeds are generated save those -explicitly specified with '.eject'. - -7.81 '.purgem NAME' -=================== - -Undefine the macro NAME, so that later uses of the string will not be -expanded. *Note Macro::. - -7.82 '.pushsection NAME , SUBSECTION' -===================================== - -This is one of the ELF section stack manipulation directives. The -others are '.section' (*note Section::), '.subsection' (*note -SubSection::), '.popsection' (*note PopSection::), and '.previous' -(*note Previous::). - - This directive pushes the current section (and subsection) onto the -top of the section stack, and then replaces the current section and -subsection with 'name' and 'subsection'. - -7.83 '.quad BIGNUMS' -==================== - -'.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. - - The term "quad" comes from contexts in which a "word" is two bytes; -hence _quad_-word for 8 bytes. - -7.84 '.reloc OFFSET, RELOC_NAME[, EXPRESSION]' -============================================== - -Generate a relocation at OFFSET of type RELOC_NAME with value -EXPRESSION. If OFFSET is a number, the relocation is generated in the -current section. If OFFSET is an expression that resolves to a symbol -plus offset, the relocation is generated in the given symbol's section. -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. - -7.85 '.rept COUNT' -================== - -Repeat the sequence of lines between the '.rept' directive and the next -'.endr' directive COUNT times. - - For example, assembling - - .rept 3 - .long 0 - .endr - - is equivalent to assembling - - .long 0 - .long 0 - .long 0 - -7.86 '.sbttl "SUBHEADING"' -========================== - -Use SUBHEADING as the title (third line, immediately after the title -line) when generating assembly listings. - - This directive affects subsequent pages, as well as the current page -if it appears within ten lines of the top of a page. - -7.87 '.section NAME' -==================== - -Use the '.section' directive to assemble the following code into a -section named NAME. - - This directive is only supported for targets that actually support -arbitrarily named sections; on 'a.out' targets, for example, it is not -accepted, even with a standard 'a.out' section name. - - This is one of the ELF section stack manipulation directives. The -others are '.subsection' (*note SubSection::), '.pushsection' (*note -PushSection::), '.popsection' (*note PopSection::), and '.previous' -(*note Previous::). - - For ELF targets, the '.section' directive is used like this: - - .section NAME [, "FLAGS"[, @TYPE[,FLAG_SPECIFIC_ARGUMENTS]]] - - The optional FLAGS argument is a quoted string which may contain any -combination of the following characters: -'a' - section is allocatable -'w' - section is writable -'x' - section is executable -'M' - section is mergeable -'S' - section contains zero terminated strings -'G' - section is a member of a section group -'T' - section is used for thread-local-storage - - The optional TYPE argument may contain one of the following -constants: -'@progbits' - section contains data -'@nobits' - section does not contain data (i.e., section only occupies space) -'@note' - section contains data which is used by things other than the - program -'@init_array' - section contains an array of pointers to init functions -'@fini_array' - section contains an array of pointers to finish functions -'@preinit_array' - section contains an array of pointers to pre-init functions - - Many targets only support the first three section types. - - Note on targets where the '@' character is the start of a comment (eg -ARM) then another character is used instead. For example the ARM port -uses the '%' character. - - If FLAGS contains the 'M' symbol then the TYPE argument must be -specified as well as an extra argument--ENTSIZE--like this: - - .section NAME , "FLAGS"M, @TYPE, ENTSIZE - - Sections with the 'M' flag but not 'S' flag must contain fixed size -constants, each ENTSIZE octets long. Sections with both 'M' and 'S' -must contain zero terminated strings where each character is ENTSIZE -bytes long. The linker may remove duplicates within sections with the -same name, same entity size and same flags. ENTSIZE must be an absolute -expression. - - If FLAGS contains the 'G' symbol then the TYPE argument must be -present along with an additional field like this: - - .section NAME , "FLAGS"G, @TYPE, GROUPNAME[, LINKAGE] - - The GROUPNAME field specifies the name of the section group to which -this particular section belongs. The optional linkage field can -contain: -'comdat' - indicates that only one copy of this section should be retained -'.gnu.linkonce' - an alias for comdat - - Note: if both the M and G flags are present then the fields for the -Merge flag should come first, like this: - - .section NAME , "FLAGS"MG, @TYPE, ENTSIZE, GROUPNAME[, LINKAGE] - - 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. - - For ELF targets, the assembler supports another type of '.section' -directive for compatibility with the Solaris assembler: - - .section "NAME"[, FLAGS...] - - Note that the section name is quoted. There may be a sequence of -comma separated flags: -'#alloc' - section is allocatable -'#write' - section is writable -'#execinstr' - section is executable -'#tls' - section is used for thread local storage - - This directive replaces the current section and subsection. See the -contents of the gas testsuite directory 'gas/testsuite/gas/elf' for some -examples of how this directive and the other section stack directives -work. - -7.88 '.set SYMBOL, EXPRESSION' -============================== - -Set the value of SYMBOL to EXPRESSION. This changes SYMBOL's value and -type to conform to EXPRESSION. If SYMBOL was flagged as external, it -remains flagged (*note Symbol Attributes::). - - You may '.set' a symbol many times in the same assembly. - - If you '.set' a global symbol, the value stored in the object file is -the last value stored into it. - -7.89 '.short EXPRESSIONS' -========================= - -This expects zero or more EXPRESSIONS, and emits a 16 bit number for -each. - -7.90 '.single FLONUMS' -====================== - -This directive assembles zero or more flonums, separated by commas. It -has the same effect as '.float'. - -7.91 '.size' -============ - -This directive is used to set the size associated with a symbol. - - For ELF targets, the '.size' directive is used like this: - - .size NAME , EXPRESSION - - This directive sets the size associated with a symbol NAME. The size -in bytes is computed from EXPRESSION which can make use of label -arithmetic. This directive is typically used to set the size of -function symbols. - -7.92 '.sleb128 EXPRESSIONS' -=========================== - -SLEB128 stands for "signed little endian base 128." This is a compact, -variable length representation of numbers used by the DWARF symbolic -debugging format. *Note '.uleb128': Uleb128. - -7.93 '.skip SIZE , FILL' -======================== - -This directive emits SIZE bytes, each of value FILL. Both SIZE and FILL -are absolute expressions. If the comma and FILL are omitted, FILL is -assumed to be zero. This is the same as '.space'. - -7.94 '.space SIZE , FILL' -========================= - -This directive emits SIZE bytes, each of value FILL. Both SIZE and FILL -are absolute expressions. If the comma and FILL are omitted, FILL is -assumed to be zero. This is the same as '.skip'. - -7.95 '.stabd, .stabn, .stabs' -============================= - -There are three directives that begin '.stab'. All emit symbols (*note -Symbols::), for use by symbolic debuggers. The symbols are not entered -in the 'as' hash table: they cannot be referenced elsewhere in the -source file. Up to five fields are required: - -STRING - This is the symbol's name. It may contain any character except - '\000', so is more general than ordinary symbol names. Some - debuggers used to code arbitrarily complex structures into symbol - names using this field. - -TYPE - An absolute expression. The symbol's type is set to the low 8 bits - of this expression. Any bit pattern is permitted, but 'ld' and - debuggers choke on silly bit patterns. - -OTHER - An absolute expression. The symbol's "other" attribute is set to - the low 8 bits of this expression. - -DESC - An absolute expression. The symbol's descriptor is set to the low - 16 bits of this expression. - -VALUE - An absolute expression which becomes the symbol's value. - - If a warning is detected while reading a '.stabd', '.stabn', or -'.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! - -'.stabd TYPE , OTHER , DESC' - - The "name" 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. - - 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 '.stabd' was assembled. - -'.stabn TYPE , OTHER , DESC , VALUE' - The name of the symbol is set to the empty string '""'. - -'.stabs STRING , TYPE , OTHER , DESC , VALUE' - All five fields are specified. - -7.96 '.string' "STR" -==================== - -Copy the characters in 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 *note Strings: Strings. - -7.97 '.struct EXPRESSION' -========================= - -Switch to the absolute section, and set the section offset to -EXPRESSION, which must be an absolute expression. You might use this as -follows: - .struct 0 - field1: - .struct field1 + 4 - field2: - .struct field2 + 4 - field3: - This would define the symbol 'field1' to have the value 0, the symbol -'field2' to have the value 4, and the symbol 'field3' to have the value -8. Assembly would be left in the absolute section, and you would need -to use a '.section' directive of some sort to change to some other -section before further assembly. - -7.98 '.subsection NAME' -======================= - -This is one of the ELF section stack manipulation directives. The -others are '.section' (*note Section::), '.pushsection' (*note -PushSection::), '.popsection' (*note PopSection::), and '.previous' -(*note Previous::). - - This directive replaces the current subsection with '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. - -7.99 '.symver' -============== - -Use the '.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. - - For ELF targets, the '.symver' directive can be used like this: - .symver NAME, NAME2@NODENAME - If the symbol NAME is defined within the file being assembled, the -'.symver' directive effectively creates a symbol alias with the name -NAME2@NODENAME, and in fact the main reason that we just don't try and -create a regular alias is that the @ character isn't permitted in symbol -names. The NAME2 part of the name is the actual name of the symbol by -which it will be externally referenced. The name 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 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 NODENAME should -correspond to the nodename of the symbol you are trying to override. - - If the symbol NAME is not defined within the file being assembled, -all references to NAME will be changed to NAME2@NODENAME. If no -reference to NAME is made, NAME2@NODENAME will be removed from the -symbol table. - - Another usage of the '.symver' directive is: - .symver NAME, NAME2@@NODENAME - In this case, the symbol NAME must exist and be defined within the -file being assembled. It is similar to NAME2@NODENAME. The difference -is NAME2@@NODENAME will also be used to resolve references to NAME2 by -the linker. - - The third usage of the '.symver' directive is: - .symver NAME, NAME2@@@NODENAME - When NAME is not defined within the file being assembled, it is -treated as NAME2@NODENAME. When NAME is defined within the file being -assembled, the symbol name, NAME, will be changed to NAME2@@NODENAME. - -7.100 '.text SUBSECTION' -======================== - -Tells 'as' to assemble the following statements onto the end of the text -subsection numbered SUBSECTION, which is an absolute expression. If -SUBSECTION is omitted, subsection number zero is used. - -7.101 '.title "HEADING"' -======================== - -Use HEADING as the title (second line, immediately after the source file -name and pagenumber) when generating assembly listings. - - This directive affects subsequent pages, as well as the current page -if it appears within ten lines of the top of a page. - -7.102 '.type' -============= - -This directive is used to set the type of a symbol. - - For ELF targets, the '.type' directive is used like this: - - .type NAME , TYPE DESCRIPTION - - This sets the type of symbol NAME to be either a function symbol or -an object symbol. There are five different syntaxes supported for the -TYPE DESCRIPTION field, in order to provide compatibility with various -other assemblers. - - Because some of the characters used in these syntaxes (such as '@' -and '#') 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. - - The syntaxes supported are: - - .type <name> STT_FUNCTION - .type <name> STT_OBJECT - - .type <name>,#function - .type <name>,#object - - .type <name>,@function - .type <name>,@object - - .type <name>,%function - .type <name>,%object - - .type <name>,"function" - .type <name>,"object" - -7.103 '.uleb128 EXPRESSIONS' -============================ - -ULEB128 stands for "unsigned little endian base 128." This is a -compact, variable length representation of numbers used by the DWARF -symbolic debugging format. *Note '.sleb128': Sleb128. - -7.104 '.version "STRING"' -========================= - -This directive creates a '.note' section and places into it an ELF -formatted note of type NT_VERSION. The note's name is set to 'string'. - -7.105 '.vtable_entry TABLE, OFFSET' -=================================== - -This directive finds or creates a symbol 'table' and creates a -'VTABLE_ENTRY' relocation for it with an addend of 'offset'. - -7.106 '.vtable_inherit CHILD, PARENT' -===================================== - -This directive finds the symbol 'child' and finds or creates the symbol -'parent' and then creates a 'VTABLE_INHERIT' relocation for the parent -whose addend is the value of the child symbol. As a special case the -parent name of '0' is treated as referring to the '*ABS*' section. - -7.107 '.warning "STRING"' -========================= - -Similar to the directive '.error' (*note '.error "STRING"': Error.), but -just emits a warning. - -7.108 '.weak NAMES' -=================== - -This directive sets the weak attribute on the comma separated list of -symbol 'names'. If the symbols do not already exist, they will be -created. - - 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 'names'. If the symbols do not already exist, they will be -created. - - 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. - -7.109 '.weakref ALIAS, 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. - - 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. - - The alias itself never makes to the symbol table, and is entirely -handled within the assembler. - -7.110 '.word EXPRESSIONS' -========================= - -This directive expects zero or more EXPRESSIONS, of any section, -separated by commas. For each expression, 'as' emits a 32-bit number. - -7.111 Deprecated Directives -=========================== - -One day these directives won't work. They are included for -compatibility with older assemblers. -.abort -.line - -8 ARM Dependent Features -************************ - -8.1 Options -=========== - -'-mcpu=PROCESSOR[+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: 'arm1', 'arm2', 'arm250', - 'arm3', 'arm6', 'arm60', 'arm600', 'arm610', 'arm620', 'arm7', - 'arm7m', 'arm7d', 'arm7dm', 'arm7di', 'arm7dmi', 'arm70', 'arm700', - 'arm700i', 'arm710', 'arm710t', 'arm720', 'arm720t', 'arm740t', - 'arm710c', 'arm7100', 'arm7500', 'arm7500fe', 'arm7t', 'arm7tdmi', - 'arm7tdmi-s', 'arm8', 'arm810', 'strongarm', 'strongarm1', - 'strongarm110', 'strongarm1100', 'strongarm1110', 'arm9', 'arm920', - 'arm920t', 'arm922t', 'arm940t', 'arm9tdmi', 'arm9e', 'arm926e', - 'arm926ej-s', 'arm946e-r0', 'arm946e', 'arm946e-s', 'arm966e-r0', - 'arm966e', 'arm966e-s', 'arm968e-s', 'arm10t', 'arm10tdmi', - 'arm10e', 'arm1020', 'arm1020t', 'arm1020e', 'arm1022e', - 'arm1026ej-s', 'arm1136j-s', 'arm1136jf-s', 'arm1156t2-s', - 'arm1156t2f-s', 'arm1176jz-s', 'arm1176jzf-s', 'mpcore', - 'mpcorenovfp', 'cortex-a8', 'cortex-r4', 'cortex-m3', 'ep9312' - (ARM920 with Cirrus Maverick coprocessor), 'i80200' (Intel XScale - processor) 'iwmmxt' (Intel(r) XScale processor with Wireless - MMX(tm) technology coprocessor) and 'xscale'. The special name - 'all' may be used to allow the assembler to accept instructions - valid for any ARM processor. - - 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, - '-mcpu=arm920+maverick' is equivalent to specifying '-mcpu=ep9312'. - The following extensions are currently supported: '+maverick' - '+iwmmxt' and '+xscale'. - -'-march=ARCHITECTURE[+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: 'armv1', 'armv2', - 'armv2a', 'armv2s', 'armv3', 'armv3m', 'armv4', 'armv4xm', - 'armv4t', 'armv4txm', 'armv5', 'armv5t', 'armv5txm', 'armv5te', - 'armv5texp', 'armv6', 'armv6j', 'armv6k', 'armv6z', 'armv6zk', - 'armv7', 'armv7-a', 'armv7-r', 'armv7-m', 'iwmmxt' and 'xscale'. - If both '-mcpu' and '-march' are specified, the assembler will use - the setting for '-mcpu'. - - The architecture option can be extended with the same instruction - set extension options as the '-mcpu' option. - -'-mfpu=FLOATING-POINT-FORMAT' - - 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: - 'softfpa', 'fpe', 'fpe2', 'fpe3', 'fpa', 'fpa10', 'fpa11', - 'arm7500fe', 'softvfp', 'softvfp+vfp', 'vfp', 'vfp10', 'vfp10-r0', - 'vfp9', 'vfpxd', 'arm1020t', 'arm1020e', 'arm1136jf-s' and - 'maverick'. - - In addition to determining which instructions are assembled, this - option also affects the way in which the '.double' assembler - directive behaves when assembling little-endian code. - - 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. - -'-mthumb' - This option specifies that the assembler should start assembling - Thumb instructions; that is, it should behave as though the file - starts with a '.code 16' directive. - -'-mthumb-interwork' - This option specifies that the output generated by the assembler - should be marked as supporting interworking. - -'-mapcs [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. - -'-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. - -'-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. - -'-mapcs-reentrant' - This indicates that the reentrant variant of the APCS should be - used. This variant supports position independent code. - -'-mfloat-abi=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: 'soft', 'softfp' and 'hard'. - -'-meabi=VER' - This option specifies which EABI version the produced object files - should conform to. The following values are recognized: 'gnu', '4' - and '5'. - -'-EB' - This option specifies that the output generated by the assembler - should be marked as being encoded for a big-endian processor. - -'-EL' - This option specifies that the output generated by the assembler - should be marked as being encoded for a little-endian processor. - -'-k' - This option specifies that the output of the assembler should be - marked as position-independent code (PIC). - -8.2 Syntax -========== - -8.2.1 Special Characters ------------------------- - -The presence of a '@' on a line indicates the start of a comment that -extends to the end of the current line. If a '#' appears as the first -character of a line, the whole line is treated as a comment. - - The ';' character can be used instead of a newline to separate -statements. - - Either '#' or '$' can be used to indicate immediate operands. - - *TODO* Explain about /data modifier on symbols. - -8.2.2 Register Names --------------------- - -*TODO* Explain about ARM register naming, and the predefined names. - -8.2.3 ARM relocation generation -------------------------------- - -Specific data relocations can be generated by putting the relocation -name in parentheses after the symbol name. For example: - - .word foo(TARGET1) - - This will generate an 'R_ARM_TARGET1' relocation against the symbol -FOO. The following relocations are supported: 'GOT', 'GOTOFF', -'TARGET1', 'TARGET2', 'SBREL', 'TLSGD', 'TLSLDM', 'TLSLDO', 'GOTTPOFF' -and 'TPOFF'. - - For compatibility with older toolchains the assembler also accepts -'(PLT)' after branch targets. This will generate the deprecated -'R_ARM_PLT32' relocation. - - Relocations for 'MOVW' and 'MOVT' instructions can be generated by -prefixing the value with '#:lower16:' and '#:upper16' respectively. For -example to load the 32-bit address of foo into r0: - - MOVW r0, #:lower16:foo - MOVT r0, #:upper16:foo - -8.3 Floating Point -================== - -The ARM family uses IEEE floating-point numbers. - -8.4 ARM Machine Directives -========================== - -'.align EXPRESSION [, EXPRESSION]' - This is the generic .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. - -'NAME .req REGISTER NAME' - This creates an alias for REGISTER NAME called NAME. For example: - - foo .req r0 - -'.unreq ALIAS-NAME' - This undefines a register alias which was previously defined using - the 'req', 'dn' or 'qn' directives. For example: - - foo .req r0 - .unreq foo - - 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. - -'NAME .dn REGISTER NAME [.TYPE] [[INDEX]]' -'NAME .qn REGISTER NAME [.TYPE] [[INDEX]]' - - The 'dn' and '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. - - 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: - - x .dn d2.f32 - y .dn d3.f32 - z .dn d4.f32[1] - vmul x,y,z - - This is equivalent to writing the following: - - vmul.f32 d2,d3,d4[1] - - Aliases created using 'dn' or 'qn' can be destroyed using 'unreq'. - -'.code [16|32]' - This directive selects the instruction set being generated. The - value 16 selects Thumb, with the value 32 selecting ARM. - -'.thumb' - This performs the same action as .CODE 16. - -'.arm' - This performs the same action as .CODE 32. - -'.force_thumb' - This directive forces the selection of Thumb instructions, even if - the target processor does not support those instructions - -'.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 '.thumb' - - This directive is not neccessary when generating EABI objects. On - these targets the encoding is implicit when generating Thumb code. - -'.thumb_set' - This performs the equivalent of a '.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 '.thumb_func' directive does. - -'.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). 'GAS' maintains a separate literal pool for each - section and each sub-section. The '.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. - - Note - older versions of '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. - -'.pool' - This is a synonym for .ltorg. - -'.unwind_fnstart' - Marks the start of a function with an unwind table entry. - -'.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. - - 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. - -'.cantunwind' - Prevents unwinding through the current function. No personality - routine or exception table data is required or permitted. - -'.personality NAME' - Sets the personality routine for the current function to NAME. - -'.personalityindex INDEX' - Sets the personality routine for the current function to the EABI - standard routine number INDEX - -'.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 '.fnend' directive will be added to the exception - table entry. - - Must be preceded by a '.personality' or '.personalityindex' - directive. - -'.save REGLIST' - Generate unwinder annotations to restore the registers in REGLIST. - The format of REGLIST is the same as the corresponding - store-multiple instruction. - - _core registers_ - .save {r4, r5, r6, lr} - stmfd sp!, {r4, r5, r6, lr} - _FPA registers_ - .save f4, 2 - sfmfd f4, 2, [sp]! - _VFP registers_ - .save {d8, d9, d10} - fstmdx sp!, {d8, d9, d10} - _iWMMXt registers_ - .save {wr10, wr11} - wstrd wr11, [sp, #-8]! - wstrd wr10, [sp, #-8]! - or - .save wr11 - wstrd wr11, [sp, #-8]! - .save wr10 - wstrd wr10, [sp, #-8]! - -'.vsave VFP-REGLIST' - Generate unwinder annotations to restore the VFP registers in - VFP-REGLIST using FLDMD. Also works for VFPv3 registers that are to - be restored using VLDM. The format of VFP-REGLIST is the same as - the corresponding store-multiple instruction. - - _VFP registers_ - .vsave {d8, d9, d10} - fstmdd sp!, {d8, d9, d10} - _VFPv3 registers_ - .vsave {d15, d16, d17} - vstm sp!, {d15, d16, d17} - - Since FLDMX and FSTMX are now deprecated, this directive should be - used in favour of '.save' for saving VFP registers for ARMv6 and - above. - -'.pad #COUNT' - Generate unwinder annotations for a stack adjustment of COUNT - bytes. A positive value indicates the function prologue allocated - stack space by decrementing the stack pointer. - -'.movsp REG [, #OFFSET]' - Tell the unwinder that REG contains an offset from the current - stack pointer. If OFFSET is not specified then it is assumed to be - zero. - -'.setfp FPREG, SPREG [, #OFFSET]' - Make all unwinder annotations relaive to a frame pointer. Without - this the unwinder will use offsets from the stack pointer. - - The syntax of this directive is the same as the 'sub' or 'mov' - instruction used to set the frame pointer. SPREG must be either - 'sp' or mentioned in a previous '.movsp' directive. - - .movsp ip - mov ip, sp - ... - .setfp fp, ip, #4 - sub fp, ip, #4 - -'.raw OFFSET, BYTE1, ...' - Insert one of more arbitary unwind opcode bytes, which are known to - adjust the stack pointer by OFFSET bytes. - - For example '.unwind_raw 4, 0xb1, 0x01' is equivalent to '.save - {r0}' - -'.cpu NAME' - Select the target processor. Valid values for NAME are the same as - for the '-mcpu' commandline option. - -'.arch NAME' - Select the target architecture. Valid values for NAME are the same - as for the '-march' commandline option. - -'.object_arch NAME' - Override the architecture recorded in the EABI object attribute - section. Valid values for NAME are the same as for the '.arch' - directive. Typically this is useful when code uses runtime - detection of CPU features. - -'.fpu NAME' - Select the floating point unit to assemble for. Valid values for - NAME are the same as for the '-mfpu' commandline option. - -'.eabi_attribute TAG, VALUE' - Set the EABI object attribute number TAG to VALUE. The value is - either a 'number', '"string"', or 'number, "string"' depending on - the tag. - -8.5 Opcodes -=========== - -'as' implements all the standard ARM opcodes. It also implements -several pseudo opcodes, including several synthetic load instructions. - -'NOP' - nop - - This pseudo op will always evaluate to a legal ARM instruction that - does nothing. Currently it will evaluate to MOV r0, r0. - -'LDR' - ldr <register> , = <expression> - - 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. - -'ADR' - adr <register> <label> - - This instruction will load the address of LABEL into the indicated - register. The instruction will evaluate to a PC relative ADD or - SUB instruction depending upon where the label is located. If the - label is out of range, or if it is not defined in the same file - (and section) as the ADR instruction, then an error will be - generated. This instruction will not make use of the literal pool. - -'ADRL' - adrl <register> <label> - - This instruction will load the address of LABEL into the indicated - register. The instruction will evaluate to one or two PC relative - ADD or SUB instructions depending upon where the label is located. - If a second instruction is not needed a NOP instruction will be - generated in its place, so that this instruction is always 8 bytes - long. - - If the label is out of range, or if it is not defined in the same - file (and section) as the ADRL instruction, then an error will be - generated. This instruction will not make use of the literal pool. - - For information on the ARM or Thumb instruction sets, see 'ARM -Software Development Toolkit Reference Manual', Advanced RISC Machines -Ltd. - -8.6 Mapping Symbols -=================== - -The ARM ELF specification requires that special symbols be inserted into -object files to mark certain features: - -'$a' - At the start of a region of code containing ARM instructions. - -'$t' - At the start of a region of code containing THUMB instructions. - -'$d' - At the start of a region of data. - - The assembler will automatically insert these symbols for you - there -is no need to code them yourself. Support for tagging symbols ($b, $f, -$p and $m) which is also mentioned in the current ARM ELF specification -is not implemented. This is because they have been dropped from the new -EABI and so tools cannot rely upon their presence. - -9 80386 Dependent Features -************************** - -The i386 version 'as' supports both the original Intel 386 architecture -in both 16 and 32-bit mode as well as AMD x86-64 architecture extending -the Intel architecture to 64-bits. - -9.1 Options -=========== - -The i386 version of 'as' has a few machine dependent options: - -'--32 | --64' - Select the word size, either 32 bits or 64 bits. Selecting 32-bit - implies Intel i386 architecture, while 64-bit implies AMD x86-64 - architecture. - - These options are only available with the ELF object file format, - and require that the necessary BFD support has been included (on a - 32-bit platform you have to add -enable-64-bit-bfd to configure - enable 64-bit usage and use x86-64 as target platform). - -'-n' - By default, x86 GAS replaces multiple nop instructions used for - alignment within code sections with multi-byte nop instructions - such as leal 0(%esi,1),%esi. This switch disables the - optimization. - -'--divide' - On SVR4-derived platforms, the character '/' is treated as a - comment character, which means that it cannot be used in - expressions. The '--divide' option turns '/' into a normal - character. This does not disable '/' at the beginning of a line - starting a comment, or affect using '#' for starting a comment. - -'-march=CPU' - This option specifies an instruction set architecture for - generating instructions. The following architectures are - recognized: 'i8086', 'i186', 'i286', 'i386', 'i486', 'i586', - 'i686', 'pentium', 'pentiumpro', 'pentiumii', 'pentiumiii', - 'pentium4', 'prescott', 'nocona', 'core', 'core2', 'k6', 'k6_2', - 'athlon', 'sledgehammer', 'opteron', 'k8', 'generic32' and - 'generic64'. - - This option only affects instructions generated by the assembler. - The '.arch' directive will take precedent. - -'-mtune=CPU' - This option specifies a processor to optimize for. When used in - conjunction with the '-march' option, only instructions of the - processor specified by the '-march' option will be generated. - - Valid CPU values are identical to '-march=CPU'. - -9.2 AT&T Syntax versus Intel Syntax -=================================== - -'as' now supports assembly using Intel assembler syntax. -'.intel_syntax' selects Intel mode, and '.att_syntax' switches back to -the usual AT&T mode for compatibility with the output of 'gcc'. Either -of these directives may have an optional argument, 'prefix', or -'noprefix' specifying whether registers require a '%' prefix. AT&T -System V/386 assembler syntax is quite different from Intel syntax. We -mention these differences because almost all 80386 documents use Intel -syntax. Notable differences between the two syntaxes are: - - * AT&T immediate operands are preceded by '$'; Intel immediate - operands are undelimited (Intel 'push 4' is AT&T 'pushl $4'). AT&T - register operands are preceded by '%'; Intel register operands are - undelimited. AT&T absolute (as opposed to PC relative) jump/call - operands are prefixed by '*'; they are undelimited in Intel syntax. - - * AT&T and Intel syntax use the opposite order for source and - destination operands. Intel 'add eax, 4' is 'addl $4, %eax'. The - 'source, dest' convention is maintained for compatibility with - previous Unix assemblers. Note that instructions with more than - one source operand, such as the 'enter' instruction, do _not_ have - reversed order. *note i386-Bugs::. - - * In AT&T syntax the size of memory operands is determined from the - last character of the instruction mnemonic. Mnemonic suffixes of - 'b', 'w', 'l' and 'q' specify byte (8-bit), word (16-bit), long - (32-bit) and quadruple word (64-bit) memory references. Intel - syntax accomplishes this by prefixing memory operands (_not_ the - instruction mnemonics) with 'byte ptr', 'word ptr', 'dword ptr' and - 'qword ptr'. Thus, Intel 'mov al, byte ptr FOO' is 'movb FOO, %al' - in AT&T syntax. - - * Immediate form long jumps and calls are 'lcall/ljmp $SECTION, - $OFFSET' in AT&T syntax; the Intel syntax is 'call/jmp far - SECTION:OFFSET'. Also, the far return instruction is 'lret - $STACK-ADJUST' in AT&T syntax; Intel syntax is 'ret far - STACK-ADJUST'. - - * The AT&T assembler does not provide support for multiple section - programs. Unix style systems expect all programs to be single - sections. - -9.3 Instruction Naming -====================== - -Instruction mnemonics are suffixed with one character modifiers which -specify the size of operands. The letters 'b', 'w', 'l' and 'q' specify -byte, word, long and quadruple word operands. If no suffix is specified -by an instruction then 'as' tries to fill in the missing suffix based on -the destination register operand (the last one by convention). Thus, -'mov %ax, %bx' is equivalent to 'movw %ax, %bx'; also, 'mov $1, %bx' is -equivalent to 'movw $1, bx'. Note that this is incompatible with the -AT&T Unix assembler which assumes that a missing mnemonic suffix implies -long operand size. (This incompatibility does not affect compiler -output since compilers always explicitly specify the mnemonic suffix.) - - Almost all instructions have the same names in AT&T and Intel format. -There are a few exceptions. The sign extend and zero extend -instructions need two sizes to specify them. They need a size to -sign/zero extend _from_ and a size to zero extend _to_. This is -accomplished by using two instruction mnemonic suffixes in AT&T syntax. -Base names for sign extend and zero extend are 'movs...' and 'movz...' -in AT&T syntax ('movsx' and 'movzx' in Intel syntax). The instruction -mnemonic suffixes are tacked on to this base name, the _from_ suffix -before the _to_ suffix. Thus, 'movsbl %al, %edx' is AT&T syntax for -"move sign extend _from_ %al _to_ %edx." Possible suffixes, thus, are -'bl' (from byte to long), 'bw' (from byte to word), 'wl' (from word to -long), 'bq' (from byte to quadruple word), 'wq' (from word to quadruple -word), and 'lq' (from long to quadruple word). - - The Intel-syntax conversion instructions - - * 'cbw' -- sign-extend byte in '%al' to word in '%ax', - - * 'cwde' -- sign-extend word in '%ax' to long in '%eax', - - * 'cwd' -- sign-extend word in '%ax' to long in '%dx:%ax', - - * 'cdq' -- sign-extend dword in '%eax' to quad in '%edx:%eax', - - * 'cdqe' -- sign-extend dword in '%eax' to quad in '%rax' (x86-64 - only), - - * 'cqo' -- sign-extend quad in '%rax' to octuple in '%rdx:%rax' - (x86-64 only), - -are called 'cbtw', 'cwtl', 'cwtd', 'cltd', 'cltq', and 'cqto' in AT&T -naming. 'as' accepts either naming for these instructions. - - Far call/jump instructions are 'lcall' and 'ljmp' in AT&T syntax, but -are 'call far' and 'jump far' in Intel convention. - -9.4 Register Naming -=================== - -Register operands are always prefixed with '%'. The 80386 registers -consist of - - * the 8 32-bit registers '%eax' (the accumulator), '%ebx', '%ecx', - '%edx', '%edi', '%esi', '%ebp' (the frame pointer), and '%esp' (the - stack pointer). - - * the 8 16-bit low-ends of these: '%ax', '%bx', '%cx', '%dx', '%di', - '%si', '%bp', and '%sp'. - - * the 8 8-bit registers: '%ah', '%al', '%bh', '%bl', '%ch', '%cl', - '%dh', and '%dl' (These are the high-bytes and low-bytes of '%ax', - '%bx', '%cx', and '%dx') - - * the 6 section registers '%cs' (code section), '%ds' (data section), - '%ss' (stack section), '%es', '%fs', and '%gs'. - - * the 3 processor control registers '%cr0', '%cr2', and '%cr3'. - - * the 6 debug registers '%db0', '%db1', '%db2', '%db3', '%db6', and - '%db7'. - - * the 2 test registers '%tr6' and '%tr7'. - - * the 8 floating point register stack '%st' or equivalently '%st(0)', - '%st(1)', '%st(2)', '%st(3)', '%st(4)', '%st(5)', '%st(6)', and - '%st(7)'. These registers are overloaded by 8 MMX registers - '%mm0', '%mm1', '%mm2', '%mm3', '%mm4', '%mm5', '%mm6' and '%mm7'. - - * the 8 SSE registers registers '%xmm0', '%xmm1', '%xmm2', '%xmm3', - '%xmm4', '%xmm5', '%xmm6' and '%xmm7'. - - The AMD x86-64 architecture extends the register set by: - - * enhancing the 8 32-bit registers to 64-bit: '%rax' (the - accumulator), '%rbx', '%rcx', '%rdx', '%rdi', '%rsi', '%rbp' (the - frame pointer), '%rsp' (the stack pointer) - - * the 8 extended registers '%r8'-'%r15'. - - * the 8 32-bit low ends of the extended registers: '%r8d'-'%r15d' - - * the 8 16-bit low ends of the extended registers: '%r8w'-'%r15w' - - * the 8 8-bit low ends of the extended registers: '%r8b'-'%r15b' - - * the 4 8-bit registers: '%sil', '%dil', '%bpl', '%spl'. - - * the 8 debug registers: '%db8'-'%db15'. - - * the 8 SSE registers: '%xmm8'-'%xmm15'. - -9.5 Instruction Prefixes -======================== - -Instruction prefixes are used to modify the following instruction. They -are used to repeat string instructions, to provide section overrides, to -perform bus lock operations, and to change operand and address sizes. -(Most instructions that normally operate on 32-bit operands will use -16-bit operands if the instruction has an "operand size" prefix.) -Instruction prefixes are best written on the same line as the -instruction they act upon. For example, the 'scas' (scan string) -instruction is repeated with: - - repne scas %es:(%edi),%al - - You may also place prefixes on the lines immediately preceding the -instruction, but this circumvents checks that 'as' does with prefixes, -and will not work with all prefixes. - - Here is a list of instruction prefixes: - - * Section override prefixes 'cs', 'ds', 'ss', 'es', 'fs', 'gs'. - These are automatically added by specifying using the - SECTION:MEMORY-OPERAND form for memory references. - - * Operand/Address size prefixes 'data16' and 'addr16' change 32-bit - operands/addresses into 16-bit operands/addresses, while 'data32' - and 'addr32' change 16-bit ones (in a '.code16' section) into - 32-bit operands/addresses. These prefixes _must_ appear on the - same line of code as the instruction they modify. For example, in - a 16-bit '.code16' section, you might write: - - addr32 jmpl *(%ebx) - - * The bus lock prefix 'lock' inhibits interrupts during execution of - the instruction it precedes. (This is only valid with certain - instructions; see a 80386 manual for details). - - * The wait for coprocessor prefix 'wait' waits for the coprocessor to - complete the current instruction. This should never be needed for - the 80386/80387 combination. - - * The 'rep', 'repe', and 'repne' prefixes are added to string - instructions to make them repeat '%ecx' times ('%cx' times if the - current address size is 16-bits). - * The 'rex' family of prefixes is used by x86-64 to encode extensions - to i386 instruction set. The 'rex' prefix has four bits -- an - operand size overwrite ('64') used to change operand size from - 32-bit to 64-bit and X, Y and Z extensions bits used to extend the - register set. - - You may write the 'rex' prefixes directly. The 'rex64xyz' - instruction emits 'rex' prefix with all the bits set. By omitting - the '64', 'x', 'y' or 'z' you may write other prefixes as well. - Normally, there is no need to write the prefixes explicitly, since - gas will automatically generate them based on the instruction - operands. - -9.6 Memory References -===================== - -An Intel syntax indirect memory reference of the form - - SECTION:[BASE + INDEX*SCALE + DISP] - -is translated into the AT&T syntax - - SECTION:DISP(BASE, INDEX, SCALE) - -where BASE and INDEX are the optional 32-bit base and index registers, -DISP is the optional displacement, and SCALE, taking the values 1, 2, 4, -and 8, multiplies INDEX to calculate the address of the operand. If no -SCALE is specified, SCALE is taken to be 1. SECTION specifies the -optional section register for the memory operand, and may override the -default section register (see a 80386 manual for section register -defaults). Note that section overrides in AT&T syntax _must_ be -preceded by a '%'. If you specify a section override which coincides -with the default section register, 'as' does _not_ output any section -register override prefixes to assemble the given instruction. Thus, -section overrides can be specified to emphasize which section register -is used for a given memory operand. - - Here are some examples of Intel and AT&T style memory references: - -AT&T: '-4(%ebp)', Intel: '[ebp - 4]' - BASE is '%ebp'; DISP is '-4'. SECTION is missing, and the default - section is used ('%ss' for addressing with '%ebp' as the base - register). INDEX, SCALE are both missing. - -AT&T: 'foo(,%eax,4)', Intel: '[foo + eax*4]' - INDEX is '%eax' (scaled by a SCALE 4); DISP is 'foo'. All other - fields are missing. The section register here defaults to '%ds'. - -AT&T: 'foo(,1)'; Intel '[foo]' - This uses the value pointed to by 'foo' as a memory operand. Note - that BASE and INDEX are both missing, but there is only _one_ ','. - This is a syntactic exception. - -AT&T: '%gs:foo'; Intel 'gs:foo' - This selects the contents of the variable 'foo' with section - register SECTION being '%gs'. - - Absolute (as opposed to PC relative) call and jump operands must be -prefixed with '*'. If no '*' is specified, 'as' always chooses PC -relative addressing for jump/call labels. - - Any instruction that has a memory operand, but no register operand, -_must_ specify its size (byte, word, long, or quadruple) with an -instruction mnemonic suffix ('b', 'w', 'l' or 'q', respectively). - - The x86-64 architecture adds an RIP (instruction pointer relative) -addressing. This addressing mode is specified by using 'rip' as a base -register. Only constant offsets are valid. For example: - -AT&T: '1234(%rip)', Intel: '[rip + 1234]' - Points to the address 1234 bytes past the end of the current - instruction. - -AT&T: 'symbol(%rip)', Intel: '[rip + symbol]' - Points to the 'symbol' in RIP relative way, this is shorter than - the default absolute addressing. - - Other addressing modes remain unchanged in x86-64 architecture, -except registers used are 64-bit instead of 32-bit. - -9.7 Handling of Jump Instructions -================================= - -Jump instructions are always optimized to use the smallest possible -displacements. This is accomplished by using byte (8-bit) displacement -jumps whenever the target is sufficiently close. If a byte displacement -is insufficient a long displacement is used. We do not support word -(16-bit) displacement jumps in 32-bit mode (i.e. prefixing the jump -instruction with the 'data16' instruction prefix), since the 80386 -insists upon masking '%eip' to 16 bits after the word displacement is -added. (See also *note i386-Arch::) - - Note that the 'jcxz', 'jecxz', 'loop', 'loopz', 'loope', 'loopnz' and -'loopne' instructions only come in byte displacements, so that if you -use these instructions ('gcc' does not use them) you may get an error -message (and incorrect code). The AT&T 80386 assembler tries to get -around this problem by expanding 'jcxz foo' to - - jcxz cx_zero - jmp cx_nonzero - cx_zero: jmp foo - cx_nonzero: - -9.8 Floating Point -================== - -All 80387 floating point types except packed BCD are supported. (BCD -support may be added without much difficulty). These data types are -16-, 32-, and 64- bit integers, and single (32-bit), double (64-bit), -and extended (80-bit) precision floating point. Each supported type has -an instruction mnemonic suffix and a constructor associated with it. -Instruction mnemonic suffixes specify the operand's data type. -Constructors build these data types into memory. - - * Floating point constructors are '.float' or '.single', '.double', - and '.tfloat' for 32-, 64-, and 80-bit formats. These correspond - to instruction mnemonic suffixes 's', 'l', and 't'. 't' stands for - 80-bit (ten byte) real. The 80387 only supports this format via - the 'fldt' (load 80-bit real to stack top) and 'fstpt' (store - 80-bit real and pop stack) instructions. - - * Integer constructors are '.word', '.long' or '.int', and '.quad' - for the 16-, 32-, and 64-bit integer formats. The corresponding - instruction mnemonic suffixes are 's' (single), 'l' (long), and 'q' - (quad). As with the 80-bit real format, the 64-bit 'q' format is - only present in the 'fildq' (load quad integer to stack top) and - 'fistpq' (store quad integer and pop stack) instructions. - - Register to register operations should not use instruction mnemonic -suffixes. 'fstl %st, %st(1)' will give a warning, and be assembled as -if you wrote 'fst %st, %st(1)', since all register to register -operations use 80-bit floating point operands. (Contrast this with -'fstl %st, mem', which converts '%st' from 80-bit to 64-bit floating -point format, then stores the result in the 4 byte location 'mem') - -9.9 Intel's MMX and AMD's 3DNow! SIMD Operations -================================================ - -'as' supports Intel's MMX instruction set (SIMD instructions for integer -data), available on Intel's Pentium MMX processors and Pentium II -processors, AMD's K6 and K6-2 processors, Cyrix' M2 processor, and -probably others. It also supports AMD's 3DNow! instruction set (SIMD -instructions for 32-bit floating point data) available on AMD's K6-2 -processor and possibly others in the future. - - Currently, 'as' does not support Intel's floating point SIMD, Katmai -(KNI). - - The eight 64-bit MMX operands, also used by 3DNow!, are called -'%mm0', '%mm1', ... '%mm7'. They contain eight 8-bit integers, four -16-bit integers, two 32-bit integers, one 64-bit integer, or two 32-bit -floating point values. The MMX registers cannot be used at the same -time as the floating point stack. - - See Intel and AMD documentation, keeping in mind that the operand -order in instructions is reversed from the Intel syntax. - -9.10 Writing 16-bit Code -======================== - -While 'as' normally writes only "pure" 32-bit i386 code or 64-bit x86-64 -code depending on the default configuration, it also supports writing -code to run in real mode or in 16-bit protected mode code segments. To -do this, put a '.code16' or '.code16gcc' directive before the assembly -language instructions to be run in 16-bit mode. You can switch 'as' -back to writing normal 32-bit code with the '.code32' directive. - - '.code16gcc' provides experimental support for generating 16-bit code -from gcc, and differs from '.code16' in that 'call', 'ret', 'enter', -'leave', 'push', 'pop', 'pusha', 'popa', 'pushf', and 'popf' -instructions default to 32-bit size. This is so that the stack pointer -is manipulated in the same way over function calls, allowing access to -function parameters at the same stack offsets as in 32-bit mode. -'.code16gcc' also automatically adds address size prefixes where -necessary to use the 32-bit addressing modes that gcc generates. - - The code which 'as' generates in 16-bit mode will not necessarily run -on a 16-bit pre-80386 processor. To write code that runs on such a -processor, you must refrain from using _any_ 32-bit constructs which -require 'as' to output address or operand size prefixes. - - Note that writing 16-bit code instructions by explicitly specifying a -prefix or an instruction mnemonic suffix within a 32-bit code section -generates different machine instructions than those generated for a -16-bit code segment. In a 32-bit code section, the following code -generates the machine opcode bytes '66 6a 04', which pushes the value -'4' onto the stack, decrementing '%esp' by 2. - - pushw $4 - - The same code in a 16-bit code section would generate the machine -opcode bytes '6a 04' (i.e., without the operand size prefix), which is -correct since the processor default operand size is assumed to be 16 -bits in a 16-bit code section. - -9.11 AT&T Syntax bugs -===================== - -The UnixWare assembler, and probably other AT&T derived ix86 Unix -assemblers, generate floating point instructions with reversed source -and destination registers in certain cases. Unfortunately, gcc and -possibly many other programs use this reversed syntax, so we're stuck -with it. - - For example - - fsub %st,%st(3) -results in '%st(3)' being updated to '%st - %st(3)' rather than the -expected '%st(3) - %st'. This happens with all the non-commutative -arithmetic floating point operations with two register operands where -the source register is '%st' and the destination register is '%st(i)'. - -9.12 Specifying CPU Architecture -================================ - -'as' may be told to assemble for a particular CPU (sub-)architecture -with the '.arch CPU_TYPE' directive. This directive enables a warning -when gas detects an instruction that is not supported on the CPU -specified. The choices for CPU_TYPE are: - -'i8086' 'i186' 'i286' 'i386' -'i486' 'i586' 'i686' 'pentium' -'pentiumpro' 'pentiumii' 'pentiumiii' 'pentium4' -'prescott' 'nocona' 'core' 'core2' -'amdfam10' -'k6' 'athlon' 'sledgehammer' 'k8' -'.mmx' '.sse' '.sse2' '.sse3' -'.ssse3' '.sse4.1' '.sse4.2' '.sse4' -'.sse4a' '.3dnow' '.3dnowa' '.padlock' -'.pacifica' '.svme' '.abm' - - Apart from the warning, there are only two other effects on 'as' -operation; Firstly, if you specify a CPU other than 'i486', then shift -by one instructions such as 'sarl $1, %eax' will automatically use a two -byte opcode sequence. The larger three byte opcode sequence is used on -the 486 (and when no architecture is specified) because it executes -faster on the 486. Note that you can explicitly request the two byte -opcode by writing 'sarl %eax'. Secondly, if you specify 'i8086', -'i186', or 'i286', _and_ '.code16' or '.code16gcc' then byte offset -conditional jumps will be promoted when necessary to a two instruction -sequence consisting of a conditional jump of the opposite sense around -an unconditional jump to the target. - - Following the CPU architecture (but not a sub-architecture, which are -those starting with a dot), you may specify 'jumps' or 'nojumps' to -control automatic promotion of conditional jumps. 'jumps' is the -default, and enables jump promotion; All external jumps will be of the -long variety, and file-local jumps will be promoted as necessary. -(*note i386-Jumps::) 'nojumps' leaves external conditional jumps as byte -offset jumps, and warns about file-local conditional jumps that 'as' -promotes. Unconditional jumps are treated as for 'jumps'. - - For example - - .arch i8086,nojumps - -9.13 Notes -========== - -There is some trickery concerning the 'mul' and 'imul' instructions that -deserves mention. The 16-, 32-, 64- and 128-bit expanding multiplies -(base opcode '0xf6'; extension 4 for 'mul' and 5 for 'imul') can be -output only in the one operand form. Thus, 'imul %ebx, %eax' does _not_ -select the expanding multiply; the expanding multiply would clobber the -'%edx' register, and this would confuse 'gcc' output. Use 'imul %ebx' -to get the 64-bit product in '%edx:%eax'. - - We have added a two operand form of 'imul' when the first operand is -an immediate mode expression and the second operand is a register. This -is just a shorthand, so that, multiplying '%eax' by 69, for example, can -be done with 'imul $69, %eax' rather than 'imul $69, %eax, %eax'. - -10 IA-64 Dependent Features -*************************** - -10.1 Options -============ - -'-mconstant-gp' - This option instructs the assembler to mark the resulting object - file as using the "constant GP" model. With this model, it is - assumed that the entire program uses a single global pointer (GP) - value. Note that this option does not in any fashion affect the - machine code emitted by the assembler. All it does is turn on the - EF_IA_64_CONS_GP flag in the ELF file header. - -'-mauto-pic' - This option instructs the assembler to mark the resulting object - file as using the "constant GP without function descriptor" data - model. This model is like the "constant GP" model, except that it - additionally does away with function descriptors. What this means - is that the address of a function refers directly to the function's - code entry-point. Normally, such an address would refer to a - function descriptor, which contains both the code entry-point and - the GP-value needed by the function. Note that this option does - not in any fashion affect the machine code emitted by the - assembler. All it does is turn on the EF_IA_64_NOFUNCDESC_CONS_GP - flag in the ELF file header. - -'-milp32' -'-milp64' -'-mlp64' -'-mp64' - These options select the data model. The assembler defaults to - '-mlp64' (LP64 data model). - -'-mle' -'-mbe' - These options select the byte order. The '-mle' option selects - little-endian byte order (default) and '-mbe' selects big-endian - byte order. Note that IA-64 machine code always uses little-endian - byte order. - -'-mtune=itanium1' -'-mtune=itanium2' - Tune for a particular IA-64 CPU, ITANIUM1 or ITANIUM2. The default - is ITANIUM2. - -'-munwind-check=warning' -'-munwind-check=error' - These options control what the assembler will do when performing - consistency checks on unwind directives. '-munwind-check=warning' - will make the assembler issue a warning when an unwind directive - check fails. This is the default. '-munwind-check=error' will - make the assembler issue an error when an unwind directive check - fails. - -'-mhint.b=ok' -'-mhint.b=warning' -'-mhint.b=error' - These options control what the assembler will do when the 'hint.b' - instruction is used. '-mhint.b=ok' will make the assembler accept - 'hint.b'. '-mint.b=warning' will make the assembler issue a - warning when 'hint.b' is used. '-mhint.b=error' will make the - assembler treat 'hint.b' as an error, which is the default. - -'-x' -'-xexplicit' - These options turn on dependency violation checking. - -'-xauto' - This option instructs the assembler to automatically insert stop - bits where necessary to remove dependency violations. This is the - default mode. - -'-xnone' - This option turns off dependency violation checking. - -'-xdebug' - This turns on debug output intended to help tracking down bugs in - the dependency violation checker. - -'-xdebugn' - This is a shortcut for -xnone -xdebug. - -'-xdebugx' - This is a shortcut for -xexplicit -xdebug. - -10.2 Syntax -=========== - -The assembler syntax closely follows the IA-64 Assembly Language -Reference Guide. - -10.2.1 Special Characters -------------------------- - -'//' is the line comment token. - - ';' can be used instead of a newline to separate statements. - -10.2.2 Register Names ---------------------- - -The 128 integer registers are referred to as 'rN'. The 128 -floating-point registers are referred to as 'fN'. The 128 application -registers are referred to as 'arN'. The 128 control registers are -referred to as 'crN'. The 64 one-bit predicate registers are referred -to as 'pN'. The 8 branch registers are referred to as 'bN'. In -addition, the assembler defines a number of aliases: 'gp' ('r1'), 'sp' -('r12'), 'rp' ('b0'), 'ret0' ('r8'), 'ret1' ('r9'), 'ret2' ('r10'), -'ret3' ('r9'), 'fargN' ('f8+N'), and 'fretN' ('f8+N'). - - For convenience, the assembler also defines aliases for all named -application and control registers. For example, 'ar.bsp' refers to the -register backing store pointer ('ar17'). Similarly, 'cr.eoi' refers to -the end-of-interrupt register ('cr67'). - -10.2.3 IA-64 Processor-Status-Register (PSR) Bit Names ------------------------------------------------------- - -The assembler defines bit masks for each of the bits in the IA-64 -processor status register. For example, 'psr.ic' corresponds to a value -of 0x2000. These masks are primarily intended for use with the -'ssm'/'sum' and 'rsm'/'rum' instructions, but they can be used anywhere -else where an integer constant is expected. - -10.3 Opcodes -============ - -For detailed information on the IA-64 machine instruction set, see the -IA-64 Architecture Handbook -(http://developer.intel.com/design/itanium/arch_spec.htm). - -11 MIPS Dependent Features -************************** - -GNU 'as' for MIPS architectures supports several different MIPS -processors, and MIPS ISA levels I through V, MIPS32, and MIPS64. For -information about the MIPS instruction set, see 'MIPS RISC -Architecture', by Kane and Heindrich (Prentice-Hall). For an overview -of MIPS assembly conventions, see "Appendix D: Assembly Language -Programming" in the same work. - -11.1 Assembler options -====================== - -The MIPS configurations of GNU 'as' support these special options: - -'-G NUM' - This option sets the largest size of an object that can be - referenced implicitly with the 'gp' register. It is only accepted - for targets that use ECOFF format. The default value is 8. - -'-EB' -'-EL' - Any MIPS configuration of 'as' can select big-endian or - little-endian output at run time (unlike the other GNU development - tools, which must be configured for one or the other). Use '-EB' - to select big-endian output, and '-EL' for little-endian. - -'-KPIC' - Generate SVR4-style PIC. This option tells the assembler to - generate SVR4-style position-independent macro expansions. It also - tells the assembler to mark the output file as PIC. - -'-mvxworks-pic' - Generate VxWorks PIC. This option tells the assembler to generate - VxWorks-style position-independent macro expansions. - -'-mips1' -'-mips2' -'-mips3' -'-mips4' -'-mips5' -'-mips32' -'-mips32r2' -'-mips64' -'-mips64r2' - Generate code for a particular MIPS Instruction Set Architecture - level. '-mips1' corresponds to the R2000 and R3000 processors, - '-mips2' to the R6000 processor, '-mips3' to the R4000 processor, - and '-mips4' to the R8000 and R10000 processors. '-mips5', - '-mips32', '-mips32r2', '-mips64', and '-mips64r2' correspond to - generic MIPS V, MIPS32, MIPS32 RELEASE 2, MIPS64, and MIPS64 - RELEASE 2 ISA processors, respectively. You can also switch - instruction sets during the assembly; see *note Directives to - override the ISA level: MIPS ISA. - -'-mgp32' -'-mfp32' - Some macros have different expansions for 32-bit and 64-bit - registers. The register sizes are normally inferred from the ISA - and ABI, but these flags force a certain group of registers to be - treated as 32 bits wide at all times. '-mgp32' controls the size - of general-purpose registers and '-mfp32' controls the size of - floating-point registers. - - The '.set gp=32' and '.set fp=32' directives allow the size of - registers to be changed for parts of an object. The default value - is restored by '.set gp=default' and '.set fp=default'. - - On some MIPS variants there is a 32-bit mode flag; when this flag - is set, 64-bit instructions generate a trap. Also, some 32-bit - OSes only save the 32-bit registers on a context switch, so it is - essential never to use the 64-bit registers. - -'-mgp64' -'-mfp64' - Assume that 64-bit registers are available. This is provided in - the interests of symmetry with '-mgp32' and '-mfp32'. - - The '.set gp=64' and '.set fp=64' directives allow the size of - registers to be changed for parts of an object. The default value - is restored by '.set gp=default' and '.set fp=default'. - -'-mips16' -'-no-mips16' - Generate code for the MIPS 16 processor. This is equivalent to - putting '.set mips16' at the start of the assembly file. - '-no-mips16' turns off this option. - -'-msmartmips' -'-mno-smartmips' - Enables the SmartMIPS extensions to the MIPS32 instruction set, - which provides a number of new instructions which target smartcard - and cryptographic applications. This is equivalent to putting - '.set smartmips' at the start of the assembly file. - '-mno-smartmips' turns off this option. - -'-mips3d' -'-no-mips3d' - Generate code for the MIPS-3D Application Specific Extension. This - tells the assembler to accept MIPS-3D instructions. '-no-mips3d' - turns off this option. - -'-mdmx' -'-no-mdmx' - Generate code for the MDMX Application Specific Extension. This - tells the assembler to accept MDMX instructions. '-no-mdmx' turns - off this option. - -'-mdsp' -'-mno-dsp' - Generate code for the DSP Release 1 Application Specific Extension. - This tells the assembler to accept DSP Release 1 instructions. - '-mno-dsp' turns off this option. - -'-mdspr2' -'-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. '-mno-dspr2' turns off this option. - -'-mmt' -'-mno-mt' - Generate code for the MT Application Specific Extension. This - tells the assembler to accept MT instructions. '-mno-mt' turns off - this option. - -'-mfix7000' -'-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. - -'-mfix-vr4120' -'-no-mfix-vr4120' - Insert nops to work around certain VR4120 errata. This option is - intended to be used on GCC-generated code: it is not designed to - catch all problems in hand-written assembler code. - -'-mfix-vr4130' -'-no-mfix-vr4130' - Insert nops to work around the VR4130 'mflo'/'mfhi' errata. - -'-m4010' -'-no-m4010' - Generate code for the LSI R4010 chip. This tells the assembler to - accept the R4010 specific instructions ('addciu', 'ffc', etc.), and - to not schedule 'nop' instructions around accesses to the 'HI' and - 'LO' registers. '-no-m4010' turns off this option. - -'-m4650' -'-no-m4650' - Generate code for the MIPS R4650 chip. This tells the assembler to - accept the 'mad' and 'madu' instruction, and to not schedule 'nop' - instructions around accesses to the 'HI' and 'LO' registers. - '-no-m4650' turns off this option. - -'-m3900' -'-no-m3900' -'-m4100' -'-no-m4100' - For each option '-mNNNN', generate code for the MIPS RNNNN chip. - This tells the assembler to accept instructions specific to that - chip, and to schedule for that chip's hazards. - -'-march=CPU' - Generate code for a particular MIPS cpu. It is exactly equivalent - to '-mCPU', except that there are more value of CPU understood. - Valid CPU value are: - - 2000, 3000, 3900, 4000, 4010, 4100, 4111, vr4120, vr4130, - vr4181, 4300, 4400, 4600, 4650, 5000, rm5200, rm5230, rm5231, - rm5261, rm5721, vr5400, vr5500, 6000, rm7000, 8000, rm9000, - 10000, 12000, 4kc, 4km, 4kp, 4ksc, 4kec, 4kem, 4kep, 4ksd, - m4k, m4kp, 24kc, 24kf, 24kx, 24kec, 24kef, 24kex, 34kc, 34kf, - 34kx, 74kc, 74kf, 74kx, 5kc, 5kf, 20kc, 25kf, sb1, sb1a - -'-mtune=CPU' - Schedule and tune for a particular MIPS cpu. Valid CPU values are - identical to '-march=CPU'. - -'-mabi=ABI' - Record which ABI the source code uses. The recognized arguments - are: '32', 'n32', 'o64', '64' and 'eabi'. - -'-msym32' -'-mno-sym32' - Equivalent to adding '.set sym32' or '.set nosym32' to the - beginning of the assembler input. *Note MIPS symbol sizes::. - -'-nocpp' - This option is ignored. It is accepted for command-line - compatibility with other assemblers, which use it to turn off C - style preprocessing. With GNU 'as', there is no need for '-nocpp', - because the GNU assembler itself never runs the C preprocessor. - -'--construct-floats' -'--no-construct-floats' - The '--no-construct-floats' option disables the construction of - double width floating point constants by loading the two halves of - the value into the two single width floating point registers that - make up the double width register. This feature is useful if the - processor support the FR bit in its status register, and this bit - is known (by the programmer) to be set. This bit prevents the - aliasing of the double width register by the single width - registers. - - By default '--construct-floats' is selected, allowing construction - of these floating point constants. - -'--trap' -'--no-break' - 'as' automatically macro expands certain division and - multiplication instructions to check for overflow and division by - zero. This option causes 'as' to generate code to take a trap - exception rather than a break exception when an error is detected. - The trap instructions are only supported at Instruction Set - Architecture level 2 and higher. - -'--break' -'--no-trap' - Generate code to take a break exception rather than a trap - exception when an error is detected. This is the default. - -'-mpdr' -'-mno-pdr' - Control generation of '.pdr' sections. Off by default on IRIX, on - elsewhere. - -'-mshared' -'-mno-shared' - When generating code using the Unix calling conventions (selected - by '-KPIC' or '-mcall_shared'), gas will normally generate code - which can go into a shared library. The '-mno-shared' option tells - gas to generate code which uses the calling convention, but can not - go into a shared library. The resulting code is slightly more - efficient. This option only affects the handling of the '.cpload' - and '.cpsetup' pseudo-ops. - -11.2 MIPS ECOFF object code -=========================== - -Assembling for a MIPS ECOFF target supports some additional sections -besides the usual '.text', '.data' and '.bss'. The additional sections -are '.rdata', used for read-only data, '.sdata', used for small data, -and '.sbss', used for small common objects. - - When assembling for ECOFF, the assembler uses the '$gp' ('$28') -register to form the address of a "small object". Any object in the -'.sdata' or '.sbss' sections is considered "small" in this sense. For -external objects, or for objects in the '.bss' section, you can use the -'gcc' '-G' option to control the size of objects addressed via '$gp'; -the default value is 8, meaning that a reference to any object eight -bytes or smaller uses '$gp'. Passing '-G 0' to 'as' prevents it from -using the '$gp' register on the basis of object size (but the assembler -uses '$gp' for objects in '.sdata' or 'sbss' in any case). The size of -an object in the '.bss' section is set by the '.comm' or '.lcomm' -directive that defines it. The size of an external object may be set -with the '.extern' directive. For example, '.extern sym,4' declares -that the object at 'sym' is 4 bytes in length, whie leaving 'sym' -otherwise undefined. - - Using small ECOFF objects requires linker support, and assumes that -the '$gp' register is correctly initialized (normally done automatically -by the startup code). MIPS ECOFF assembly code must not modify the -'$gp' register. - -11.3 Directives for debugging information -========================================= - -MIPS ECOFF 'as' supports several directives used for generating -debugging information which are not support by traditional MIPS -assemblers. These are '.def', '.endef', '.dim', '.file', '.scl', -'.size', '.tag', '.type', '.val', '.stabd', '.stabn', and '.stabs'. The -debugging information generated by the three '.stab' directives can only -be read by GDB, not by traditional MIPS debuggers (this enhancement is -required to fully support C++ debugging). These directives are -primarily used by compilers, not assembly language programmers! - -11.4 Directives to override the size of symbols -=============================================== - -The n64 ABI allows symbols to have any 64-bit value. Although this -provides a great deal of flexibility, it means that some macros have -much longer expansions than their 32-bit counterparts. For example, the -non-PIC expansion of 'dla $4,sym' is usually: - - lui $4,%highest(sym) - lui $1,%hi(sym) - daddiu $4,$4,%higher(sym) - daddiu $1,$1,%lo(sym) - dsll32 $4,$4,0 - daddu $4,$4,$1 - - whereas the 32-bit expansion is simply: - - lui $4,%hi(sym) - daddiu $4,$4,%lo(sym) - - n64 code is sometimes constructed in such a way that all symbolic -constants are known to have 32-bit values, and in such cases, it's -preferable to use the 32-bit expansion instead of the 64-bit expansion. - - You can use the '.set sym32' directive to tell the assembler that, -from this point on, all expressions of the form 'SYMBOL' or 'SYMBOL + -OFFSET' have 32-bit values. For example: - - .set sym32 - dla $4,sym - lw $4,sym+16 - sw $4,sym+0x8000($4) - - will cause the assembler to treat 'sym', 'sym+16' and 'sym+0x8000' as -32-bit values. The handling of non-symbolic addresses is not affected. - - The directive '.set nosym32' ends a '.set sym32' block and reverts to -the normal behavior. It is also possible to change the symbol size -using the command-line options '-msym32' and '-mno-sym32'. - - These options and directives are always accepted, but at present, -they have no effect for anything other than n64. - -11.5 Directives to override the ISA level -========================================= - -GNU 'as' supports an additional directive to change the MIPS Instruction -Set Architecture level on the fly: '.set mipsN'. N should be a number -from 0 to 5, or 32, 32r2, 64 or 64r2. The values other than 0 make the -assembler accept instructions for the corresponding ISA level, from that -point on in the assembly. '.set mipsN' affects not only which -instructions are permitted, but also how certain macros are expanded. -'.set mips0' restores the ISA level to its original level: either the -level you selected with command line options, or the default for your -configuration. You can use this feature to permit specific MIPS3 -instructions while assembling in 32 bit mode. Use this directive with -care! - - The '.set arch=CPU' directive provides even finer control. It -changes the effective CPU target and allows the assembler to use -instructions specific to a particular CPU. All CPUs supported by the -'-march' command line option are also selectable by this directive. The -original value is restored by '.set arch=default'. - - The directive '.set mips16' puts the assembler into MIPS 16 mode, in -which it will assemble instructions for the MIPS 16 processor. Use -'.set nomips16' to return to normal 32 bit mode. - - Traditional MIPS assemblers do not support this directive. - -11.6 Directives for extending MIPS 16 bit instructions -====================================================== - -By default, MIPS 16 instructions are automatically extended to 32 bits -when necessary. The directive '.set noautoextend' will turn this off. -When '.set noautoextend' is in effect, any 32 bit instruction must be -explicitly extended with the '.e' modifier (e.g., 'li.e $4,1000'). The -directive '.set autoextend' may be used to once again automatically -extend instructions when necessary. - - This directive is only meaningful when in MIPS 16 mode. Traditional -MIPS assemblers do not support this directive. - -11.7 Directive to mark data as an instruction -============================================= - -The '.insn' directive tells 'as' that the following data is actually -instructions. This makes a difference in MIPS 16 mode: when loading the -address of a label which precedes instructions, 'as' automatically adds -1 to the value, so that jumping to the loaded address will do the right -thing. - -11.8 Directives to save and restore options -=========================================== - -The directives '.set push' and '.set pop' may be used to save and -restore the current settings for all the options which are controlled by -'.set'. The '.set push' directive saves the current settings on a -stack. The '.set pop' directive pops the stack and restores the -settings. - - These directives can be useful inside an macro which must change an -option such as the ISA level or instruction reordering but does not want -to change the state of the code which invoked the macro. - - Traditional MIPS assemblers do not support these directives. - -11.9 Directives to control generation of MIPS ASE instructions -============================================================== - -The directive '.set mips3d' makes the assembler accept instructions from -the MIPS-3D Application Specific Extension from that point on in the -assembly. The '.set nomips3d' directive prevents MIPS-3D instructions -from being accepted. - - The directive '.set smartmips' makes the assembler accept -instructions from the SmartMIPS Application Specific Extension to the -MIPS32 ISA from that point on in the assembly. The '.set nosmartmips' -directive prevents SmartMIPS instructions from being accepted. - - The directive '.set mdmx' makes the assembler accept instructions -from the MDMX Application Specific Extension from that point on in the -assembly. The '.set nomdmx' directive prevents MDMX instructions from -being accepted. - - The directive '.set dsp' makes the assembler accept instructions from -the DSP Release 1 Application Specific Extension from that point on in -the assembly. The '.set nodsp' directive prevents DSP Release 1 -instructions from being accepted. - - The directive '.set dspr2' makes the assembler accept instructions -from the DSP Release 2 Application Specific Extension from that point on -in the assembly. This dirctive implies '.set dsp'. The '.set nodspr2' -directive prevents DSP Release 2 instructions from being accepted. - - The directive '.set mt' makes the assembler accept instructions from -the MT Application Specific Extension from that point on in the -assembly. The '.set nomt' directive prevents MT instructions from being -accepted. - - Traditional MIPS assemblers do not support these directives. - -12 PowerPC Dependent Features -***************************** - -12.1 Options -============ - -The PowerPC chip family includes several successive levels, using the -same core instruction set, but including a few additional instructions -at each level. There are exceptions to this however. For details on -what instructions each variant supports, please see the chip's -architecture reference manual. - - The following table lists all available PowerPC options. - -'-mpwrx | -mpwr2' - Generate code for POWER/2 (RIOS2). - -'-mpwr' - Generate code for POWER (RIOS1) - -'-m601' - Generate code for PowerPC 601. - -'-mppc, -mppc32, -m603, -m604' - Generate code for PowerPC 603/604. - -'-m403, -m405' - Generate code for PowerPC 403/405. - -'-m440' - Generate code for PowerPC 440. BookE and some 405 instructions. - -'-m7400, -m7410, -m7450, -m7455' - Generate code for PowerPC 7400/7410/7450/7455. - -'-mppc64, -m620' - Generate code for PowerPC 620/625/630. - -'-me500, -me500x2' - Generate code for Motorola e500 core complex. - -'-mspe' - Generate code for Motorola SPE instructions. - -'-mppc64bridge' - Generate code for PowerPC 64, including bridge insns. - -'-mbooke64' - Generate code for 64-bit BookE. - -'-mbooke, mbooke32' - Generate code for 32-bit BookE. - -'-me300' - Generate code for PowerPC e300 family. - -'-maltivec' - Generate code for processors with AltiVec instructions. - -'-mpower4' - Generate code for Power4 architecture. - -'-mpower5' - Generate code for Power5 architecture. - -'-mpower6' - Generate code for Power6 architecture. - -'-mcell' - Generate code for Cell Broadband Engine architecture. - -'-mcom' - Generate code Power/PowerPC common instructions. - -'-many' - Generate code for any architecture (PWR/PWRX/PPC). - -'-mregnames' - Allow symbolic names for registers. - -'-mno-regnames' - Do not allow symbolic names for registers. - -'-mrelocatable' - Support for GCC's -mrelocatable option. - -'-mrelocatable-lib' - Support for GCC's -mrelocatable-lib option. - -'-memb' - Set PPC_EMB bit in ELF flags. - -'-mlittle, -mlittle-endian' - Generate code for a little endian machine. - -'-mbig, -mbig-endian' - Generate code for a big endian machine. - -'-msolaris' - Generate code for Solaris. - -'-mno-solaris' - Do not generate code for Solaris. - -12.2 PowerPC Assembler Directives -================================= - -A number of assembler directives are available for PowerPC. The -following table is far from complete. - -'.machine "string"' - This directive allows you to change the machine for which code is - generated. '"string"' may be any of the -m cpu selection options - (without the -m) enclosed in double quotes, '"push"', or '"pop"'. - '.machine "push"' saves the currently selected cpu, which may be - restored with '.machine "pop"'. - -13 SPARC Dependent Features -*************************** - -13.1 Options -============ - -The SPARC chip family includes several successive levels, using the same -core instruction set, but including a few additional instructions at -each level. There are exceptions to this however. For details on what -instructions each variant supports, please see the chip's architecture -reference manual. - - By default, 'as' assumes the core instruction set (SPARC v6), but -"bumps" the architecture level as needed: it switches to successively -higher architectures as it encounters instructions that only exist in -the higher levels. - - If not configured for SPARC v9 ('sparc64-*-*') GAS will not bump -passed sparclite by default, an option must be passed to enable the v9 -instructions. - - GAS treats sparclite as being compatible with v8, unless an -architecture is explicitly requested. SPARC v9 is always incompatible -with sparclite. - -'-Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite' -'-Av8plus | -Av8plusa | -Av9 | -Av9a' - Use one of the '-A' options to select one of the SPARC - architectures explicitly. If you select an architecture - explicitly, 'as' reports a fatal error if it encounters an - instruction or feature requiring an incompatible or higher level. - - '-Av8plus' and '-Av8plusa' select a 32 bit environment. - - '-Av9' and '-Av9a' select a 64 bit environment and are not - available unless GAS is explicitly configured with 64 bit - environment support. - - '-Av8plusa' and '-Av9a' enable the SPARC V9 instruction set with - UltraSPARC extensions. - -'-xarch=v8plus | -xarch=v8plusa' - For compatibility with the Solaris v9 assembler. These options are - equivalent to -Av8plus and -Av8plusa, respectively. - -'-bump' - Warn whenever it is necessary to switch to another level. If an - architecture level is explicitly requested, GAS will not issue - warnings until that level is reached, and will then bump the level - as required (except between incompatible levels). - -'-32 | -64' - Select the word size, either 32 bits or 64 bits. These options are - only available with the ELF object file format, and require that - the necessary BFD support has been included. - -13.2 Enforcing aligned data -=========================== - -SPARC GAS normally permits data to be misaligned. For example, it -permits the '.long' pseudo-op to be used on a byte boundary. However, -the native SunOS and Solaris assemblers issue an error when they see -misaligned data. - - You can use the '--enforce-aligned-data' option to make SPARC GAS -also issue an error about misaligned data, just as the SunOS and Solaris -assemblers do. - - The '--enforce-aligned-data' option is not the default because gcc -issues misaligned data pseudo-ops when it initializes certain packed -data structures (structures defined using the 'packed' attribute). You -may have to assemble with GAS in order to initialize packed data -structures in your own code. - -13.3 Floating Point -=================== - -The Sparc uses IEEE floating-point numbers. - -13.4 Sparc Machine Directives -============================= - -The Sparc version of 'as' supports the following additional machine -directives: - -'.align' - This must be followed by the desired alignment in bytes. - -'.common' - This must be followed by a symbol name, a positive number, and - '"bss"'. This behaves somewhat like '.comm', but the syntax is - different. - -'.half' - This is functionally identical to '.short'. - -'.nword' - On the Sparc, the '.nword' directive produces native word sized - value, ie. if assembling with -32 it is equivalent to '.word', if - assembling with -64 it is equivalent to '.xword'. - -'.proc' - This directive is ignored. Any text following it on the same line - is also ignored. - -'.register' - This directive declares use of a global application or system - register. It must be followed by a register name %g2, %g3, %g6 or - %g7, comma and the symbol name for that register. If symbol name - is '#scratch', it is a scratch register, if it is '#ignore', it - just suppresses any errors about using undeclared global register, - but does not emit any information about it into the object file. - This can be useful e.g. if you save the register before use and - restore it after. - -'.reserve' - This must be followed by a symbol name, a positive number, and - '"bss"'. This behaves somewhat like '.lcomm', but the syntax is - different. - -'.seg' - This must be followed by '"text"', '"data"', or '"data1"'. It - behaves like '.text', '.data', or '.data 1'. - -'.skip' - This is functionally identical to the '.space' directive. - -'.word' - On the Sparc, the '.word' directive produces 32 bit values, instead - of the 16 bit values it produces on many other machines. - -'.xword' - On the Sparc V9 processor, the '.xword' directive produces 64 bit - values. - -14 Reporting Bugs -***************** - -Your bug reports play an essential role in making 'as' reliable. - - 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 'as' work -better. Bug reports are your contribution to the maintenance of 'as'. - - In order for a bug report to serve its purpose, you must include the -information that enables us to fix the bug. - -14.1 Have You Found a Bug? -========================== - -If you are not sure whether you have found a bug, here are some -guidelines: - - * If the assembler gets a fatal signal, for any input whatever, that - is a 'as' bug. Reliable assemblers never crash. - - * If 'as' produces an error message for valid input, that is a bug. - - * If 'as' does not produce an error message for invalid input, that - is a bug. However, you should note that your idea of "invalid - input" might be our idea of "an extension" or "support for - traditional practice". - - * If you are an experienced user of assemblers, your suggestions for - improvement of 'as' are welcome in any case. - -14.2 How to Report Bugs -======================= - -A number of companies and individuals offer support for GNU products. -If you obtained 'as' from a support organization, we recommend you -contact that organization first. - - You can find contact information for many support companies and -individuals in the file 'etc/SERVICE' in the GNU Emacs distribution. - - The fundamental principle of reporting bugs usefully is this: *report -all the facts*. If you are not sure whether to state a fact or leave it -out, state it! - - Often people omit facts because they think they know what causes the -problem and assume that some details do not matter. Thus, you might -assume that the name of a symbol you use in an example does not matter. -Well, probably it does not, but one cannot be sure. Perhaps the bug is -a stray memory reference which happens to fetch from the location where -that name is stored in memory; perhaps, if the name were different, the -contents of that location would fool the assembler into doing the right -thing despite the bug. Play it safe and give a specific, complete -example. That is the easiest thing for you to do, and the most helpful. - - 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. - - Sometimes people give a few sketchy facts and ask, "Does this ring a -bell?" 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. - - To enable us to fix the bug, you should include all these things: - - * The version of 'as'. 'as' announces it if you start it with the - '--version' argument. - - Without this, we will not know whether there is any point in - looking for the bug in the current version of 'as'. - - * Any patches you may have applied to the 'as' source. - - * The type of machine you are using, and the operating system name - and version number. - - * What compiler (and its version) was used to compile 'as'--e.g. - "'gcc-2.7'". - - * The command arguments you gave the assembler to assemble your - example and observe the bug. To guarantee you will not omit - something important, list them all. A copy of the Makefile (or the - output from make) is sufficient. - - If we were to try to guess the arguments, we would probably guess - wrong and then we might not encounter the bug. - - * A complete input file that will reproduce the bug. If the bug is - observed when the assembler is invoked via a compiler, send the - assembler source, not the high level language source. Most - compilers will produce the assembler source when run with the '-S' - option. If you are using 'gcc', use the options '-v --save-temps'; - this will save the assembler source in a file with an extension of - '.s', and also show you exactly how 'as' is being run. - - * A description of what behavior you observe that you believe is - incorrect. For example, "It gets a fatal signal." - - Of course, if the bug is that 'as' gets a fatal signal, then we - will certainly notice it. But if the bug is incorrect output, we - might not notice unless it is glaringly wrong. You might as well - not give us a chance to make a mistake. - - 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 'as' is out of sync, or you have encountered - a bug in the C library on your system. (This has happened!) Your - copy might crash and ours would not. If you told us to expect a - crash, then when ours fails to crash, we would know that the bug - was not happening for us. If you had not told us to expect a - crash, then we would not be able to draw any conclusion from our - observations. - - * If you wish to suggest changes to the 'as' source, send us context - diffs, as generated by 'diff' with the '-u', '-c', or '-p' option. - Always send diffs from the old file to the new file. If you even - discuss something in the 'as' source, refer to it by context, not - by line number. - - The line numbers in our development sources will not match those in - your sources. Your line numbers would convey no useful information - to us. - - Here are some things that are not necessary: - - * A description of the envelope of the bug. - - 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. - - 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. - - Of course, if you can find a simpler example to report _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. - - 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. - - * A patch for the bug. - - 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. - - Sometimes with a program as complicated as 'as' it is very hard to - construct an example that will make the program follow a certain - path through the code. If you do not send us the example, we will - not be able to construct one, so we will not be able to verify that - the bug is fixed. - - 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. - - * A guess about what the bug is or what it depends on. - - Such guesses are usually wrong. Even we cannot guess right about - such things without first using the debugger to find the facts. - -15 Acknowledgements -******************* - -If you have contributed to GAS and your name isn't listed here, it is -not meant as a slight. We just don't know about it. Send mail to the -maintainer, and we'll correct the situation. Currently the maintainer -is Ken Raeburn (email address 'raeburn@cygnus.com'). - - Dean Elsner wrote the original GNU assembler for the VAX.(1) - - Jay Fenlason maintained GAS for a while, adding support for -GDB-specific debug information and the 68k series machines, most of the -preprocessing pass, and extensive changes in 'messages.c', -'input-file.c', 'write.c'. - - K. Richard Pixley maintained GAS for a while, adding various -enhancements and many bug fixes, including merging support for several -processors, breaking GAS up to handle multiple object file format back -ends (including heavy rewrite, testing, an integration of the coff and -b.out back ends), adding configuration including heavy testing and -verification of cross assemblers and file splits and renaming, converted -GAS to strictly ANSI C including full prototypes, added support for -m680[34]0 and cpu32, did considerable work on i960 including a COFF port -(including considerable amounts of reverse engineering), a SPARC opcode -file rewrite, DECstation, rs6000, and hp300hpux host ports, updated -"know" assertions and made them work, much other reorganization, -cleanup, and lint. - - Ken Raeburn wrote the high-level BFD interface code to replace most -of the code in format-specific I/O modules. - - The original VMS support was contributed by David L. Kashtan. Eric -Youngdale has done much work with it since. - - The Intel 80386 machine description was written by Eliot Dresselhaus. - - Minh Tran-Le at IntelliCorp contributed some AIX 386 support. - - The Motorola 88k machine description was contributed by Devon Bowen -of Buffalo University and Torbjorn Granlund of the Swedish Institute of -Computer Science. - - Keith Knowles at the Open Software Foundation wrote the original MIPS -back end ('tc-mips.c', 'tc-mips.h'), and contributed Rose format support -(which hasn't been merged in yet). Ralph Campbell worked with the MIPS -code to support a.out format. - - Support for the Zilog Z8k and Renesas H8/300 processors (tc-z8k, -tc-h8300), and IEEE 695 object file format (obj-ieee), was written by -Steve Chamberlain of Cygnus Support. Steve also modified the COFF back -end to use BFD for some low-level operations, for use with the H8/300 -and AMD 29k targets. - - John Gilmore built the AMD 29000 support, added '.include' support, -and simplified the configuration of which versions accept which -directives. He updated the 68k machine description so that Motorola's -opcodes always produced fixed-size instructions (e.g., 'jsr'), while -synthetic instructions remained shrinkable ('jbsr'). John fixed many -bugs, including true tested cross-compilation support, and one bug in -relaxation that took a week and required the proverbial one-bit fix. - - Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntax -for the 68k, completed support for some COFF targets (68k, i386 SVR3, -and SCO Unix), added support for MIPS ECOFF and ELF targets, wrote the -initial RS/6000 and PowerPC assembler, and made a few other minor -patches. - - Steve Chamberlain made GAS able to generate listings. - - Hewlett-Packard contributed support for the HP9000/300. - - Jeff Law wrote GAS and BFD support for the native HPPA object format -(SOM) along with a fairly extensive HPPA testsuite (for both SOM and ELF -object formats). This work was supported by both the Center for -Software Science at the University of Utah and Cygnus Support. - - Support for ELF format files has been worked on by Mark Eichin of -Cygnus Support (original, incomplete implementation for SPARC), Pete -Hoogenboom and Jeff Law at the University of Utah (HPPA mainly), Michael -Meissner of the Open Software Foundation (i386 mainly), and Ken Raeburn -of Cygnus Support (sparc, and some initial 64-bit support). - - Linas Vepstas added GAS support for the ESA/390 "IBM 370" -architecture. - - Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote -GAS and BFD support for openVMS/Alpha. - - Timothy Wall, Michael Hayes, and Greg Smart contributed to the -various tic* flavors. - - David Heine, Sterling Augustine, Bob Wilson and John Ruttenberg from -Tensilica, Inc. added support for Xtensa processors. - - Several engineers at Cygnus Support have also provided many small bug -fixes and configuration enhancements. - - Many others have contributed large or small bugfixes and -enhancements. If you have contributed significant work and are not -mentioned on this list, and want to be, let us know. Some of the -history has been lost; we are not intentionally leaving anyone out. - -Appendix A GNU Free Documentation License -***************************************** - - Version 1.1, March 2000 - - Copyright (C) 2000, 2003 Free Software Foundation, Inc. - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - 0. PREAMBLE - - The purpose of this License is to make a manual, textbook, or other - written document "free" in the sense of freedom: to assure everyone - the effective freedom to copy and redistribute it, with or without - modifying it, either commercially or noncommercially. Secondarily, - this License preserves for the author and publisher a way to get - credit for their work, while not being considered responsible for - modifications made by others. - - This License is a kind of "copyleft", which means that derivative - works of the document must themselves be free in the same sense. - It complements the GNU General Public License, which is a copyleft - license designed for free software. - - 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. - - - 1. APPLICABILITY AND DEFINITIONS - - This License applies to any manual or other work that contains a - notice placed by the copyright holder saying it can be distributed - under the terms of this License. The "Document", below, refers to - any such manual or work. Any member of the public is a licensee, - and is addressed as "you." - - A "Modified Version" of the Document means any work containing the - Document or a portion of it, either copied verbatim, or with - modifications and/or translated into another language. - - A "Secondary Section" is a named appendix or a front-matter section - of the Document that deals exclusively with the relationship of the - publishers or authors of the Document to the Document's overall - subject (or to related matters) and contains nothing that could - fall directly within that overall subject. (For example, if the - Document is in part a textbook of mathematics, a Secondary Section - may not explain any mathematics.) The relationship could be a - matter of historical connection with the subject or with related - matters, or of legal, commercial, philosophical, ethical or - political position regarding them. - - The "Invariant Sections" are certain Secondary Sections whose - titles are designated, as being those of Invariant Sections, in the - notice that says that the Document is released under this License. - - The "Cover Texts" are certain short passages of text that are - listed, as Front-Cover Texts or Back-Cover Texts, in the notice - that says that the Document is released under this License. - - A "Transparent" copy of the Document means a machine-readable copy, - represented in a format whose specification is available to the - general public, whose contents can be viewed and edited directly - and straightforwardly with generic text editors or (for images - composed of pixels) generic paint programs or (for drawings) some - widely available drawing editor, and that is suitable for input to - text formatters or for automatic translation to a variety of - formats suitable for input to text formatters. A copy made in an - otherwise Transparent file format whose markup has been designed to - thwart or discourage subsequent modification by readers is not - Transparent. A copy that is not "Transparent" is called "Opaque." - - 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. - - The "Title Page" means, for a printed book, the title page itself, - plus such following pages as are needed to hold, legibly, the - material this License requires to appear in the title page. For - works in formats which do not have any title page as such, "Title - Page" means the text near the most prominent appearance of the - work's title, preceding the beginning of the body of the text. - - 2. VERBATIM COPYING - - 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. - - You may also lend copies, under the same conditions stated above, - and you may publicly display copies. - - 3. COPYING IN QUANTITY - - 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. - - 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. - - 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. - - 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. - - 4. MODIFICATIONS - - 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: - - A. Use in the Title Page (and on the covers, if any) a title - distinct from that of the Document, and from those of previous - versions (which should, if there were any, be listed in the History - section of the Document). You may use the same title as a previous - version if the original publisher of that version gives permission. - B. List on the Title Page, as authors, one or more persons or - entities responsible for authorship of the modifications in the - Modified Version, together with at least five of the principal - authors of the Document (all of its principal authors, if it has - less than five). - C. State on the Title page the name of the publisher of the - Modified Version, as the publisher. - D. Preserve all the copyright notices of the Document. - E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. - F. Include, immediately after the copyright notices, a license - notice giving the public permission to use the Modified Version - under the terms of this License, in the form shown in the Addendum - below. - G. Preserve in that license notice the full lists of Invariant - Sections and required Cover Texts given in the Document's license - notice. - H. Include an unaltered copy of this License. - I. Preserve the section entitled "History", and its title, and add - to it an item stating at least the title, year, new authors, and - publisher of the Modified Version as given on the Title Page. If - there is no section entitled "History" in the Document, create one - stating the title, year, authors, and publisher of the Document as - given on its Title Page, then add an item describing the Modified - Version as stated in the previous sentence. - J. Preserve the network location, if any, given in the Document for - public access to a Transparent copy of the Document, and likewise - the network locations given in the Document for previous versions - it was based on. These may be placed in the "History" section. - You may omit a network location for a work that was published at - least four years before the Document itself, or if the original - publisher of the version it refers to gives permission. - K. In any section entitled "Acknowledgements" or "Dedications", - preserve the section's title, and preserve in the section all the - substance and tone of each of the contributor acknowledgements - and/or dedications given therein. - L. Preserve all the Invariant Sections of the Document, unaltered - in their text and in their titles. Section numbers or the - equivalent are not considered part of the section titles. - M. Delete any section entitled "Endorsements." Such a section may - not be included in the Modified Version. - N. Do not retitle any existing section as "Endorsements" or to - conflict in title with any Invariant Section. - - 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. - - You may add a section entitled "Endorsements", provided it contains - nothing but endorsements of your Modified Version by various - parties-for example, statements of peer review or that the text has - been approved by an organization as the authoritative definition of - a standard. - - 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. - - 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. - - 5. COMBINING DOCUMENTS - - 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. - - 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. - - In the combination, you must combine any sections entitled - "History" in the various original documents, forming one section - entitled "History"; likewise combine any sections entitled - "Acknowledgements", and any sections entitled "Dedications." You - must delete all sections entitled "Endorsements." - - 6. COLLECTIONS OF DOCUMENTS - - 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. - - 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. - - 7. AGGREGATION WITH INDEPENDENT WORKS - - A compilation of the Document or its derivatives with other - separate and independent documents or works, in or on a volume of a - storage or distribution medium, does not as a whole count as a - Modified Version of the Document, provided no compilation copyright - is claimed for the compilation. Such a compilation is called an - "aggregate", and this License does not apply to the other - self-contained works thus compiled with the Document, on account of - their being thus compiled, if they are not themselves derivative - works of the Document. - - 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. - - 8. TRANSLATION - - 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. - - 9. TERMINATION - - 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. - - 10. FUTURE REVISIONS OF THIS LICENSE - - 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/. - - Each version of the License is given a distinguishing version - number. If the Document specifies that a particular numbered - version of this License "or any later version" applies to it, you - have the option of following the terms and conditions either of - that specified version or of any later version that has been - published (not as a draft) by the Free Software Foundation. If the - Document does not specify a version number of this License, you may - choose any version ever published (not as a draft) by the Free - Software Foundation. - -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: - - 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." - - If you have no Invariant Sections, write "with no Invariant Sections" -instead of saying which ones are invariant. If you have no Front-Cover -Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being -LIST"; likewise for Back-Cover Texts. - - 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. - - ---------- Footnotes ---------- - - (1) Any more details? - -AS Index -******** - -* Menu: - -* #: Comments. (line 1306) -* #APP: Preprocessing. (line 1268) -* #NO_APP: Preprocessing. (line 1268) -* '$a': ARM Mapping Symbols. - (line 4193) -* '$d': ARM Mapping Symbols. - (line 4199) -* '$t': ARM Mapping Symbols. - (line 4196) -* --: Command Line. (line 760) -* '--32' option, i386: i386-Options. (line 4220) -* '--32' option, x86-64: i386-Options. (line 4220) -* '--64' option, i386: i386-Options. (line 4220) -* '--64' option, x86-64: i386-Options. (line 4220) -* --alternate: alternate. (line 929) -* '--divide' option, i386: i386-Options. (line 4236) -* --enforce-aligned-data: Sparc-Aligned-Data. (line 5460) -* --fatal-warnings: W. (line 1222) -* --hash-size=NUMBER: Overview. (line 459) -* --listing-cont-lines: listing. (line 1015) -* --listing-lhs-width: listing. (line 997) -* --listing-lhs-width2: listing. (line 1002) -* --listing-rhs-width: listing. (line 1009) -* --MD: MD. (line 1149) -* --no-warn: W. (line 1217) -* --statistics: statistics. (line 1188) -* --traditional-format: traditional-format. (line 1196) -* --warn: W. (line 1225) -* -a: a. (line 894) -* -ac: a. (line 894) -* -ad: a. (line 894) -* -ah: a. (line 894) -* -al: a. (line 894) -* -an: a. (line 894) -* -as: a. (line 894) -* -Asparclet: Sparc-Opts. (line 5421) -* -Asparclite: Sparc-Opts. (line 5421) -* -Av6: Sparc-Opts. (line 5421) -* -Av8: Sparc-Opts. (line 5421) -* -Av9: Sparc-Opts. (line 5421) -* -Av9a: Sparc-Opts. (line 5421) -* -construct-floats: MIPS Opts. (line 5056) -* -D: D. (line 934) -* '-eabi=' command line option, ARM: ARM Options. (line 3844) -* '-EB' command line option, ARM: ARM Options. (line 3849) -* '-EB' option (MIPS): MIPS Opts. (line 4879) -* '-EL' command line option, ARM: ARM Options. (line 3853) -* '-EL' option (MIPS): MIPS Opts. (line 4879) -* -f: f. (line 940) -* '-G' option (MIPS): MIPS Opts. (line 4874) -* -I PATH: I. (line 952) -* -K: K. (line 962) -* '-k' command line option, ARM: ARM Options. (line 3857) -* '-KPIC' option, MIPS: MIPS Opts. (line 4887) -* -L: L. (line 972) -* -M: M. (line 1022) -* '-mapcs' command line option, ARM: ARM Options. (line 3817) -* '-mapcs-float' command line option, ARM: ARM Options. (line 3830) -* '-mapcs-reentrant' command line option, ARM: ARM Options. (line 3835) -* '-march=' command line option, ARM: ARM Options. (line 3773) -* '-march=' option, i386: i386-Options. (line 4243) -* '-march=' option, x86-64: i386-Options. (line 4243) -* '-matpcs' command line option, ARM: ARM Options. (line 3822) -* '-mconstant-gp' command line option, IA-64: IA-64 Options. (line 4733) -* '-mcpu=' command line option, ARM: ARM Options. (line 3742) -* '-mfloat-abi=' command line option, ARM: ARM Options. (line 3839) -* '-mfpu=' command line option, ARM: ARM Options. (line 3788) -* -mno-sym32: MIPS Opts. (line 5045) -* -msym32: MIPS Opts. (line 5045) -* '-mthumb' command line option, ARM: ARM Options. (line 3808) -* '-mthumb-interwork' command line option, ARM: ARM Options. (line 3813) -* '-mtune=' option, i386: i386-Options. (line 4255) -* '-mtune=' option, x86-64: i386-Options. (line 4255) -* '-mvxworks-pic' option, MIPS: MIPS Opts. (line 4892) -* -no-construct-floats: MIPS Opts. (line 5056) -* '-nocpp' ignored (MIPS): MIPS Opts. (line 5048) -* -o: o. (line 1160) -* -R: R. (line 1170) -* -v: v. (line 1206) -* -version: v. (line 1206) -* -W: W. (line 1217) -* '.' (symbol): Dot. (line 1898) -* '.arch' directive, ARM: ARM Directives. (line 4118) -* '.cantunwind' directive, ARM: ARM Directives. (line 4022) -* '.cpu' directive, ARM: ARM Directives. (line 4114) -* '.eabi_attribute' directive, ARM: ARM Directives. (line 4132) -* '.fnend' directive, ARM: ARM Directives. (line 4014) -* '.fnstart' directive, ARM: ARM Directives. (line 4011) -* '.fpu' directive, ARM: ARM Directives. (line 4128) -* '.handlerdata' directive, ARM: ARM Directives. (line 4033) -* '.insn': MIPS insn. (line 5223) -* '.ltorg' directive, ARM: ARM Directives. (line 3994) -* '.movsp' directive, ARM: ARM Directives. (line 4088) -* .o: Object. (line 827) -* '.object_arch' directive, ARM: ARM Directives. (line 4122) -* '.pad' directive, ARM: ARM Directives. (line 4083) -* '.personality' directive, ARM: ARM Directives. (line 4026) -* '.personalityindex' directive, ARM: ARM Directives. (line 4029) -* '.pool' directive, ARM: ARM Directives. (line 4008) -* '.save' directive, ARM: ARM Directives. (line 4042) -* '.set arch=CPU': MIPS ISA. (line 5195) -* '.set autoextend': MIPS autoextend. (line 5210) -* '.set dsp': MIPS ASE instruction generation overrides. - (line 5262) -* '.set dspr2': MIPS ASE instruction generation overrides. - (line 5267) -* '.set mdmx': MIPS ASE instruction generation overrides. - (line 5257) -* '.set mips3d': MIPS ASE instruction generation overrides. - (line 5247) -* '.set mipsN': MIPS ISA. (line 5183) -* '.set mt': MIPS ASE instruction generation overrides. - (line 5272) -* '.set noautoextend': MIPS autoextend. (line 5210) -* '.set nodsp': MIPS ASE instruction generation overrides. - (line 5262) -* '.set nodspr2': MIPS ASE instruction generation overrides. - (line 5267) -* '.set nomdmx': MIPS ASE instruction generation overrides. - (line 5257) -* '.set nomips3d': MIPS ASE instruction generation overrides. - (line 5247) -* '.set nomt': MIPS ASE instruction generation overrides. - (line 5272) -* '.set nosmartmips': MIPS ASE instruction generation overrides. - (line 5252) -* '.set nosym32': MIPS symbol sizes. (line 5140) -* '.set pop': MIPS option stack. (line 5232) -* '.set push': MIPS option stack. (line 5232) -* '.set smartmips': MIPS ASE instruction generation overrides. - (line 5252) -* '.set sym32': MIPS symbol sizes. (line 5140) -* '.setfp' directive, ARM: ARM Directives. (line 4093) -* '.unwind_raw' directive, ARM: ARM Directives. (line 4107) -* '.vsave' directive, ARM: ARM Directives. (line 4066) -* 16-bit code, i386: i386-16bit. (line 4615) -* 3DNow!, i386: i386-SIMD. (line 4593) -* 3DNow!, x86-64: i386-SIMD. (line 4593) -* ':' (label): Statements. (line 1355) -* '\"' (doublequote character): Strings. (line 1423) -* '\b' (backspace character): Strings. (line 1395) -* '\DDD' (octal character code): Strings. (line 1410) -* '\f' (formfeed character): Strings. (line 1398) -* '\n' (newline character): Strings. (line 1401) -* '\r' (carriage return character): Strings. (line 1404) -* '\t' (tab): Strings. (line 1407) -* '\XD...' (hex character code): Strings. (line 1416) -* '\\' ('\' character): Strings. (line 1420) -* a.out: Object. (line 827) -* 'abort' directive: Abort. (line 2114) -* absolute section: Ld Sections. (line 1632) -* addition, permitted arguments: Infix Ops. (line 2055) -* addresses: Expressions. (line 1946) -* addresses, format of: Secs Background. (line 1573) -* 'ADR reg,<label>' pseudo op, ARM: ARM Opcodes. (line 4159) -* 'ADRL reg,<label>' pseudo op, ARM: ARM Opcodes. (line 4169) -* advancing location counter: Org. (line 3101) -* 'align' directive: Align. (line 2123) -* 'align' directive, ARM: ARM Directives. (line 3915) -* 'align' directive, SPARC: Sparc-Directives. (line 5481) -* arch directive, i386: i386-Arch. (line 4670) -* arch directive, x86-64: i386-Arch. (line 4670) -* architectures, PowerPC: PowerPC-Opts. (line 5285) -* architectures, SPARC: Sparc-Opts. (line 5402) -* arguments for addition: Infix Ops. (line 2055) -* arguments for subtraction: Infix Ops. (line 2060) -* arguments in expressions: Arguments. (line 1973) -* arithmetic functions: Operators. (line 1998) -* arithmetic operands: Arguments. (line 1973) -* ARM data relocations: ARM-Relocations. (line 3886) -* 'arm' directive, ARM: ARM Directives. (line 3969) -* ARM floating point (IEEE): ARM Floating Point. (line 3910) -* ARM identifiers: ARM-Chars. (line 3876) -* ARM immediate character: ARM-Chars. (line 3874) -* ARM line comment character: ARM-Chars. (line 3867) -* ARM line separator: ARM-Chars. (line 3871) -* ARM machine directives: ARM Directives. (line 3915) -* ARM opcodes: ARM Opcodes. (line 4140) -* ARM options (none): ARM Options. (line 3742) -* ARM register names: ARM-Regs. (line 3881) -* ARM support: Machine Dependencies. - (line 3739) -* 'ascii' directive: Ascii. (line 2165) -* 'asciz' directive: Asciz. (line 2172) -* assembler bugs, reporting: Bug Reporting. (line 5566) -* assembler crash: Bug Criteria. (line 5550) -* assembler internal logic error: As Sections. (line 1674) -* assembler version: v. (line 1206) -* assembler, and linker: Secs Background. (line 1535) -* assembly listings, enabling: a. (line 894) -* assigning values to symbols: Setting Symbols. (line 1772) -* assigning values to symbols <1>: Equ. (line 2471) -* attributes, symbol: Symbol Attributes. (line 1907) -* att_syntax pseudo op, i386: i386-Syntax. (line 4265) -* att_syntax pseudo op, x86-64: i386-Syntax. (line 4265) -* Av7: Sparc-Opts. (line 5421) -* backslash ('\\'): Strings. (line 1420) -* backspace ('\b'): Strings. (line 1395) -* 'balign' directive: Balign. (line 2178) -* 'balignl' directive: Balign. (line 2199) -* 'balignw' directive: Balign. (line 2199) -* big endian output, MIPS: Overview. (line 560) -* big-endian output, MIPS: MIPS Opts. (line 4879) -* bignums: Bignums. (line 1485) -* binary files, including: Incbin. (line 2707) -* binary integers: Integers. (line 1466) -* bit names, IA-64: IA-64-Bits. (line 4846) -* bss section: Ld Sections. (line 1623) -* bss section <1>: bss. (line 1739) -* bug criteria: Bug Criteria. (line 5547) -* bug reports: Bug Reporting. (line 5566) -* bugs in assembler: Reporting Bugs. (line 5534) -* bus lock prefixes, i386: i386-Prefixes. (line 4444) -* 'byte' directive: Byte. (line 2211) -* call instructions, i386: i386-Mnemonics. (line 4353) -* call instructions, x86-64: i386-Mnemonics. (line 4353) -* carriage return ('\r'): Strings. (line 1404) -* 'cfi_endproc' directive: CFI directives. (line 2249) -* 'cfi_startproc' directive: CFI directives. (line 2239) -* character constants: Characters. (line 1377) -* character escape codes: Strings. (line 1395) -* character, single: Chars. (line 1443) -* characters used in symbols: Symbol Intro. (line 1325) -* 'code' directive, ARM: ARM Directives. (line 3962) -* 'code16' directive, i386: i386-16bit. (line 4615) -* 'code16gcc' directive, i386: i386-16bit. (line 4615) -* 'code32' directive, i386: i386-16bit. (line 4615) -* 'code64' directive, i386: i386-16bit. (line 4615) -* 'code64' directive, x86-64: i386-16bit. (line 4615) -* COMDAT: Linkonce. (line 2831) -* 'comm' directive: Comm. (line 2217) -* command line conventions: Command Line. (line 756) -* comments: Comments. (line 1288) -* comments, removed by preprocessor: Preprocessing. (line 1253) -* 'common' directive, SPARC: Sparc-Directives. (line 5484) -* common sections: Linkonce. (line 2831) -* common variable storage: bss. (line 1739) -* comparison expressions: Infix Ops. (line 2066) -* conditional assembly: If. (line 2629) -* constant, single character: Chars. (line 1443) -* constants: Constants. (line 1366) -* constants, bignum: Bignums. (line 1485) -* constants, character: Characters. (line 1377) -* constants, converted by preprocessor: Preprocessing. (line 1256) -* constants, floating point: Flonums. (line 1493) -* constants, integer: Integers. (line 1466) -* constants, number: Numbers. (line 1457) -* constants, string: Strings. (line 1386) -* conversion instructions, i386: i386-Mnemonics. (line 4334) -* conversion instructions, x86-64: i386-Mnemonics. (line 4334) -* coprocessor wait, i386: i386-Prefixes. (line 4448) -* crash of assembler: Bug Criteria. (line 5550) -* current address: Dot. (line 1898) -* current address, advancing: Org. (line 3101) -* data alignment on SPARC: Sparc-Aligned-Data. (line 5455) -* data and text sections, joining: R. (line 1170) -* 'data' directive: Data. (line 2421) -* data relocations, ARM: ARM-Relocations. (line 3886) -* debuggers, and symbol order: Symbols. (line 1757) -* decimal integers: Integers. (line 1472) -* dependency tracking: MD. (line 1149) -* deprecated directives: Deprecated. (line 3731) -* directives and instructions: Statements. (line 1347) -* directives for PowerPC: PowerPC-Pseudo. (line 5386) -* directives, machine independent: Pseudo Ops. (line 2105) -* 'dn' and 'qn' directives, ARM: ARM Directives. (line 3938) -* dollar local symbols: Symbol Names. (line 1879) -* dot (symbol): Dot. (line 1898) -* 'double' directive: Double. (line 2428) -* 'double' directive, i386: i386-Float. (line 4569) -* 'double' directive, x86-64: i386-Float. (line 4569) -* doublequote ('\"'): Strings. (line 1423) -* ECOFF sections: MIPS Object. (line 5100) -* eight-byte integer: Quad. (line 3245) -* 'eject' directive: Eject. (line 2434) -* ELF symbol type: Type. (line 3620) -* 'else' directive: Else. (line 2439) -* 'elseif' directive: Elseif. (line 2446) -* empty expressions: Empty Exprs. (line 1959) -* emulation: Overview. (line 663) -* 'end' directive: End. (line 2453) -* 'endfunc' directive: Endfunc. (line 2459) -* endianness, MIPS: Overview. (line 560) -* 'endif' directive: Endif. (line 2464) -* 'endm' directive: Macro. (line 3025) -* EOF, newline must precede: Statements. (line 1341) -* 'equ' directive: Equ. (line 2471) -* 'equiv' directive: Equiv. (line 2477) -* 'eqv' directive: Eqv. (line 2493) -* 'err' directive: Err. (line 2501) -* error directive: Error. (line 2509) -* error messages: Errors. (line 844) -* error on valid input: Bug Criteria. (line 5553) -* errors, caused by warnings: W. (line 1222) -* errors, continuing after: Z. (line 1231) -* escape codes, character: Strings. (line 1395) -* 'exitm' directive: Macro. (line 3028) -* expr (internal section): As Sections. (line 1678) -* expression arguments: Arguments. (line 1973) -* expressions: Expressions. (line 1946) -* expressions, comparison: Infix Ops. (line 2066) -* expressions, empty: Empty Exprs. (line 1959) -* expressions, integer: Integer Exprs. (line 1967) -* 'extern' directive: Extern. (line 2524) -* 'fail' directive: Fail. (line 2531) -* faster processing ('-f'): f. (line 940) -* fatal signal: Bug Criteria. (line 5550) -* 'file' directive: LNS directives. (line 2369) -* 'file' directive <1>: File. (line 2540) -* file name, logical: File. (line 2540) -* files, including: Include. (line 2721) -* files, input: Input Files. (line 780) -* 'fill' directive: Fill. (line 2550) -* filling memory: Skip. (line 3452) -* filling memory <1>: Space. (line 3459) -* 'float' directive: Float. (line 2568) -* 'float' directive, i386: i386-Float. (line 4569) -* 'float' directive, x86-64: i386-Float. (line 4569) -* floating point numbers: Flonums. (line 1493) -* floating point numbers (double): Double. (line 2428) -* floating point numbers (single): Float. (line 2568) -* floating point numbers (single) <1>: Single. (line 3425) -* floating point, ARM (IEEE): ARM Floating Point. (line 3910) -* floating point, i386: i386-Float. (line 4561) -* floating point, SPARC (IEEE): Sparc-Float. (line 5473) -* floating point, x86-64: i386-Float. (line 4561) -* flonums: Flonums. (line 1493) -* 'force_thumb' directive, ARM: ARM Directives. (line 3972) -* format of error messages: Errors. (line 861) -* format of warning messages: Errors. (line 850) -* formfeed ('\f'): Strings. (line 1398) -* 'func' directive: Func. (line 2574) -* functions, in expressions: Operators. (line 1998) -* 'global' directive: Global. (line 2585) -* 'gp' register, MIPS: MIPS Object. (line 5105) -* grouping data: Sub-Sections. (line 1686) -* 'half' directive, SPARC: Sparc-Directives. (line 5489) -* hex character code ('\XD...'): Strings. (line 1416) -* hexadecimal integers: Integers. (line 1475) -* 'hidden' directive: Hidden. (line 2597) -* 'hword' directive: hword. (line 2610) -* i386 16-bit code: i386-16bit. (line 4615) -* i386 arch directive: i386-Arch. (line 4670) -* i386 att_syntax pseudo op: i386-Syntax. (line 4265) -* i386 conversion instructions: i386-Mnemonics. (line 4334) -* i386 floating point: i386-Float. (line 4561) -* i386 immediate operands: i386-Syntax. (line 4274) -* i386 instruction naming: i386-Mnemonics. (line 4309) -* i386 instruction prefixes: i386-Prefixes. (line 4414) -* i386 intel_syntax pseudo op: i386-Syntax. (line 4265) -* i386 jump optimization: i386-Jumps. (line 4538) -* i386 jump, call, return: i386-Syntax. (line 4296) -* i386 jump/call operands: i386-Syntax. (line 4274) -* i386 memory references: i386-Memory. (line 4471) -* i386 'mul', 'imul' instructions: i386-Notes. (line 4714) -* i386 options: i386-Options. (line 4218) -* i386 register operands: i386-Syntax. (line 4274) -* i386 registers: i386-Regs. (line 4359) -* i386 sections: i386-Syntax. (line 4302) -* i386 size suffixes: i386-Syntax. (line 4287) -* i386 source, destination operands: i386-Syntax. (line 4280) -* i386 support: . (line 4211) -* i386 syntax compatibility: i386-Syntax. (line 4265) -* i80306 support: . (line 4211) -* IA-64 line comment character: IA-64-Chars. (line 4822) -* IA-64 line separator: IA-64-Chars. (line 4824) -* IA-64 options: IA-64 Options. (line 4733) -* IA-64 Processor-status-Register bit names: IA-64-Bits. (line 4846) -* IA-64 registers: IA-64-Regs. (line 4829) -* IA-64 support: . (line 4730) -* IA-64 Syntax: IA-64 Options. (line 4812) -* 'ident' directive: Ident. (line 2618) -* identifiers, ARM: ARM-Chars. (line 3876) -* 'if' directive: If. (line 2629) -* 'ifb' directive: If. (line 2644) -* 'ifc' directive: If. (line 2648) -* 'ifdef' directive: If. (line 2639) -* 'ifeq' directive: If. (line 2656) -* 'ifeqs' directive: If. (line 2659) -* 'ifge' directive: If. (line 2663) -* 'ifgt' directive: If. (line 2667) -* 'ifle' directive: If. (line 2671) -* 'iflt' directive: If. (line 2675) -* 'ifnb' directive: If. (line 2679) -* 'ifnc' directive: If. (line 2684) -* 'ifndef' directive: If. (line 2688) -* 'ifne' directive: If. (line 2695) -* 'ifnes' directive: If. (line 2699) -* 'ifnotdef' directive: If. (line 2688) -* immediate character, ARM: ARM-Chars. (line 3874) -* immediate operands, i386: i386-Syntax. (line 4274) -* immediate operands, x86-64: i386-Syntax. (line 4274) -* 'imul' instruction, i386: i386-Notes. (line 4714) -* 'imul' instruction, x86-64: i386-Notes. (line 4714) -* 'incbin' directive: Incbin. (line 2707) -* 'include' directive: Include. (line 2721) -* 'include' directive search path: I. (line 952) -* infix operators: Infix Ops. (line 2016) -* inhibiting interrupts, i386: i386-Prefixes. (line 4444) -* input: Input Files. (line 780) -* input file linenumbers: Input Files. (line 809) -* instruction naming, i386: i386-Mnemonics. (line 4309) -* instruction naming, x86-64: i386-Mnemonics. (line 4309) -* instruction prefixes, i386: i386-Prefixes. (line 4414) -* instructions and directives: Statements. (line 1347) -* 'int' directive: Int. (line 2732) -* 'int' directive, i386: i386-Float. (line 4576) -* 'int' directive, x86-64: i386-Float. (line 4576) -* integer expressions: Integer Exprs. (line 1967) -* integer, 16-byte: Octa. (line 3092) -* integer, 8-byte: Quad. (line 3245) -* integers: Integers. (line 1466) -* integers, 16-bit: hword. (line 2610) -* integers, 32-bit: Int. (line 2732) -* integers, binary: Integers. (line 1466) -* integers, decimal: Integers. (line 1472) -* integers, hexadecimal: Integers. (line 1475) -* integers, octal: Integers. (line 1469) -* integers, one byte: Byte. (line 2211) -* intel_syntax pseudo op, i386: i386-Syntax. (line 4265) -* intel_syntax pseudo op, x86-64: i386-Syntax. (line 4265) -* internal assembler sections: As Sections. (line 1667) -* 'internal' directive: Internal. (line 2740) -* invalid input: Bug Criteria. (line 5555) -* invocation summary: Overview. (line 249) -* 'irp' directive: Irp. (line 2754) -* 'irpc' directive: Irpc. (line 2779) -* joining text and data sections: R. (line 1170) -* jump instructions, i386: i386-Mnemonics. (line 4353) -* jump instructions, x86-64: i386-Mnemonics. (line 4353) -* jump optimization, i386: i386-Jumps. (line 4538) -* jump optimization, x86-64: i386-Jumps. (line 4538) -* jump/call operands, i386: i386-Syntax. (line 4274) -* jump/call operands, x86-64: i386-Syntax. (line 4274) -* label (':'): Statements. (line 1355) -* labels: Labels. (line 1763) -* 'lcomm' directive: Lcomm. (line 2805) -* ld: Object. (line 836) -* 'LDR reg,=<label>' pseudo op, ARM: ARM Opcodes. (line 4149) -* length of symbols: Symbol Intro. (line 1331) -* 'lflags' directive (ignored): Lflags. (line 2814) -* line comment character: Comments. (line 1301) -* line comment character, ARM: ARM-Chars. (line 3867) -* line comment character, IA-64: IA-64-Chars. (line 4822) -* 'line' directive: Line. (line 2820) -* line numbers, in input files: Input Files. (line 809) -* line numbers, in warnings/errors: Errors. (line 854) -* line separator character: Statements. (line 1336) -* line separator, ARM: ARM-Chars. (line 3871) -* line separator, IA-64: IA-64-Chars. (line 4824) -* lines starting with '#': Comments. (line 1306) -* linker: Object. (line 836) -* linker, and assembler: Secs Background. (line 1535) -* 'linkonce' directive: Linkonce. (line 2831) -* 'list' directive: List. (line 2876) -* listing control, turning off: Nolist. (line 3083) -* listing control, turning on: List. (line 2876) -* listing control: new page: Eject. (line 2434) -* listing control: paper size: Psize. (line 3208) -* listing control: subtitle: Sbttl. (line 3284) -* listing control: title line: Title. (line 3609) -* listings, enabling: a. (line 894) -* little endian output, MIPS: Overview. (line 563) -* little-endian output, MIPS: MIPS Opts. (line 4879) -* 'ln' directive: Ln. (line 2863) -* 'loc' directive: LNS directives. (line 2382) -* local common symbols: Lcomm. (line 2805) -* local labels: Symbol Names. (line 1810) -* local symbol names: Symbol Names. (line 1797) -* local symbols, retaining in output: L. (line 972) -* location counter: Dot. (line 1898) -* location counter, advancing: Org. (line 3101) -* 'loc_mark_blocks' directive: LNS directives. (line 2412) -* logical file name: File. (line 2540) -* logical line number: Line. (line 2820) -* logical line numbers: Comments. (line 1306) -* 'long' directive: Long. (line 2889) -* 'long' directive, i386: i386-Float. (line 4576) -* 'long' directive, x86-64: i386-Float. (line 4576) -* machine directives, ARM: ARM Directives. (line 3915) -* machine directives, SPARC: Sparc-Directives. (line 5478) -* machine independent directives: Pseudo Ops. (line 2105) -* machine instructions (not covered): Manual. (line 716) -* machine-independent syntax: Syntax. (line 1241) -* 'macro' directive: Macro. (line 2916) -* macros: Macro. (line 2894) -* macros, count executed: Macro. (line 3030) -* make rules: MD. (line 1149) -* manual, structure and purpose: Manual. (line 708) -* Maximum number of continuation lines: listing. (line 1015) -* memory references, i386: i386-Memory. (line 4471) -* memory references, x86-64: i386-Memory. (line 4471) -* merging text and data sections: R. (line 1170) -* messages from assembler: Errors. (line 844) -* minus, permitted arguments: Infix Ops. (line 2060) -* MIPS architecture options: MIPS Opts. (line 4895) -* MIPS big-endian output: MIPS Opts. (line 4879) -* MIPS CPU override: MIPS ISA. (line 5195) -* MIPS debugging directives: MIPS Stabs. (line 5128) -* MIPS DSP Release 1 instruction generation override: MIPS ASE instruction generation overrides. - (line 5262) -* MIPS DSP Release 2 instruction generation override: MIPS ASE instruction generation overrides. - (line 5267) -* MIPS ECOFF sections: MIPS Object. (line 5100) -* MIPS endianness: Overview. (line 560) -* MIPS ISA: Overview. (line 566) -* MIPS ISA override: MIPS ISA. (line 5183) -* MIPS little-endian output: MIPS Opts. (line 4879) -* MIPS MDMX instruction generation override: MIPS ASE instruction generation overrides. - (line 5257) -* MIPS MIPS-3D instruction generation override: MIPS ASE instruction generation overrides. - (line 5247) -* MIPS MT instruction generation override: MIPS ASE instruction generation overrides. - (line 5272) -* MIPS option stack: MIPS option stack. (line 5232) -* MIPS processor: . (line 4862) -* MMX, i386: i386-SIMD. (line 4593) -* MMX, x86-64: i386-SIMD. (line 4593) -* mnemonic suffixes, i386: i386-Syntax. (line 4287) -* mnemonic suffixes, x86-64: i386-Syntax. (line 4287) -* MOVW and MOVT relocations, ARM: ARM-Relocations. (line 3900) -* MRI compatibility mode: M. (line 1022) -* 'mri' directive: MRI. (line 2868) -* MRI mode, temporarily: MRI. (line 2868) -* 'mul' instruction, i386: i386-Notes. (line 4714) -* 'mul' instruction, x86-64: i386-Notes. (line 4714) -* named section: Section. (line 3293) -* named sections: Ld Sections. (line 1613) -* names, symbol: Symbol Names. (line 1781) -* naming object file: o. (line 1160) -* new page, in listings: Eject. (line 2434) -* newline ('\n'): Strings. (line 1401) -* newline, required at file end: Statements. (line 1341) -* 'nolist' directive: Nolist. (line 3083) -* 'NOP' pseudo op, ARM: ARM Opcodes. (line 4143) -* null-terminated strings: Asciz. (line 2172) -* number constants: Numbers. (line 1457) -* number of macros executed: Macro. (line 3030) -* numbered subsections: Sub-Sections. (line 1686) -* numbers, 16-bit: hword. (line 2610) -* numeric values: Expressions. (line 1946) -* 'nword' directive, SPARC: Sparc-Directives. (line 5492) -* object file: Object. (line 827) -* object file format: Object Formats. (line 746) -* object file name: o. (line 1160) -* object file, after errors: Z. (line 1231) -* obsolescent directives: Deprecated. (line 3731) -* 'octa' directive: Octa. (line 3092) -* octal character code ('\DDD'): Strings. (line 1410) -* octal integers: Integers. (line 1469) -* opcodes for ARM: ARM Opcodes. (line 4140) -* operand delimiters, i386: i386-Syntax. (line 4274) -* operand delimiters, x86-64: i386-Syntax. (line 4274) -* operands in expressions: Arguments. (line 1973) -* operator precedence: Infix Ops. (line 2021) -* operators, in expressions: Operators. (line 1998) -* operators, permitted arguments: Infix Ops. (line 2016) -* option summary: Overview. (line 249) -* options for ARM (none): ARM Options. (line 3742) -* options for i386: i386-Options. (line 4218) -* options for IA-64: IA-64 Options. (line 4733) -* options for PowerPC: PowerPC-Opts. (line 5285) -* options for SPARC: Sparc-Opts. (line 5402) -* options for x86-64: i386-Options. (line 4218) -* options, all versions of assembler: Invoking. (line 870) -* options, command line: Command Line. (line 763) -* 'org' directive: Org. (line 3101) -* output file: Object. (line 827) -* 'p2align' directive: P2align. (line 3127) -* 'p2alignl' directive: P2align. (line 3149) -* 'p2alignw' directive: P2align. (line 3149) -* padding the location counter: Align. (line 2123) -* padding the location counter given a power of two: P2align. - (line 3127) -* padding the location counter given number of bytes: Balign. - (line 2178) -* page, in listings: Eject. (line 2434) -* paper size, for listings: Psize. (line 3208) -* paths for '.include': I. (line 952) -* patterns, writing in memory: Fill. (line 2550) -* PIC code generation for ARM: ARM Options. (line 3857) -* PIC selection, MIPS: MIPS Opts. (line 4887) -* plus, permitted arguments: Infix Ops. (line 2055) -* 'popsection' directive: PopSection. (line 3177) -* PowerPC architectures: PowerPC-Opts. (line 5285) -* PowerPC directives: PowerPC-Pseudo. (line 5386) -* PowerPC options: PowerPC-Opts. (line 5285) -* PowerPC support: . (line 5282) -* precedence of operators: Infix Ops. (line 2021) -* precision, floating point: Flonums. (line 1493) -* prefix operators: Prefix Ops. (line 2005) -* prefixes, i386: i386-Prefixes. (line 4414) -* preprocessing: Preprocessing. (line 1248) -* preprocessing, turning on and off: Preprocessing. (line 1268) -* 'previous' directive: Previous. (line 3161) -* 'print' directive: Print. (line 3189) -* 'proc' directive, SPARC: Sparc-Directives. (line 5497) -* 'protected' directive: Protected. (line 3195) -* pseudo-ops, machine independent: Pseudo Ops. (line 2105) -* 'psize' directive: Psize. (line 3208) -* PSR bits: IA-64-Bits. (line 4846) -* 'purgem' directive: Purgem. (line 3224) -* purpose of GNU assembler: GNU Assembler. (line 734) -* 'pushsection' directive: PushSection. (line 3230) -* 'quad' directive: Quad. (line 3242) -* 'quad' directive, i386: i386-Float. (line 4576) -* 'quad' directive, x86-64: i386-Float. (line 4576) -* real-mode code, i386: i386-16bit. (line 4615) -* 'register' directive, SPARC: Sparc-Directives. (line 5501) -* register names, ARM: ARM-Regs. (line 3881) -* register names, IA-64: IA-64-Regs. (line 4829) -* register operands, i386: i386-Syntax. (line 4274) -* register operands, x86-64: i386-Syntax. (line 4274) -* registers, i386: i386-Regs. (line 4359) -* registers, x86-64: i386-Regs. (line 4359) -* 'reloc' directive: Reloc. (line 3253) -* relocation: Sections. (line 1528) -* relocation example: Ld Sections. (line 1643) -* repeat prefixes, i386: i386-Prefixes. (line 4452) -* reporting bugs in assembler: Reporting Bugs. (line 5534) -* 'rept' directive: Rept. (line 3266) -* 'req' directive, ARM: ARM Directives. (line 3922) -* 'reserve' directive, SPARC: Sparc-Directives. (line 5511) -* return instructions, i386: i386-Syntax. (line 4296) -* return instructions, x86-64: i386-Syntax. (line 4296) -* REX prefixes, i386: i386-Prefixes. (line 4454) -* 'sbttl' directive: Sbttl. (line 3284) -* search path for '.include': I. (line 952) -* 'section' directive (ELF version): Section. (line 3305) -* section override prefixes, i386: i386-Prefixes. (line 4431) -* Section Stack: Previous. (line 3161) -* Section Stack <1>: PopSection. (line 3177) -* Section Stack <2>: PushSection. (line 3230) -* Section Stack <3>: Section. (line 3300) -* Section Stack <4>: SubSection. (line 3545) -* section-relative addressing: Secs Background. (line 1573) -* sections: Sections. (line 1528) -* sections in messages, internal: As Sections. (line 1667) -* sections, i386: i386-Syntax. (line 4302) -* sections, named: Ld Sections. (line 1613) -* sections, x86-64: i386-Syntax. (line 4302) -* 'seg' directive, SPARC: Sparc-Directives. (line 5516) -* 'set' directive: Set. (line 3407) -* 'short' directive: Short. (line 3419) -* SIMD, i386: i386-SIMD. (line 4593) -* SIMD, x86-64: i386-SIMD. (line 4593) -* single character constant: Chars. (line 1443) -* 'single' directive: Single. (line 3425) -* 'single' directive, i386: i386-Float. (line 4569) -* 'single' directive, x86-64: i386-Float. (line 4569) -* sixteen bit integers: hword. (line 2610) -* sixteen byte integer: Octa. (line 3092) -* 'size' directive (ELF version): Size. (line 3433) -* size prefixes, i386: i386-Prefixes. (line 4435) -* sizes operands, i386: i386-Syntax. (line 4287) -* sizes operands, x86-64: i386-Syntax. (line 4287) -* 'skip' directive: Skip. (line 3452) -* 'skip' directive, SPARC: Sparc-Directives. (line 5520) -* 'sleb128' directive: Sleb128. (line 3445) -* small objects, MIPS ECOFF: MIPS Object. (line 5105) -* SmartMIPS instruction generation override: MIPS ASE instruction generation overrides. - (line 5252) -* source program: Input Files. (line 780) -* source, destination operands; i386: i386-Syntax. (line 4280) -* source, destination operands; x86-64: i386-Syntax. (line 4280) -* 'space' directive: Space. (line 3459) -* space used, maximum for assembly: statistics. (line 1188) -* SPARC architectures: Sparc-Opts. (line 5402) -* SPARC data alignment: Sparc-Aligned-Data. (line 5455) -* SPARC floating point (IEEE): Sparc-Float. (line 5473) -* SPARC machine directives: Sparc-Directives. (line 5478) -* SPARC options: Sparc-Opts. (line 5402) -* SPARC support: . (line 5399) -* 'stabd' directive: Stab. (line 3498) -* 'stabn' directive: Stab. (line 3509) -* 'stabs' directive: Stab. (line 3512) -* 'stabX' directives: Stab. (line 3466) -* standard assembler sections: Secs Background. (line 1550) -* standard input, as input file: Command Line. (line 760) -* statement separator character: Statements. (line 1336) -* statement separator, ARM: ARM-Chars. (line 3871) -* statement separator, IA-64: IA-64-Chars. (line 4824) -* statements, structure of: Statements. (line 1336) -* statistics, about assembly: statistics. (line 1188) -* stopping the assembly: Abort. (line 2114) -* string constants: Strings. (line 1386) -* 'string' directive: String. (line 3518) -* string literals: Ascii. (line 2165) -* string, copying to object file: String. (line 3518) -* 'struct' directive: Struct. (line 3527) -* subexpressions: Arguments. (line 1991) -* 'subsection' directive: SubSection. (line 3545) -* subtitles for listings: Sbttl. (line 3284) -* subtraction, permitted arguments: Infix Ops. (line 2060) -* summary of options: Overview. (line 249) -* supporting files, including: Include. (line 2721) -* suppressing warnings: W. (line 1217) -* symbol attributes: Symbol Attributes. (line 1907) -* symbol names: Symbol Names. (line 1781) -* symbol names, local: Symbol Names. (line 1797) -* symbol names, temporary: Symbol Names. (line 1810) -* symbol type: Symbol Type. (line 1938) -* symbol type, ELF: Type. (line 3620) -* symbol value: Symbol Value. (line 1918) -* symbol value, setting: Set. (line 3407) -* symbol values, assigning: Setting Symbols. (line 1772) -* symbol versioning: Symver. (line 3557) -* symbol, common: Comm. (line 2217) -* symbol, making visible to linker: Global. (line 2585) -* symbolic debuggers, information for: Stab. (line 3466) -* symbols: Symbols. (line 1753) -* symbols, assigning values to: Equ. (line 2471) -* symbols, local common: Lcomm. (line 2805) -* 'symver' directive: Symver. (line 3557) -* syntax compatibility, i386: i386-Syntax. (line 4265) -* syntax compatibility, x86-64: i386-Syntax. (line 4265) -* syntax, machine-independent: Syntax. (line 1241) -* tab ('\t'): Strings. (line 1407) -* temporary symbol names: Symbol Names. (line 1810) -* text and data sections, joining: R. (line 1170) -* 'text' directive: Text. (line 3602) -* 'tfloat' directive, i386: i386-Float. (line 4569) -* 'tfloat' directive, x86-64: i386-Float. (line 4569) -* 'thumb' directive, ARM: ARM Directives. (line 3966) -* Thumb support: Machine Dependencies. - (line 3739) -* 'thumb_func' directive, ARM: ARM Directives. (line 3976) -* 'thumb_set' directive, ARM: ARM Directives. (line 3987) -* time, total for assembly: statistics. (line 1188) -* 'title' directive: Title. (line 3609) -* trusted compiler: f. (line 940) -* turning preprocessing on and off: Preprocessing. (line 1268) -* 'type' directive (ELF version): Type. (line 3620) -* type of a symbol: Symbol Type. (line 1938) -* 'uleb128' directive: Uleb128. (line 3656) -* undefined section: Ld Sections. (line 1639) -* 'unreq' directive, ARM: ARM Directives. (line 3927) -* value of a symbol: Symbol Value. (line 1918) -* 'version' directive: Version. (line 3663) -* version of assembler: v. (line 1206) -* versions of symbols: Symver. (line 3557) -* visibility: Hidden. (line 2597) -* visibility <1>: Internal. (line 2740) -* visibility <2>: Protected. (line 3195) -* 'vtable_entry' directive: VTableEntry. (line 3669) -* 'vtable_inherit' directive: VTableInherit. (line 3675) -* warning directive: Warning. (line 3683) -* warning messages: Errors. (line 844) -* warnings, causing error: W. (line 1222) -* warnings, suppressing: W. (line 1217) -* warnings, switching on: W. (line 1225) -* 'weak' directive: Weak. (line 3689) -* 'weakref' directive: Weakref. (line 3705) -* whitespace: Whitespace. (line 1280) -* whitespace, removed by preprocessor: Preprocessing. (line 1249) -* Width of continuation lines of disassembly output: listing. - (line 1002) -* Width of first line disassembly output: listing. (line 997) -* Width of source line output: listing. (line 1009) -* 'word' directive: Word. (line 3725) -* 'word' directive, i386: i386-Float. (line 4576) -* 'word' directive, SPARC: Sparc-Directives. (line 5523) -* 'word' directive, x86-64: i386-Float. (line 4576) -* writing patterns in memory: Fill. (line 2550) -* x86-64 arch directive: i386-Arch. (line 4670) -* x86-64 att_syntax pseudo op: i386-Syntax. (line 4265) -* x86-64 conversion instructions: i386-Mnemonics. (line 4334) -* x86-64 floating point: i386-Float. (line 4561) -* x86-64 immediate operands: i386-Syntax. (line 4274) -* x86-64 instruction naming: i386-Mnemonics. (line 4309) -* x86-64 intel_syntax pseudo op: i386-Syntax. (line 4265) -* x86-64 jump optimization: i386-Jumps. (line 4538) -* x86-64 jump, call, return: i386-Syntax. (line 4296) -* x86-64 jump/call operands: i386-Syntax. (line 4274) -* x86-64 memory references: i386-Memory. (line 4471) -* x86-64 options: i386-Options. (line 4218) -* x86-64 register operands: i386-Syntax. (line 4274) -* x86-64 registers: i386-Regs. (line 4359) -* x86-64 sections: i386-Syntax. (line 4302) -* x86-64 size suffixes: i386-Syntax. (line 4287) -* x86-64 source, destination operands: i386-Syntax. (line 4280) -* x86-64 support: . (line 4211) -* x86-64 syntax compatibility: i386-Syntax. (line 4265) -* 'xword' directive, SPARC: Sparc-Directives. (line 5527) -* zero-terminated strings: Asciz. (line 2172) - -START-INFO-DIR-ENTRY -* As: (as). The GNU assembler. -* Gas: (as). The GNU assembler. -END-INFO-DIR-ENTRY - -Using as -1 Overview - 1.1 Structure of this Manual - 1.2 The GNU Assembler - 1.3 Object File Formats - 1.4 Command Line - 1.5 Input Files - 1.6 Output (Object) File - 1.7 Error and Warning Messages -2 Command-Line Options - 2.1 Enable Listings: '-a[cdhlns]' - 2.2 '--alternate' - 2.3 '-D' - 2.4 Work Faster: '-f' - 2.5 '.include' Search Path: '-I' PATH - 2.6 Difference Tables: '-K' - 2.7 Include Local Symbols: '-L' - 2.8 Configuring listing output: '--listing' - 2.9 Assemble in MRI Compatibility Mode: '-M' - 2.10 Dependency Tracking: '--MD' - 2.11 Name the Object File: '-o' - 2.12 Join Data and Text Sections: '-R' - 2.13 Display Assembly Statistics: '--statistics' - 2.14 Compatible Output: '--traditional-format' - 2.15 Announce Version: '-v' - 2.16 Control Warnings: '-W', '--warn', '--no-warn', '--fatal-warnings' - 2.17 Generate Object File in Spite of Errors: '-Z' -3 Syntax - 3.1 Preprocessing - 3.2 Whitespace - 3.3 Comments - 3.4 Symbols - 3.5 Statements - 3.6 Constants - 3.6.1 Character Constants - 3.6.1.1 Strings - 3.6.1.2 Characters - 3.6.2 Number Constants - 3.6.2.1 Integers - 3.6.2.2 Bignums - 3.6.2.3 Flonums -4 Sections and Relocation - 4.1 Background - 4.2 Linker Sections - 4.3 Assembler Internal Sections - 4.4 Sub-Sections - 4.5 bss Section -5 Symbols - 5.1 Labels - 5.2 Giving Symbols Other Values - 5.3 Symbol Names - 5.4 The Special Dot Symbol - 5.5 Symbol Attributes - 5.5.1 Value - 5.5.2 Type -6 Expressions - 6.1 Empty Expressions - 6.2 Integer Expressions - 6.2.1 Arguments - 6.2.2 Operators - 6.2.3 Prefix Operator - 6.2.4 Infix Operators -7 Assembler Directives - 7.1 '.abort' - 7.2 '.align ABS-EXPR, ABS-EXPR, ABS-EXPR' - 7.3 '.ascii "STRING"'... - 7.4 '.asciz "STRING"'... - 7.5 '.balign[wl] ABS-EXPR, ABS-EXPR, ABS-EXPR' - 7.6 '.byte EXPRESSIONS' - 7.7 '.comm SYMBOL , LENGTH ' - 7.8 '.cfi_startproc [simple]' - 7.9 '.cfi_endproc' - 7.10 '.cfi_personality ENCODING [, EXP]' - 7.11 '.cfi_lsda ENCODING [, EXP]' - 7.12 '.cfi_def_cfa REGISTER, OFFSET' - 7.13 '.cfi_def_cfa_register REGISTER' - 7.14 '.cfi_def_cfa_offset OFFSET' - 7.15 '.cfi_adjust_cfa_offset OFFSET' - 7.16 '.cfi_offset REGISTER, OFFSET' - 7.17 '.cfi_rel_offset REGISTER, OFFSET' - 7.18 '.cfi_register REGISTER1, REGISTER2' - 7.19 '.cfi_restore REGISTER' - 7.20 '.cfi_undefined REGISTER' - 7.21 '.cfi_same_value REGISTER' - 7.22 '.cfi_remember_state', - 7.23 '.cfi_return_column REGISTER' - 7.24 '.cfi_signal_frame' - 7.25 '.cfi_window_save' - 7.26 '.cfi_escape' EXPRESSION[, ...] - 7.27 '.file FILENO FILENAME' - 7.28 '.loc FILENO LINENO [COLUMN] [OPTIONS]' - 7.29 '.loc_mark_blocks ENABLE' - 7.30 '.data SUBSECTION' - 7.31 '.double FLONUMS' - 7.32 '.eject' - 7.33 '.else' - 7.34 '.elseif' - 7.35 '.end' - 7.36 '.endfunc' - 7.37 '.endif' - 7.38 '.equ SYMBOL, EXPRESSION' - 7.39 '.equiv SYMBOL, EXPRESSION' - 7.40 '.eqv SYMBOL, EXPRESSION' - 7.41 '.err' - 7.42 '.error "STRING"' - 7.43 '.exitm' - 7.44 '.extern' - 7.45 '.fail EXPRESSION' - 7.46 '.file STRING' - 7.47 '.fill REPEAT , SIZE , VALUE' - 7.48 '.float FLONUMS' - 7.49 '.func NAME[,LABEL]' - 7.50 '.global SYMBOL', '.globl SYMBOL' - 7.51 '.hidden NAMES' - 7.52 '.hword EXPRESSIONS' - 7.53 '.ident' - 7.54 '.if ABSOLUTE EXPRESSION' - 7.55 '.incbin "FILE"[,SKIP[,COUNT]]' - 7.56 '.include "FILE"' - 7.57 '.int EXPRESSIONS' - 7.58 '.internal NAMES' - 7.59 '.irp SYMBOL,VALUES'... - 7.60 '.irpc SYMBOL,VALUES'... - 7.61 '.lcomm SYMBOL , LENGTH' - 7.62 '.lflags' - 7.63 '.line LINE-NUMBER' - 7.64 '.linkonce [TYPE]' - 7.65 '.ln LINE-NUMBER' - 7.66 '.mri VAL' - 7.67 '.list' - 7.68 '.long EXPRESSIONS' - 7.69 '.macro' - 7.70 '.altmacro' - 7.71 '.noaltmacro' - 7.72 '.nolist' - 7.73 '.octa BIGNUMS' - 7.74 '.org NEW-LC , FILL' - 7.75 '.p2align[wl] ABS-EXPR, ABS-EXPR, ABS-EXPR' - 7.76 '.previous' - 7.77 '.popsection' - 7.78 '.print STRING' - 7.79 '.protected NAMES' - 7.80 '.psize LINES , COLUMNS' - 7.81 '.purgem NAME' - 7.82 '.pushsection NAME , SUBSECTION' - 7.83 '.quad BIGNUMS' - 7.84 '.reloc OFFSET, RELOC_NAME[, EXPRESSION]' - 7.85 '.rept COUNT' - 7.86 '.sbttl "SUBHEADING"' - 7.87 '.section NAME' - 7.88 '.set SYMBOL, EXPRESSION' - 7.89 '.short EXPRESSIONS' - 7.90 '.single FLONUMS' - 7.91 '.size' - 7.92 '.sleb128 EXPRESSIONS' - 7.93 '.skip SIZE , FILL' - 7.94 '.space SIZE , FILL' - 7.95 '.stabd, .stabn, .stabs' - 7.96 '.string' "STR" - 7.97 '.struct EXPRESSION' - 7.98 '.subsection NAME' - 7.99 '.symver' - 7.100 '.text SUBSECTION' - 7.101 '.title "HEADING"' - 7.102 '.type' - 7.103 '.uleb128 EXPRESSIONS' - 7.104 '.version "STRING"' - 7.105 '.vtable_entry TABLE, OFFSET' - 7.106 '.vtable_inherit CHILD, PARENT' - 7.107 '.warning "STRING"' - 7.108 '.weak NAMES' - 7.109 '.weakref ALIAS, TARGET' - 7.110 '.word EXPRESSIONS' - 7.111 Deprecated Directives -8 ARM Dependent Features - 8.1 Options - 8.2 Syntax - 8.2.1 Special Characters - 8.2.2 Register Names - 8.2.3 ARM relocation generation - 8.3 Floating Point - 8.4 ARM Machine Directives - 8.5 Opcodes - 8.6 Mapping Symbols -9 80386 Dependent Features - 9.1 Options - 9.2 AT&T Syntax versus Intel Syntax - 9.3 Instruction Naming - 9.4 Register Naming - 9.5 Instruction Prefixes - 9.6 Memory References - 9.7 Handling of Jump Instructions - 9.8 Floating Point - 9.9 Intel's MMX and AMD's 3DNow! SIMD Operations - 9.10 Writing 16-bit Code - 9.11 AT&T Syntax bugs - 9.12 Specifying CPU Architecture - 9.13 Notes -10 IA-64 Dependent Features - 10.1 Options - 10.2 Syntax - 10.2.1 Special Characters - 10.2.2 Register Names - 10.2.3 IA-64 Processor-Status-Register (PSR) Bit Names - 10.3 Opcodes -11 MIPS Dependent Features - 11.1 Assembler options - 11.2 MIPS ECOFF object code - 11.3 Directives for debugging information - 11.4 Directives to override the size of symbols - 11.5 Directives to override the ISA level - 11.6 Directives for extending MIPS 16 bit instructions - 11.7 Directive to mark data as an instruction - 11.8 Directives to save and restore options - 11.9 Directives to control generation of MIPS ASE instructions -12 PowerPC Dependent Features - 12.1 Options - 12.2 PowerPC Assembler Directives -13 SPARC Dependent Features - 13.1 Options - 13.2 Enforcing aligned data - 13.3 Floating Point - 13.4 Sparc Machine Directives -14 Reporting Bugs - 14.1 Have You Found a Bug? - 14.2 How to Report Bugs -15 Acknowledgements -Appendix A GNU Free Documentation License - ADDENDUM: How to use this License for your documents -AS Index -Using as -******** - -This file is a user guide to the GNU assembler 'as' version "2.17.50 -[FreeBSD] 2007-07-03". This version of the file describes 'as' -configured to generate code for machine specific architectures. - - 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". - -1 Overview -********** - -Here is a brief summary of how to invoke 'as'. For details, see *note -Command-Line Options: Invoking. - - 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] - - - -'@FILE' - Read command-line options from FILE. The options read are inserted - in place of the original @FILE option. If FILE does not exist, or - cannot be read, then the option will be treated literally, and not - removed. - - Options in 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 FILE may itself contain additional - @FILE options; any such options will be processed recursively. - -'-a[cdhlmns]' - Turn on listings, in any of a variety of ways: - - '-ac' - omit false conditionals - - '-ad' - omit debugging directives - - '-ah' - include high-level source - - '-al' - include assembly - - '-am' - include macro expansions - - '-an' - omit forms processing - - '-as' - include symbols - - '=file' - set the name of the listing file - - You may combine these options; for example, use '-aln' for assembly - listing without forms processing. The '=file' option, if used, - must be the last one. By itself, '-a' defaults to '-ahls'. - -'--alternate' - Begin in alternate macro mode. *Note '.altmacro': Altmacro. - -'-D' - Ignored. This option is accepted for script compatibility with - calls to other assemblers. - -'--defsym SYM=VALUE' - Define the symbol SYM to be VALUE before assembling the input file. - VALUE must be an integer constant. As in C, a leading '0x' - indicates a hexadecimal value, and a leading '0' indicates an octal - value. The value of the symbol can be overridden inside a source - file via the use of a '.set' pseudo-op. - -'-f' - "fast"--skip whitespace and comment preprocessing (assume source is - compiler output). - -'-g' -'--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. - -'--gstabs' - Generate stabs debugging information for each assembler line. This - may help debugging assembler code, if the debugger can handle 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. - -'--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. - -'--help' - Print a summary of the command line options and exit. - -'--target-help' - Print a summary of all target specific options and exit. - -'-I DIR' - Add directory DIR to the search list for '.include' directives. - -'-J' - Don't warn about signed overflow. - -'-K' - This option is accepted but has no effect on the machine specific - family. - -'-L' -'--keep-locals' - Keep (in the symbol table) local symbols. These symbols start with - system-specific local label prefixes, typically '.L' for ELF - systems or 'L' for traditional a.out systems. *Note Symbol - Names::. - -'--listing-lhs-width=NUMBER' - Set the maximum width, in words, of the output data column for an - assembler listing to NUMBER. - -'--listing-lhs-width2=NUMBER' - Set the maximum width, in words, of the output data column for - continuation lines in an assembler listing to NUMBER. - -'--listing-rhs-width=NUMBER' - Set the maximum width of an input source line, as displayed in a - listing, to NUMBER bytes. - -'--listing-cont-lines=NUMBER' - Set the maximum number of lines printed in a listing for a single - line of input to NUMBER + 1. - -'-o OBJFILE' - Name the object-file output from 'as' OBJFILE. - -'-R' - Fold the data section into the text section. - - Set the default size of GAS's hash tables to a prime number close - to 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. - -'--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 '--hash-size=4051', but in the future it may have other - effects as well. - -'--statistics' - Print the maximum space (in bytes) and total time (in seconds) used - by assembly. - -'--strip-local-absolute' - Remove local absolute symbols from the outgoing symbol table. - -'-v' -'-version' - Print the 'as' version. - -'--version' - Print the 'as' version and exit. - -'-W' -'--no-warn' - Suppress warning messages. - -'--fatal-warnings' - Treat warnings as errors. - -'--warn' - Don't suppress warning messages or treat them as errors. - -'-w' - Ignored. - -'-x' - Ignored. - -'-Z' - Generate an object file even after errors. - -'-- | FILES ...' - Standard input, or source files to assemble. - - The following options are available when as is configured for the ARM -processor family. - -'-mcpu=PROCESSOR[+EXTENSION...]' - Specify which ARM processor variant is the target. -'-march=ARCHITECTURE[+EXTENSION...]' - Specify which ARM architecture variant is used by the target. -'-mfpu=FLOATING-POINT-FORMAT' - Select which Floating Point architecture is the target. -'-mfloat-abi=ABI' - Select which floating point ABI is in use. -'-mthumb' - Enable Thumb only instruction decoding. -'-mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant' - Select which procedure calling convention is in use. -'-EB | -EL' - Select either big-endian (-EB) or little-endian (-EL) output. -'-mthumb-interwork' - Specify that the code has been generated with interworking between - Thumb and ARM code in mind. -'-k' - Specify that PIC code has been generated. - - The following options are available when 'as' is configured for the -SPARC architecture: - -'-Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite' -'-Av8plus | -Av8plusa | -Av9 | -Av9a' - Explicitly select a variant of the SPARC architecture. - - '-Av8plus' and '-Av8plusa' select a 32 bit environment. '-Av9' and - '-Av9a' select a 64 bit environment. - - '-Av8plusa' and '-Av9a' enable the SPARC V9 instruction set with - UltraSPARC extensions. - -'-xarch=v8plus | -xarch=v8plusa' - For compatibility with the Solaris v9 assembler. These options are - equivalent to -Av8plus and -Av8plusa, respectively. - -'-bump' - Warn when the assembler switches to another architecture. - - The following options are available when as is configured for a MIPS -processor. - -'-G NUM' - This option sets the largest size of an object that can be - referenced implicitly with the 'gp' register. It is only accepted - for targets that use ECOFF format, such as a DECstation running - Ultrix. The default value is 8. - -'-EB' - Generate "big endian" format output. - -'-EL' - Generate "little endian" format output. - -'-mips1' -'-mips2' -'-mips3' -'-mips4' -'-mips5' -'-mips32' -'-mips32r2' -'-mips64' -'-mips64r2' - Generate code for a particular MIPS Instruction Set Architecture - level. '-mips1' is an alias for '-march=r3000', '-mips2' is an - alias for '-march=r6000', '-mips3' is an alias for '-march=r4000' - and '-mips4' is an alias for '-march=r8000'. '-mips5', '-mips32', - '-mips32r2', '-mips64', and '-mips64r2' correspond to generic 'MIPS - V', 'MIPS32', 'MIPS32 Release 2', 'MIPS64', and 'MIPS64 Release 2' - ISA processors, respectively. - -'-march=CPU' - Generate code for a particular MIPS cpu. - -'-mtune=CPU' - Schedule and tune for a particular MIPS cpu. - -'-mfix7000' -'-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. - -'-mdebug' -'-no-mdebug' - Cause stabs-style debugging output to go into an ECOFF-style - .mdebug section instead of the standard ELF .stabs sections. - -'-mpdr' -'-mno-pdr' - Control generation of '.pdr' sections. - -'-mgp32' -'-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. '-mgp32' controls the size of - general-purpose registers and '-mfp32' controls the size of - floating-point registers. - -'-mips16' -'-no-mips16' - Generate code for the MIPS 16 processor. This is equivalent to - putting '.set mips16' at the start of the assembly file. - '-no-mips16' turns off this option. - -'-msmartmips' -'-mno-smartmips' - Enables the SmartMIPS extension to the MIPS32 instruction set. - This is equivalent to putting '.set smartmips' at the start of the - assembly file. '-mno-smartmips' turns off this option. - -'-mips3d' -'-no-mips3d' - Generate code for the MIPS-3D Application Specific Extension. This - tells the assembler to accept MIPS-3D instructions. '-no-mips3d' - turns off this option. - -'-mdmx' -'-no-mdmx' - Generate code for the MDMX Application Specific Extension. This - tells the assembler to accept MDMX instructions. '-no-mdmx' turns - off this option. - -'-mdsp' -'-mno-dsp' - Generate code for the DSP Release 1 Application Specific Extension. - This tells the assembler to accept DSP Release 1 instructions. - '-mno-dsp' turns off this option. - -'-mdspr2' -'-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. '-mno-dspr2' turns off this option. - -'-mmt' -'-mno-mt' - Generate code for the MT Application Specific Extension. This - tells the assembler to accept MT instructions. '-mno-mt' turns off - this option. - -'--construct-floats' -'--no-construct-floats' - The '--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 '--construct-floats' - is selected, allowing construction of these floating point - constants. - -'--emulation=NAME' - This option causes 'as' to emulate '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: - 'mipsecoff', 'mipself', 'mipslecoff', 'mipsbecoff', 'mipslelf', - '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 'b' or 'l' in the name. Using '-EB' or '-EL' will override - the endianness selection in any case. - - This option is currently supported only when the primary target - 'as' is configured for is a MIPS ELF or ECOFF target. Furthermore, - the primary target or others specified with '--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. - - Eventually, this option will support more configurations, with more - fine-grained control over the assembler's behavior, and will be - supported for more processors. - -'-nocpp' - 'as' ignores this option. It is accepted for compatibility with - the native tools. - -'--trap' -'--no-trap' -'--break' -'--no-break' - Control how to deal with multiplication overflow and division by - zero. '--trap' or '--no-break' (which are synonyms) take a trap - exception (and only work for Instruction Set Architecture level 2 - and higher); '--break' or '--no-trap' (also synonyms, and the - default) take a break exception. - -'-n' - When this option is used, 'as' will issue a warning every time it - generates a nop instruction from a macro. - -1.1 Structure of this Manual -============================ - -This manual is intended to describe what you need to know to use GNU -'as'. We cover the syntax expected in source files, including notation -for symbols, constants, and expressions; the directives that 'as' -understands; and of course how to invoke 'as'. - - We also cover special features in the machine specific configuration -of 'as', including assembler directives. - - On the other hand, this manual is _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 _not_ describe the instruction set, standard -mnemonics, registers or addressing modes that are standard to a -particular architecture. - -1.2 The GNU Assembler -===================== - -GNU 'as' is really a family of assemblers. This manual describes '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 "pseudo-ops") and assembler syntax. - - 'as' is primarily intended to assemble the output of the GNU C -compiler 'gcc' for use by the linker 'ld'. Nevertheless, we've tried to -make 'as' assemble correctly everything that other assemblers for the -same machine would assemble. - - Unlike older assemblers, 'as' is designed to assemble a source -program in one pass of the source file. This has a subtle impact on the -'.org' directive (*note '.org': Org.). - -1.3 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. *Note Symbol -Attributes: Symbol Attributes. For the machine specific target, 'as' is -configured to produce ELF format object files. - -1.4 Command Line -================ - -After the program name '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. - - '--' (two hyphens) by itself names the standard input file -explicitly, as one of the files for 'as' to assemble. - - Except for '--' any command line argument that begins with a hyphen -('-') is an option. Each option changes the behavior of 'as'. No -option changes the way another option works. An option is a '-' -followed by one or more letters; the case of the letter is important. -All options are optional. - - 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: - - as -o my-object-file.o mumble.s - as -omy-object-file.o mumble.s - -1.5 Input Files -=============== - -We use the phrase "source program", abbreviated "source", to describe -the program input to one run of '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. - - The source program is a concatenation of the text in all the files, -in the order specified. - - Each time you run '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.) - - You give '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. - - If you give 'as' no file names it attempts to read one input file -from the 'as' standard input, which is normally your terminal. You may -have to type <ctl-D> to tell 'as' there is no more program to assemble. - - Use '--' if you need to explicitly name the standard input file in -your command line. - - If the source is empty, 'as' produces a small, empty object file. - -Filenames and Line-numbers --------------------------- - -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 -"logical" file. *Note Error and Warning Messages: Errors. - - "Physical files" are those files named in the command line given to -'as'. - - "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 'as' source -is itself synthesized from other files. 'as' understands the '#' -directives emitted by the 'gcc' preprocessor. See also *note '.file': -File. - -1.6 Output (Object) File -======================== - -Every time you run '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 'a.out'. You can give it another name -by using the '-o' option. Conventionally, object file names end with -'.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 'a.out' format.) - - The object file is meant for input to the linker 'ld'. It contains -assembled program code, information to help 'ld' integrate the assembled -program into a runnable file, and (optionally) symbolic information for -the debugger. - -1.7 Error and Warning Messages -============================== - -'as' may write warnings and error messages to the standard error file -(usually your terminal). This should not happen when a compiler runs -'as' automatically. Warnings report an assumption made so that 'as' -could keep assembling a flawed program; errors report a grave problem -that stops the assembly. - - Warning messages have the format - - file_name:NNN:Warning Message Text - -(where NNN is a line number). If a logical file name has been given -(*note '.file': 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). - - Error messages have the format - file_name:NNN:FATAL:Error Message Text - 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. - -2 Command-Line Options -********************** - -This chapter describes command-line options available in _all_ versions -of the GNU assembler; see *note Machine Dependencies::, for options -specific to the machine specific target. - - If you are invoking 'as' via the GNU C compiler, you can use the -'-Wa' option to pass arguments through to the assembler. The assembler -arguments must be separated from each other (and the '-Wa') by commas. -For example: - - gcc -c -g -O -Wa,-alh,-L file.c - -This passes two options to the assembler: '-alh' (emit a listing to -standard output with high-level and assembly source) and '-L' (retain -local symbols in the symbol table). - - Usually you do not need to use this '-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 '-v' -option to see precisely what options it passes to each compilation pass, -including the assembler.) - -2.1 Enable Listings: '-a[cdhlns]' -================================= - -These options enable listing output from the assembler. By itself, '-a' -requests high-level, assembly, and symbols listing. You can use other -letters to select specific options for the list: '-ah' requests a -high-level language listing, '-al' requests an output-program assembly -listing, and '-as' requests a symbol table listing. High-level listings -require that a compiler debugging option like '-g' be used, and that -assembly listings ('-al') be requested also. - - Use the '-ac' option to omit false conditionals from a listing. Any -lines which are not assembled because of a false '.if' (or '.ifdef', or -any other conditional), or a true '.if' followed by an '.else', will be -omitted from the listing. - - Use the '-ad' option to omit debugging directives from the listing. - - Once you have specified one of these options, you can further control -listing output and its appearance using the directives '.list', -'.nolist', '.psize', '.eject', '.title', and '.sbttl'. The '-an' option -turns off all forms processing. If you do not request listing output -with one of the '-a' options, the listing-control directives have no -effect. - - The letters after '-a' may be combined into one option, _e.g._, -'-aln'. - - Note if the assembler source is coming from the standard input (e.g., -because it is being created by 'gcc' and the '-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. - -2.2 '--alternate' -================= - -Begin in alternate macro mode, see *note '.altmacro': Altmacro. - -2.3 '-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 'as'. - -2.4 Work Faster: '-f' -===================== - -'-f' should only be used when assembling programs written by a (trusted) -compiler. '-f' stops the assembler from doing whitespace and comment -preprocessing on the input file(s) before assembling them. *Note -Preprocessing: Preprocessing. - - _Warning:_ if you use '-f' when the files actually need to be - preprocessed (if they contain comments, for example), 'as' does not - work correctly. - -2.5 '.include' Search Path: '-I' PATH -===================================== - -Use this option to add a PATH to the list of directories 'as' searches -for files specified in '.include' directives (*note '.include': -Include.). You may use '-I' as many times as necessary to include a -variety of paths. The current working directory is always searched -first; after that, 'as' searches any '-I' directories in the same order -as they were specified (left to right) on the command line. - -2.6 Difference Tables: '-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 '.word' directives in difference tables. -The machine specific family does not have the addressing limitations -that sometimes lead to this alteration on other platforms. - -2.7 Include Local Symbols: '-L' -=============================== - -Symbols beginning with system-specific local label prefixes, typically -'.L' for ELF systems or 'L' for traditional a.out systems, are called -"local symbols". *Note 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 'as' and 'ld' discard such symbols, so you do not -normally debug with them. - - This option tells 'as' to retain those local symbols in the object -file. Usually if you do this you also tell the linker 'ld' to preserve -those symbols. - -2.8 Configuring listing output: '--listing' -=========================================== - -The listing feature of the assembler can be enabled via the command line -switch '-a' (*note 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., -'.list' (*note List::), '.title' (*note Title::), '.sbttl' (*note -Sbttl::), '.psize' (*note Psize::), and '.eject' (*note Eject::) and -also by the following switches: - -'--listing-lhs-width='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. - -'--listing-lhs-width2='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 - '--listing-lhs-width'. If neither switch is used the default is to - one. - -'--listing-rhs-width='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. - -'--listing-cont-lines='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. - -2.9 Assemble in MRI Compatibility Mode: '-M' -============================================ - -The '-M' or '--mri' option selects MRI compatibility mode. This changes -the syntax and pseudo-op handling of 'as' to make it compatible with the -'ASM68K' or the '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 'as'. - - 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: - - * global symbols in common section - - The m68k MRI assembler supports common sections which are merged by - the linker. Other object file formats do not support this. '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. - - * complex relocations - - 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. - - * 'END' pseudo-op specifying start address - - The MRI '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 '-e' option to the - linker, or in a linker script. - - * 'IDNT', '.ident' and 'NAME' pseudo-ops - - The MRI 'IDNT', '.ident' and 'NAME' pseudo-ops assign a module name - to the output file. This is not supported by other object file - formats. - - * 'ORG' pseudo-op - - The m68k MRI 'ORG' pseudo-op begins an absolute section at a given - address. This differs from the usual 'as' '.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. - - There are some other features of the MRI assembler which are not -supported by 'as', typically either because they are difficult or -because they seem of little consequence. Some of these may be supported -in future releases. - - * EBCDIC strings - - EBCDIC strings are not supported. - - * packed binary coded decimal - - Packed binary coded decimal is not supported. This means that the - 'DC.P' and 'DCB.P' pseudo-ops are not supported. - - * 'FEQU' pseudo-op - - The m68k 'FEQU' pseudo-op is not supported. - - * 'NOOBJ' pseudo-op - - The m68k 'NOOBJ' pseudo-op is not supported. - - * 'OPT' branch control options - - The m68k 'OPT' branch control options--'B', 'BRS', 'BRB', 'BRL', - and 'BRW'--are ignored. 'as' automatically relaxes all branches, - whether forward or backward, to an appropriate size, so these - options serve no purpose. - - * 'OPT' list control options - - The following m68k 'OPT' list control options are ignored: 'C', - 'CEX', 'CL', 'CRE', 'E', 'G', 'I', 'M', 'MEX', 'MC', 'MD', 'X'. - - * other 'OPT' options - - The following m68k 'OPT' options are ignored: 'NEST', 'O', 'OLD', - 'OP', 'P', 'PCO', 'PCR', 'PCS', 'R'. - - * 'OPT' 'D' option is default - - The m68k 'OPT' 'D' option is the default, unlike the MRI assembler. - 'OPT NOD' may be used to turn it off. - - * 'XREF' pseudo-op. - - The m68k 'XREF' pseudo-op is ignored. - - * '.debug' pseudo-op - - The i960 '.debug' pseudo-op is not supported. - - * '.extended' pseudo-op - - The i960 '.extended' pseudo-op is not supported. - - * '.list' pseudo-op. - - The various options of the i960 '.list' pseudo-op are not - supported. - - * '.optimize' pseudo-op - - The i960 '.optimize' pseudo-op is not supported. - - * '.output' pseudo-op - - The i960 '.output' pseudo-op is not supported. - - * '.setreal' pseudo-op - - The i960 '.setreal' pseudo-op is not supported. - -2.10 Dependency Tracking: '--MD' -================================ - -'as' can generate a dependency file for the file it creates. This file -consists of a single rule suitable for 'make' describing the -dependencies of the main source file. - - The rule is written to the file named in its argument. - - This feature is used in the automatic updating of makefiles. - -2.11 Name the Object File: '-o' -=============================== - -There is always one object file output when you run 'as'. By default it -has the name 'a.out'. You use this option (which takes exactly one -filename) to give the object file a different name. - - Whatever the object file is called, 'as' overwrites any existing file -of the same name. - -2.12 Join Data and Text Sections: '-R' -====================================== - -'-R' tells '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. (*Note -Sections and Relocation: Sections.) - - When you specify '-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 'as'. In future, '-R' may work this way. - - When 'as' is configured for COFF or ELF output, this option is only -useful if you use sections named '.text' and '.data'. - -2.13 Display Assembly Statistics: '--statistics' -================================================ - -Use '--statistics' to display two statistics about the resources used by -'as': the maximum amount of space allocated during the assembly (in -bytes), and the total execution time taken for the assembly (in CPU -seconds). - -2.14 Compatible Output: '--traditional-format' -============================================== - -For some targets, the output of 'as' is different in some ways from the -output of some existing assembler. This switch requests 'as' to use the -traditional format instead. - - For example, it disables the exception frame optimizations which 'as' -normally does by default on 'gcc' output. - -2.15 Announce Version: '-v' -=========================== - -You can find out what version of as is running by including the option -'-v' (which you can also spell as '-version') on the command line. - -2.16 Control Warnings: '-W', '--warn', '--no-warn', '--fatal-warnings' -====================================================================== - -'as' should never give a warning or error message when assembling -compiler output. But programs written by people often cause 'as' to -give a warning that a particular assumption was made. All such warnings -are directed to the standard error file. - - If you use the '-W' and '--no-warn' options, no warnings are issued. -This only affects the warning messages: it does not change any -particular of how 'as' assembles your file. Errors, which stop the -assembly, are still reported. - - If you use the '--fatal-warnings' option, 'as' considers files that -generate warnings to be in error. - - You can switch these options off again by specifying '--warn', which -causes warnings to be output as usual. - -2.17 Generate Object File in Spite of Errors: '-Z' -================================================== - -After an error message, 'as' normally produces no output. If for some -reason you are interested in object file output even after 'as' gives an -error message on your program, use the '-Z' option. If there are any -errors, 'as' continues anyways, and writes an object file after a final -warning message of the form 'N errors, M warnings, generating bad object -file.' - -3 Syntax -******** - -This chapter describes the machine-independent syntax allowed in a -source file. 'as' syntax is similar to what many other assemblers use; -it is inspired by the BSD 4.2 assembler. - -3.1 Preprocessing -================= - -The 'as' internal preprocessor: - * 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. - - * removes all comments, replacing them with a single space, or an - appropriate number of newlines. - - * converts character constants into the appropriate numeric values. - - 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 '.include' directive (*note '.include': -Include.). You can use the GNU C compiler driver to get other "CPP" -style preprocessing by giving the input file a '.S' suffix. *Note -Options Controlling the Kind of Output: (gcc.info)Overall Options. - - Excess whitespace, comments, and character constants cannot be used -in the portions of the input text that are not preprocessed. - - If the first line of an input file is '#NO_APP' or if you use the -'-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 '#APP' -before the text that may contain whitespace or comments, and putting a -line that says '#NO_APP' after this text. This feature is mainly intend -to support 'asm' statements in compilers whose output is otherwise free -of comments and whitespace. - -3.2 Whitespace -============== - -"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 (*note Character Constants: -Characters.), any whitespace means the same as exactly one space. - -3.3 Comments -============ - -There are two ways of rendering comments to 'as'. In both cases the -comment is equivalent to one space. - - Anything from '/*' through the next '*/' is a comment. This means -you may not nest these comments. - - /* - The only way to include a newline ('\n') in a comment - is to use this sort of comment. - */ - - /* This sort of comment does not nest. */ - - Anything from the "line comment" character to the next newline is -considered a comment and is ignored. The line comment character is '@' -on the ARM; '#' on the i386 and x86-64; '#' for Motorola PowerPC; '!' on -the SPARC; see *note Machine Dependencies::. - - To be compatible with past assemblers, lines that begin with '#' have -a special interpretation. Following the '#' should be an absolute -expression (*note Expressions::): the logical line number of the _next_ -line. Then a string (*note Strings: Strings.) is allowed: if present it -is a new logical file name. The rest of the line, if any, should be -whitespace. - - If the first non-whitespace characters on the line are not numeric, -the line is ignored. (Just like a comment.) - - # This is an ordinary comment. - # 42-6 "new_file_name" # New logical file name - # This is logical line # 36. - This feature is deprecated, and may disappear from future versions of -'as'. - -3.4 Symbols -=========== - -A "symbol" is one or more characters chosen from the set of all letters -(both upper and lower case), digits and the three characters '_.$'. 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). *Note Symbols::. - -3.5 Statements -============== - -A "statement" ends at a newline character ('\n') or at a semicolon -(';'). 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. - - It is an error to end any statement with end-of-file: the last -character of any input file should be a newline. - - An empty statement is allowed, and may include whitespace. It is -ignored. - - 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 '.' 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 "instruction": it -assembles into a machine language instruction. - - A label is a symbol immediately followed by a colon (':'). -Whitespace before a label or after a colon is permitted, but you may not -have whitespace between a label's symbol and its colon. *Note Labels::. - - label: .directive followed by something - another_label: # This is an empty statement. - instruction operand_1, operand_2, ... - -3.6 Constants -============= - -A constant is a number, written so that its value is known by -inspection, without knowing any context. Like this: - .byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value. - .ascii "Ring the bell\7" # A string constant. - .octa 0x123456789abcdef0123456789ABCDEF0 # A bignum. - .float 0f-314159265358979323846264338327\ - 95028841971.693993751E-40 # - pi, a flonum. - -3.6.1 Character Constants -------------------------- - -There are two kinds of character constants. A "character" stands for -one character in one byte and its value may be used in numeric -expressions. String constants (properly called string _literals_) are -potentially many bytes and their values may not be used in arithmetic -expressions. - -3.6.1.1 Strings -............... - -A "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 "escape" these characters: precede them with a -backslash '\' character. For example '\\' represents one backslash: the -first '\' is an escape which tells 'as' to interpret the second -character literally as a backslash (which prevents 'as' from recognizing -the second '\' as an escape character). The complete list of escapes -follows. - -'\b' - Mnemonic for backspace; for ASCII this is octal code 010. - -'\f' - Mnemonic for FormFeed; for ASCII this is octal code 014. - -'\n' - Mnemonic for newline; for ASCII this is octal code 012. - -'\r' - Mnemonic for carriage-Return; for ASCII this is octal code 015. - -'\t' - Mnemonic for horizontal Tab; for ASCII this is octal code 011. - -'\ DIGIT DIGIT 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, '\008' has the value 010, and '\009' the value - 011. - -'\x HEX-DIGITS...' - A hex character code. All trailing hex digits are combined. - Either upper or lower case 'x' works. - -'\\' - Represents one '\' character. - -'\"' - Represents one '"' character. Needed in strings to represent this - character, because an unescaped '"' would end the string. - -'\ ANYTHING-ELSE' - Any other character when escaped by '\' gives a warning, but - assembles as if the '\' 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 'as' has no - other interpretation, so 'as' knows it is giving you the wrong code - and warns you of the fact. - - 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. - -3.6.1.2 Characters -.................. - -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 ''\\' -where the first '\' escapes the second '\'. As you can see, the quote -is an acute accent, not a grave accent. A newline (or semicolon ';') -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. 'as' assumes your character code is ASCII: ''A' means -65, ''B' means 66, and so on. - -3.6.2 Number Constants ----------------------- - -'as' distinguishes three kinds of numbers according to how they are -stored in the target machine. _Integers_ are numbers that would fit -into an 'int' in the C language. _Bignums_ are integers, but they are -stored in more than 32 bits. _Flonums_ are floating point numbers, -described below. - -3.6.2.1 Integers -................ - -A binary integer is '0b' or '0B' followed by zero or more of the binary -digits '01'. - - An octal integer is '0' followed by zero or more of the octal digits -('01234567'). - - A decimal integer starts with a non-zero digit followed by zero or -more digits ('0123456789'). - - A hexadecimal integer is '0x' or '0X' followed by one or more -hexadecimal digits chosen from '0123456789abcdefABCDEF'. - - Integers have the usual values. To denote a negative integer, use -the prefix operator '-' discussed under expressions (*note Prefix -Operators: Prefix Ops.). - -3.6.2.2 Bignums -............... - -A "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. - -3.6.2.3 Flonums -............... - -A "flonum" represents a floating point number. The translation is -indirect: a decimal floating point number from the text is converted by -'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 -'as' specialized to that computer. - - A flonum is written by writing (in order) - * The digit '0'. - - * A letter, to tell 'as' the rest of the number is a flonum. - - * An optional sign: either '+' or '-'. - - * An optional "integer part": zero or more decimal digits. - - * An optional "fractional part": '.' followed by zero or more decimal - digits. - - * An optional exponent, consisting of: - - * An 'E' or 'e'. - * Optional sign: either '+' or '-'. - * One or more decimal digits. - - At least one of the integer part or the fractional part must be -present. The floating point number has the usual base-10 value. - - 'as' does all processing using integers. Flonums are computed -independently of any floating point hardware in the computer running -'as'. - -4 Sections and Relocation -************************* - -4.1 Background -============== - -Roughly, a section is a range of addresses, with no gaps; all data "in" -those addresses is treated the same for some particular purpose. For -example there may be a "read only" section. - - The linker 'ld' reads many object files (partial programs) and -combines their contents to form a runnable program. When 'as' emits an -object file, the partial program is assumed to start at address 0. '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 'as' uses sections. - - '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 _section_. Assigning -run-time addresses to sections is called "relocation". It includes the -task of adjusting mentions of object-file addresses so they refer to the -proper run-time addresses. - - An object file written by 'as' has at least three sections, any of -which may be empty. These are named "text", "data" and "bss" sections. - - 'as' can also generate whatever other named sections you specify -using the '.section' directive (*note '.section': Section.). If you do -not use any directives that place output in the '.text' or '.data' -sections, these sections still exist, but are empty. - - Within the object file, the text section starts at address '0', the -data section follows, and the bss section follows the data section. - - To let 'ld' know which data changes when the sections are relocated, -and how to change that data, 'as' also writes to the object file details -of the relocation needed. To perform relocation 'ld' must know, each -time an address in the object file is mentioned: - * Where in the object file is the beginning of this reference to an - address? - * How long (in bytes) is this reference? - * Which section does the address refer to? What is the numeric value - of - (ADDRESS) - (START-ADDRESS OF SECTION)? - * Is the reference to an address "Program-Counter relative"? - - In fact, every address 'as' ever uses is expressed as - (SECTION) + (OFFSET INTO SECTION) -Further, most expressions 'as' computes have this section-relative -nature. - - In this manual we use the notation {SECNAME N} to mean "offset N into -section SECNAME." - - Apart from text, data and bss sections you need to know about the -"absolute" section. When 'ld' mixes partial programs, addresses in the -absolute section remain unchanged. For example, address '{absolute 0}' -is "relocated" to run-time address 0 by 'ld'. Although the linker never -arranges two partial programs' data sections with overlapping addresses -after linking, _by definition_ their absolute sections must overlap. -Address '{absolute 239}' in one part of a program is always the same -address when the program is running as address '{absolute 239}' in any -other part of the program. - - The idea of sections is extended to the "undefined" section. Any -address whose section is unknown at assembly time is by definition -rendered {undefined U}--where 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 _undefined_. - - By analogy the word _section_ is used to describe groups of sections -in the linked program. 'ld' puts all partial programs' text sections in -contiguous addresses in the linked program. It is customary to refer to -the _text section_ of a program, meaning all the addresses of all -partial programs' text sections. Likewise for data and bss sections. - - Some sections are manipulated by 'ld'; others are invented for use of -'as' and have no meaning except during assembly. - -4.2 Linker Sections -=================== - -'ld' deals with just four kinds of sections, summarized below. - -*named sections* - These sections hold your program. 'as' and '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. - -*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. - -*absolute section* - Address 0 of this section is always "relocated" to runtime address - 0. This is useful if you want to refer to an address that 'ld' - must not change when relocating. In this sense we speak of - absolute addresses being "unrelocatable": they do not change during - relocation. - -*undefined section* - This "section" is a catch-all for address references to objects not - in the preceding sections. - - An idealized example of three relocatable sections follows. The -example uses the traditional section names '.text' and '.data'. Memory -addresses are on the horizontal axis. - - +-----+----+--+ - 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 ... - -4.3 Assembler Internal Sections -=============================== - -These sections are meant only for the internal use of '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 'as' warning -messages, so it might be helpful to have an idea of their meanings to -'as'. These sections are used to permit the value of every expression -in your assembly language program to be a section-relative address. - -ASSEMBLER-INTERNAL-LOGIC-ERROR! - An internal assembler logic error has been found. This means there - is a bug in the assembler. - -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. - -4.4 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. 'as' allows you to use -"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 '.text 0' before each section of code being -output, and a '.text 1' before each group of constants being output. - - Subsections are optional. If you do not use subsections, everything -goes in subsection number zero. - - 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; -'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. - - To specify which subsection you want subsequent statements assembled -into, use a numeric argument to specify it, in a '.text EXPRESSION' or a -'.data EXPRESSION' statement. You can also use the '.subsection' -directive (*note SubSection::) to specify a subsection: '.subsection -EXPRESSION'. EXPRESSION should be an absolute expression (*note -Expressions::). If you just say '.text' then '.text 0' is assumed. -Likewise '.data' means '.data 0'. Assembly begins in 'text 0'. For -instance: - .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 (*)." - - Each section has a "location counter" incremented by one for every -byte assembled into that section. Because subsections are merely a -convenience restricted to 'as' there is no concept of a subsection -location counter. There is no way to directly manipulate a location -counter--but the '.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 "active" location -counter. - -4.5 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. - - The '.lcomm' pseudo-op defines a symbol in the bss section; see *note -'.lcomm': Lcomm. - - The '.comm' pseudo-op may be used to declare a common symbol, which -is another form of uninitialized symbol; see *note '.comm': Comm. - -5 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. - - _Warning:_ 'as' does not place symbols in the object file in the - same order they were declared. This may break some debuggers. - -5.1 Labels -========== - -A "label" is written as a symbol immediately followed by a colon ':'. -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. - -5.2 Giving Symbols Other Values -=============================== - -A symbol can be given an arbitrary value by writing a symbol, followed -by an equals sign '=', followed by an expression (*note Expressions::). -This is equivalent to using the '.set' directive. *Note '.set': Set. -In the same way, using a double equals sign '=''=' here represents an -equivalent of the '.eqv' directive. *Note '.eqv': Eqv. - -5.3 Symbol Names -================ - -Symbol names begin with a letter or with one of '._'. On most machines, -you can also use '$' in symbol names; exceptions are noted in *note -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. - - Case of letters is significant: 'foo' is a different symbol name than -'Foo'. - - 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. - -Local Symbol Names ------------------- - -A local symbol is any symbol beginning with certain local label -prefixes. By default, the local label prefix is '.L' for ELF systems or -'L' for traditional a.out systems, but each target may have its own set -of local label prefixes. - - 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 '-L' option (*note Include Local Symbols: -'-L': L.) to retain the local symbols in the object files. - -Local Labels ------------- - -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 'N:' -(where N represents any positive integer). To refer to the most recent -previous definition of that label write 'Nb', using the same number as -when you defined the label. To refer to the next definition of a local -label, write 'Nf'--the 'b' stands for "backwards" and the 'f' stands for -"forwards". - - 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 '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 ('0:'...'9:') are implemented in a slightly more efficient manner -than the others. - - Here is an example: - - 1: branch 1f - 2: branch 1b - 1: branch 2f - 2: branch 1b - - Which is the equivalent of: - - label_1: branch label_3 - label_2: branch label_1 - label_3: branch label_4 - label_4: branch label_3 - - 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: - -'_local label prefix_' - All local symbols begin with the system-specific local label - prefix. Normally both 'as' and '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 '-L' option then 'as' - retains these symbols in the object file. If you also instruct - 'ld' to retain these symbols, you may use them in debugging. - -'NUMBER' - This is the number that was used in the local label definition. So - if the label is written '55:' then the number is '55'. - -'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 - '\002' (control-B). - -'_ordinal number_' - This is a serial number to keep the labels distinct. The first - definition of '0:' gets the number '1'. The 15th definition of - '0:' gets the number '15', and so on. Likewise the first - definition of '1:' gets the number '1' and its 15th definition gets - '15' as well. - - So for example, the first '1:' may be named '.L1C-B1', and the 44th -'3:' may be named '.L3C-B44'. - -Dollar Local Labels -------------------- - -'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. - - 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., '55$'. - - They can also be distinguished from ordinary local labels by their -transformed names which use ASCII character '\001' (control-A) as the -magic character to distinguish them from ordinary labels. For example, -the fifth definition of '6$' may be named '.L6'C-A'5'. - -5.4 The Special Dot Symbol -========================== - -The special symbol '.' refers to the current address that 'as' is -assembling into. Thus, the expression 'melvin: .long .' defines -'melvin' to contain its own address. Assigning a value to '.' is -treated the same as a '.org' directive. Thus, the expression '.=.+4' is -the same as saying '.space 4'. - -5.5 Symbol Attributes -===================== - -Every symbol has, as well as its name, the attributes "Value" and -"Type". Depending on output format, symbols can also have auxiliary -attributes. The detailed definitions are in 'a.out.h'. - - If you use a symbol without defining it, '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. - -5.5.1 Value ------------ - -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 'ld' changes section base addresses during linking. Absolute -symbols' values do not change during linking: that is why they are -called absolute. - - 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 -'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 '.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. - -5.5.2 Type ----------- - -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. - -6 Expressions -************* - -An "expression" specifies an address or numeric value. Whitespace may -precede and/or follow an expression. - - 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 '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. 'as' aborts with an error message in this situation. - -6.1 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 'as' assumes a value of (absolute) 0. This is -compatible with other assemblers. - -6.2 Integer Expressions -======================= - -An "integer expression" is one or more _arguments_ delimited by -_operators_. - -6.2.1 Arguments ---------------- - -"Arguments" are symbols, numbers or subexpressions. In other contexts -arguments are sometimes called "arithmetic operands". In this manual, -to avoid confusing them with the "instruction operands" of the machine -language, we use the term "argument" to refer to parts of expressions -only, reserving the word "operand" to refer only to machine instruction -operands. - - Symbols are evaluated to yield {SECTION NNN} where SECTION is one of -text, data, bss, absolute, or undefined. NNN is a signed, 2's -complement 32 bit integer. - - Numbers are usually integers. - - A number can be a flonum or bignum. In this case, you are warned -that only the low order 32 bits are used, and 'as' pretends these 32 -bits are an integer. You may write integer-manipulating instructions -that act on exotic constants, compatible with other assemblers. - - Subexpressions are a left parenthesis '(' followed by an integer -expression, followed by a right parenthesis ')'; or a prefix operator -followed by an argument. - -6.2.2 Operators ---------------- - -"Operators" are arithmetic functions, like '+' or '%'. Prefix operators -are followed by an argument. Infix operators appear between their -arguments. Operators may be preceded and/or followed by whitespace. - -6.2.3 Prefix Operator ---------------------- - -'as' has the following "prefix operators". They each take one argument, -which must be absolute. - -'-' - "Negation". Two's complement negation. -'~' - "Complementation". Bitwise not. - -6.2.4 Infix Operators ---------------------- - -"Infix operators" take two arguments, one on either side. Operators -have precedence, but operations with equal precedence are performed left -to right. Apart from '+' or '-', both arguments must be absolute, and -the result is absolute. - - 1. Highest Precedence - - '*' - "Multiplication". - - '/' - "Division". Truncation is the same as the C operator '/' - - '%' - "Remainder". - - '<<' - "Shift Left". Same as the C operator '<<'. - - '>>' - "Shift Right". Same as the C operator '>>'. - - 2. Intermediate precedence - - '|' - - "Bitwise Inclusive Or". - - '&' - "Bitwise And". - - '^' - "Bitwise Exclusive Or". - - '!' - "Bitwise Or Not". - - 3. Low Precedence - - '+' - "Addition". If either argument is absolute, the result has - the section of the other argument. You may not add together - arguments from different sections. - - '-' - "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. - - '==' - "Is Equal To" - '<>' - '!=' - "Is Not Equal To" - '<' - "Is Less Than" - '>' - "Is Greater Than" - '>=' - "Is Greater Than Or Equal To" - '<=' - "Is Less Than Or Equal To" - - 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. - - 4. Lowest Precedence - - '&&' - "Logical And". - - '||' - "Logical Or". - - 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. - - In short, it's only meaningful to add or subtract the _offsets_ in an -address; you can only have a defined section in one of the two -arguments. - -7 Assembler Directives -********************** - -All assembler directives have names that begin with a period ('.'). The -rest of the name is letters, usually in lower case. - - This chapter discusses directives that are available regardless of -the target machine configuration for the GNU assembler. - -7.1 '.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 'as' to quit also. One day -'.abort' will not be supported. - -7.2 '.align ABS-EXPR, ABS-EXPR, 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. - - 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. - - 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. - - 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 '.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. - - 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 '.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. - - This inconsistency is due to the different behaviors of the various -native assemblers for these systems which GAS must emulate. GAS also -provides '.balign' and '.p2align' directives, described later, which -have a consistent behavior across all architectures (but are specific to -GAS). - -7.3 '.ascii "STRING"'... -======================== - -'.ascii' expects zero or more string literals (*note Strings::) -separated by commas. It assembles each string (with no automatic -trailing zero byte) into consecutive addresses. - -7.4 '.asciz "STRING"'... -======================== - -'.asciz' is just like '.ascii', but each string is followed by a zero -byte. The "z" in '.asciz' stands for "zero". - -7.5 '.balign[wl] ABS-EXPR, ABS-EXPR, 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 '.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. - - 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. - - 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. - - The '.balignw' and '.balignl' directives are variants of the -'.balign' directive. The '.balignw' directive treats the fill pattern -as a two byte word value. The '.balignl' directives treats the fill -pattern as a four byte longword value. For example, '.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. - -7.6 '.byte EXPRESSIONS' -======================= - -'.byte' expects zero or more expressions, separated by commas. Each -expression is assembled into the next byte. - -7.7 '.comm SYMBOL , LENGTH ' -============================ - -'.comm' declares a common symbol named 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 'ld' does not see a -definition for the symbol-just one or more common symbols-then it will -allocate LENGTH bytes of uninitialized memory. LENGTH must be an -absolute expression. If '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. - - When using ELF, the '.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 'ld' -allocates uninitialized memory for the common symbol, it will use the -alignment when placing the symbol. If no alignment is specified, '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. - -7.8 '.cfi_startproc [simple]' -============================= - -'.cfi_startproc' is used at the beginning of each function that should -have an entry in '.eh_frame'. It initializes some internal data -structures. Don't forget to close the function by '.cfi_endproc'. - - Unless '.cfi_startproc' is used along with parameter 'simple' it also -emits some architecture dependent initial CFI instructions. - -7.9 '.cfi_endproc' -================== - -'.cfi_endproc' is used at the end of a function where it closes its -unwind entry previously opened by '.cfi_startproc', and emits it to -'.eh_frame'. - -7.10 '.cfi_personality ENCODING [, EXP]' -======================================== - -'.cfi_personality' defines personality routine and its encoding. -ENCODING must be a constant determining how the personality should be -encoded. If it is 255 ('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 '.cfi_startproc' is '.cfi_personality -0xff', no personality routine. - -7.11 '.cfi_lsda ENCODING [, EXP]' -================================= - -'.cfi_lsda' defines LSDA and its encoding. ENCODING must be a constant -determining how the LSDA should be encoded. If it is 255 -('DW_EH_PE_omit'), second argument is not present, otherwise second -argument should be a constant or a symbol name. The default after -'.cfi_startproc' is '.cfi_lsda 0xff', no LSDA. - -7.12 '.cfi_def_cfa REGISTER, OFFSET' -==================================== - -'.cfi_def_cfa' defines a rule for computing CFA as: take address from -REGISTER and add OFFSET to it. - -7.13 '.cfi_def_cfa_register REGISTER' -===================================== - -'.cfi_def_cfa_register' modifies a rule for computing CFA. From now on -REGISTER will be used instead of the old one. Offset remains the same. - -7.14 '.cfi_def_cfa_offset OFFSET' -================================= - -'.cfi_def_cfa_offset' modifies a rule for computing CFA. Register -remains the same, but OFFSET is new. Note that it is the absolute -offset that will be added to a defined register to compute CFA address. - -7.15 '.cfi_adjust_cfa_offset OFFSET' -==================================== - -Same as '.cfi_def_cfa_offset' but OFFSET is a relative value that is -added/substracted from the previous offset. - -7.16 '.cfi_offset REGISTER, OFFSET' -=================================== - -Previous value of REGISTER is saved at offset OFFSET from CFA. - -7.17 '.cfi_rel_offset REGISTER, OFFSET' -======================================= - -Previous value of REGISTER is saved at offset OFFSET from the current -CFA register. This is transformed to '.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. - -7.18 '.cfi_register REGISTER1, REGISTER2' -========================================= - -Previous value of REGISTER1 is saved in register REGISTER2. - -7.19 '.cfi_restore REGISTER' -============================ - -'.cfi_restore' says that the rule for REGISTER is now the same as it was -at the beginning of the function, after all initial instruction added by -'.cfi_startproc' were executed. - -7.20 '.cfi_undefined REGISTER' -============================== - -From now on the previous value of REGISTER can't be restored anymore. - -7.21 '.cfi_same_value REGISTER' -=============================== - -Current value of REGISTER is the same like in the previous frame, i.e. -no restoration needed. - -7.22 '.cfi_remember_state', -=========================== - -First save all current rules for all registers by '.cfi_remember_state', -then totally screw them up by subsequent '.cfi_*' directives and when -everything is hopelessly bad, use '.cfi_restore_state' to restore the -previous saved state. - -7.23 '.cfi_return_column REGISTER' -================================== - -Change return column REGISTER, i.e. the return address is either -directly in REGISTER or can be accessed by rules for REGISTER. - -7.24 '.cfi_signal_frame' -======================== - -Mark current function as signal trampoline. - -7.25 '.cfi_window_save' -======================= - -SPARC register window has been saved. - -7.26 '.cfi_escape' 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. - -7.27 '.file FILENO FILENAME' -============================ - -When emitting dwarf2 line number information '.file' assigns filenames -to the '.debug_line' file name table. The FILENO operand should be a -unique positive integer to use as the index of the entry in the table. -The FILENAME operand is a C string literal. - - The detail of filename indices is exposed to the user because the -filename table is shared with the '.debug_info' section of the dwarf2 -debugging information, and thus the user must know the exact indices -that table entries will have. - -7.28 '.loc FILENO LINENO [COLUMN] [OPTIONS]' -============================================ - -The '.loc' directive will add row to the '.debug_line' line number -matrix corresponding to the immediately following assembly instruction. -The FILENO, LINENO, and optional COLUMN arguments will be applied to the -'.debug_line' state machine before the row is added. - - The OPTIONS are a sequence of the following tokens in any order: - -'basic_block' - This option will set the 'basic_block' register in the - '.debug_line' state machine to 'true'. - -'prologue_end' - This option will set the 'prologue_end' register in the - '.debug_line' state machine to 'true'. - -'epilogue_begin' - This option will set the 'epilogue_begin' register in the - '.debug_line' state machine to 'true'. - -'is_stmt VALUE' - This option will set the 'is_stmt' register in the '.debug_line' - state machine to 'value', which must be either 0 or 1. - -'isa VALUE' - This directive will set the 'isa' register in the '.debug_line' - state machine to VALUE, which must be an unsigned integer. - -7.29 '.loc_mark_blocks ENABLE' -============================== - -The '.loc_mark_blocks' directive makes the assembler emit an entry to -the '.debug_line' line number matrix with the 'basic_block' register in -the state machine set whenever a code label is seen. The ENABLE -argument should be either 1 or 0, to enable or disable this function -respectively. - -7.30 '.data SUBSECTION' -======================= - -'.data' tells 'as' to assemble the following statements onto the end of -the data subsection numbered SUBSECTION (which is an absolute -expression). If SUBSECTION is omitted, it defaults to zero. - -7.31 '.double FLONUMS' -====================== - -'.double' expects zero or more flonums, separated by commas. It -assembles floating point numbers. - -7.32 '.eject' -============= - -Force a page break at this point, when generating assembly listings. - -7.33 '.else' -============ - -'.else' is part of the 'as' support for conditional assembly; see *note -'.if': If. It marks the beginning of a section of code to be assembled -if the condition for the preceding '.if' was false. - -7.34 '.elseif' -============== - -'.elseif' is part of the 'as' support for conditional assembly; see -*note '.if': If. It is shorthand for beginning a new '.if' block that -would otherwise fill the entire '.else' section. - -7.35 '.end' -=========== - -'.end' marks the end of the assembly file. 'as' does not process -anything in the file past the '.end' directive. - -7.36 '.endfunc' -=============== - -'.endfunc' marks the end of a function specified with '.func'. - -7.37 '.endif' -============= - -'.endif' is part of the 'as' support for conditional assembly; it marks -the end of a block of code that is only assembled conditionally. *Note -'.if': If. - -7.38 '.equ SYMBOL, EXPRESSION' -============================== - -This directive sets the value of SYMBOL to EXPRESSION. It is synonymous -with '.set'; see *note '.set': Set. - -7.39 '.equiv SYMBOL, EXPRESSION' -================================ - -The '.equiv' directive is like '.equ' and '.set', except that the -assembler will signal an error if SYMBOL is already defined. Note a -symbol which has been referenced but not actually defined is considered -to be undefined. - - Except for the contents of the error message, this is roughly -equivalent to - .ifdef SYM - .err - .endif - .equ SYM,VAL - plus it protects the symbol from later redefinition. - -7.40 '.eqv SYMBOL, EXPRESSION' -============================== - -The '.eqv' directive is like '.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. - -7.41 '.err' -=========== - -If 'as' assembles a '.err' directive, it will print an error message -and, unless the '-Z' option was used, it will not generate an object -file. This can be used to signal an error in conditionally compiled -code. - -7.42 '.error "STRING"' -====================== - -Similarly to '.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 '".error directive invoked in source -file"'. *Note Error and Warning Messages: Errors. - - .error "This code has not been assembled and tested." - -7.43 '.exitm' -============= - -Exit early from the current macro definition. *Note Macro::. - -7.44 '.extern' -============== - -'.extern' is accepted in the source program--for compatibility with -other assemblers--but it is ignored. 'as' treats all undefined symbols -as external. - -7.45 '.fail EXPRESSION' -======================= - -Generates an error or a warning. If the value of the EXPRESSION is 500 -or more, 'as' will print a warning message. If the value is less than -500, 'as' will print an error message. The message will include the -value of EXPRESSION. This can occasionally be useful inside complex -nested macros or conditional assembly. - -7.46 '.file STRING' -=================== - -'.file' tells 'as' that we are about to start a new logical file. -STRING is the new file name. In general, the filename is recognized -whether or not it is surrounded by quotes '"'; but if you wish to -specify an empty file name, you must give the quotes-'""'. This -statement may go away in future: it is only recognized to be compatible -with old 'as' programs. - -7.47 '.fill REPEAT , SIZE , VALUE' -================================== - -REPEAT, SIZE and VALUE are absolute expressions. This emits REPEAT -copies of SIZE bytes. REPEAT may be zero or more. 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 REPEAT -bytes is taken from an 8-byte number. The highest order 4 bytes are -zero. The lowest order 4 bytes are VALUE rendered in the byte-order of -an integer on the computer 'as' is assembling for. Each SIZE bytes in a -repetition is taken from the lowest order SIZE bytes of this number. -Again, this bizarre behavior is compatible with other people's -assemblers. - - SIZE and VALUE are optional. If the second comma and VALUE are -absent, VALUE is assumed zero. If the first comma and following tokens -are absent, SIZE is assumed to be 1. - -7.48 '.float FLONUMS' -===================== - -This directive assembles zero or more flonums, separated by commas. It -has the same effect as '.single'. - -7.49 '.func NAME[,LABEL]' -========================= - -'.func' emits debugging information to denote function NAME, and is -ignored unless the file is assembled with debugging enabled. Only -'--gstabs[+]' is currently supported. LABEL is the entry point of the -function and if omitted NAME prepended with the 'leading char' is used. -'leading char' is usually '_' or nothing, depending on the target. All -functions are currently defined to have 'void' return type. The -function must be terminated with '.endfunc'. - -7.50 '.global SYMBOL', '.globl SYMBOL' -====================================== - -'.global' makes the symbol visible to 'ld'. If you define SYMBOL in -your partial program, its value is made available to other partial -programs that are linked with it. Otherwise, SYMBOL takes its -attributes from a symbol of the same name from another file linked into -the same program. - - Both spellings ('.globl' and '.global') are accepted, for -compatibility with other assemblers. - -7.51 '.hidden NAMES' -==================== - -This is one of the ELF visibility directives. The other two are -'.internal' (*note '.internal': Internal.) and '.protected' (*note -'.protected': Protected.). - - This directive overrides the named symbols default visibility (which -is set by their binding: local, global or weak). The directive sets the -visibility to 'hidden' which means that the symbols are not visible to -other components. Such symbols are always considered to be 'protected' -as well. - -7.52 '.hword EXPRESSIONS' -========================= - -This expects zero or more EXPRESSIONS, and emits a 16 bit number for -each. - - This directive is a synonym for '.short'. - -7.53 '.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, '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 -'.comment' or '.rdata' section, depending on the target. When using -ELF, comments are emitted to the '.comment' section. - -7.54 '.if ABSOLUTE EXPRESSION' -============================== - -'.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 ABSOLUTE EXPRESSION) is non-zero. The end of the conditional -section of code must be marked by '.endif' (*note '.endif': Endif.); -optionally, you may include code for the alternative condition, flagged -by '.else' (*note '.else': Else.). If you have several conditions to -check, '.elseif' may be used to avoid nesting blocks if/else within each -subsequent '.else' block. - - The following variants of '.if' are also supported: -'.ifdef SYMBOL' - Assembles the following section of code if the specified SYMBOL has - been defined. Note a symbol which has been referenced but not yet - defined is considered to be undefined. - -'.ifb TEXT' - Assembles the following section of code if the operand is blank - (empty). - -'.ifc STRING1,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. - -'.ifeq ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is zero. - -'.ifeqs STRING1,STRING2' - Another form of '.ifc'. The strings must be quoted using double - quotes. - -'.ifge ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is greater - than or equal to zero. - -'.ifgt ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is greater - than zero. - -'.ifle ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is less - than or equal to zero. - -'.iflt ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is less - than zero. - -'.ifnb TEXT' - Like '.ifb', but the sense of the test is reversed: this assembles - the following section of code if the operand is non-blank - (non-empty). - -'.ifnc STRING1,STRING2.' - Like '.ifc', but the sense of the test is reversed: this assembles - the following section of code if the two strings are not the same. - -'.ifndef SYMBOL' -'.ifnotdef SYMBOL' - Assembles the following section of code if the specified 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. - -'.ifne ABSOLUTE EXPRESSION' - Assembles the following section of code if the argument is not - equal to zero (in other words, this is equivalent to '.if'). - -'.ifnes STRING1,STRING2' - Like '.ifeqs', but the sense of the test is reversed: this - assembles the following section of code if the two strings are not - the same. - -7.55 '.incbin "FILE"[,SKIP[,COUNT]]' -==================================== - -The 'incbin' directive includes FILE verbatim at the current location. -You can control the search paths used with the '-I' command-line option -(*note Command-Line Options: Invoking.). Quotation marks are required -around FILE. - - The SKIP argument skips a number of bytes from the start of the FILE. -The 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 'incbin' directive. - -7.56 '.include "FILE"' -====================== - -This directive provides a way to include supporting files at specified -points in your source program. The code from FILE is assembled as if it -followed the point of the '.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 '-I' command-line option (*note -Command-Line Options: Invoking.). Quotation marks are required around -FILE. - -7.57 '.int EXPRESSIONS' -======================= - -Expect zero or more 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. - -7.58 '.internal NAMES' -====================== - -This is one of the ELF visibility directives. The other two are -'.hidden' (*note '.hidden': Hidden.) and '.protected' (*note -'.protected': Protected.). - - This directive overrides the named symbols default visibility (which -is set by their binding: local, global or weak). The directive sets the -visibility to 'internal' which means that the symbols are considered to -be 'hidden' (i.e., not visible to other components), and that some -extra, processor specific processing must also be performed upon the -symbols as well. - -7.59 '.irp SYMBOL,VALUES'... -============================ - -Evaluate a sequence of statements assigning different values to SYMBOL. -The sequence of statements starts at the '.irp' directive, and is -terminated by an '.endr' directive. For each VALUE, SYMBOL is set to -VALUE, and the sequence of statements is assembled. If no VALUE is -listed, the sequence of statements is assembled once, with SYMBOL set to -the null string. To refer to SYMBOL within the sequence of statements, -use \SYMBOL. - - For example, assembling - - .irp param,1,2,3 - move d\param,sp@- - .endr - - is equivalent to assembling - - move d1,sp@- - move d2,sp@- - move d3,sp@- - - For some caveats with the spelling of SYMBOL, see also *note Macro::. - -7.60 '.irpc SYMBOL,VALUES'... -============================= - -Evaluate a sequence of statements assigning different values to SYMBOL. -The sequence of statements starts at the '.irpc' directive, and is -terminated by an '.endr' directive. For each character in VALUE, SYMBOL -is set to the character, and the sequence of statements is assembled. -If no VALUE is listed, the sequence of statements is assembled once, -with SYMBOL set to the null string. To refer to SYMBOL within the -sequence of statements, use \SYMBOL. - - For example, assembling - - .irpc param,123 - move d\param,sp@- - .endr - - is equivalent to assembling - - move d1,sp@- - move d2,sp@- - move d3,sp@- - - For some caveats with the spelling of SYMBOL, see also the discussion -at *Note Macro::. - -7.61 '.lcomm SYMBOL , LENGTH' -============================= - -Reserve LENGTH (an absolute expression) bytes for a local common denoted -by SYMBOL. The section and value of 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. SYMBOL is not declared global -(*note '.global': Global.), so is normally not visible to 'ld'. - -7.62 '.lflags' -============== - -'as' accepts this directive, for compatibility with other assemblers, -but ignores it. - -7.63 '.line LINE-NUMBER' -======================== - -Even though this is a directive associated with the 'a.out' or 'b.out' -object-code formats, 'as' still recognizes it when producing COFF -output, and treats '.line' as though it were the COFF '.ln' _if_ it is -found outside a '.def'/'.endef' pair. - - Inside a '.def', '.line' is, instead, one of the directives used by -compilers to generate auxiliary symbol information for debugging. - -7.64 '.linkonce [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 '.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. - - 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. - - The TYPE argument is optional. If specified, it must be one of the -following strings. For example: - .linkonce same_size - Not all types may be supported on all object file formats. - -'discard' - Silently discard duplicate sections. This is the default. - -'one_only' - Warn if there are duplicate sections, but still keep only one copy. - -'same_size' - Warn if any of the duplicates have different sizes. - -'same_contents' - Warn if any of the duplicates do not have exactly the same - contents. - -7.65 '.ln LINE-NUMBER' -====================== - -'.ln' is a synonym for '.line'. - -7.66 '.mri VAL' -=============== - -If VAL is non-zero, this tells 'as' to enter MRI mode. If VAL is zero, -this tells 'as' to exit MRI mode. This change affects code assembled -until the next '.mri' directive, or until the end of the file. *Note -MRI mode: M. - -7.67 '.list' -============ - -Control (in conjunction with the '.nolist' directive) whether or not -assembly listings are generated. These two directives maintain an -internal counter (which is zero initially). '.list' increments the -counter, and '.nolist' decrements it. Assembly listings are generated -whenever the counter is greater than zero. - - By default, listings are disabled. When you enable them (with the -'-a' command line option; *note Command-Line Options: Invoking.), the -initial value of the listing counter is one. - -7.68 '.long EXPRESSIONS' -======================== - -'.long' is the same as '.int'. *Note '.int': Int. - -7.69 '.macro' -============= - -The commands '.macro' and '.endm' allow you to define macros that -generate assembly output. For example, this definition specifies a -macro 'sum' that puts a sequence of numbers into memory: - - .macro sum from=0, to=5 - .long \from - .if \to-\from - sum "(\from+1)",\to - .endif - .endm - -With that definition, 'SUM 0,5' is equivalent to this assembly input: - - .long 0 - .long 1 - .long 2 - .long 3 - .long 4 - .long 5 - -'.macro MACNAME' -'.macro MACNAME MACARGS ...' - Begin the definition of a macro called 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 ':'req''), or whether it takes all of the - remaining arguments (through ':'vararg''). You can supply a - default value for any macro argument by following the name with - '=DEFLT'. You cannot define two macros with the same MACNAME - unless it has been subject to the '.purgem' directive (*note - Purgem::) between the two definitions. For example, these are all - valid '.macro' statements: - - '.macro comm' - Begin the definition of a macro called 'comm', which takes no - arguments. - - '.macro plus1 p, p1' - '.macro plus1 p p1' - Either statement begins the definition of a macro called - 'plus1', which takes two arguments; within the macro - definition, write '\p' or '\p1' to evaluate the arguments. - - '.macro reserve_str p1=0 p2' - Begin the definition of a macro called '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 'reserve_str A,B' (with '\p1' evaluating - to A and '\p2' evaluating to B), or as 'reserve_str ,B' (with - '\p1' evaluating as the default, in this case '0', and '\p2' - evaluating to B). - - '.macro m p1:req, p2=0, p3:vararg' - Begin the definition of a macro called '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. - - When you call a macro, you can specify the argument values - either by position, or by keyword. For example, 'sum 9,17' is - equivalent to 'sum to=17, from=9'. - - Note that since each of the 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 (':') 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: - - .macro label l - \l: - .endm - - might not work as expected. Invoking 'label foo' might not create - a label called 'foo' but instead just insert the text '\l:' into - the assembler source, probably generating an error about an - unrecognised identifier. - - Similarly problems might occur with the period character ('.') - 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: - - .macro opcode base length - \base.\length - .endm - - and invoking it as 'opcode store l' will not create a 'store.l' - instruction but instead generate some kind of error as the - assembler tries to interpret the text '\base.\length'. - - There are several possible ways around this problem: - - 'Insert white space' - If it is possible to use white space characters then this is - the simplest solution. eg: - - .macro label l - \l : - .endm - - 'Use '\()'' - The string '\()' can be used to separate the end of a macro - argument from the following text. eg: - - .macro opcode base length - \base\().\length - .endm - - 'Use the alternate macro syntax mode' - In the alternative macro syntax mode the ampersand character - ('&') can be used as a separator. eg: - - .altmacro - .macro label l - l&: - .endm - - Note: this problem of correctly identifying string parameters to - pseudo ops also applies to the identifiers used in '.irp' (*note - Irp::) and '.irpc' (*note Irpc::) as well. - -'.endm' - Mark the end of a macro definition. - -'.exitm' - Exit early from the current macro definition. - -'\@' - 'as' maintains a counter of how many macros it has executed in this - pseudo-variable; you can copy that number to your output with '\@', - but _only within a macro definition_. - -'LOCAL NAME [ , ... ]' - _Warning: 'LOCAL' is only available if you select "alternate macro - syntax" with '--alternate' or '.altmacro'._ *Note '.altmacro': - Altmacro. - -7.70 '.altmacro' -================ - -Enable alternate macro mode, enabling: - -'LOCAL NAME [ , ... ]' - One additional directive, 'LOCAL', is available. It is used to - generate a string replacement for each of the NAME arguments, and - replace any instances of NAME in each macro expansion. The - replacement string is unique in the assembly, and different for - each separate macro expansion. 'LOCAL' allows you to write macros - that define symbols, without fear of conflict between separate - macro expansions. - -'String delimiters' - You can write strings delimited in these other ways besides - '"STRING"': - - ''STRING'' - You can delimit strings with single-quote characters. - - '<STRING>' - You can delimit strings with matching angle brackets. - -'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 '!' (an exclamation mark). For example, - you can write '<4.3 !> 5.4!!>' to get the literal text '4.3 > - 5.4!'. - -'Expression results as strings' - You can write '%EXPR' to evaluate the expression EXPR and use the - result as a string. - -7.71 '.noaltmacro' -================== - -Disable alternate macro mode. *Note Altmacro::. - -7.72 '.nolist' -============== - -Control (in conjunction with the '.list' directive) whether or not -assembly listings are generated. These two directives maintain an -internal counter (which is zero initially). '.list' increments the -counter, and '.nolist' decrements it. Assembly listings are generated -whenever the counter is greater than zero. - -7.73 '.octa BIGNUMS' -==================== - -This directive expects zero or more bignums, separated by commas. For -each bignum, it emits a 16-byte integer. - - The term "octa" comes from contexts in which a "word" is two bytes; -hence _octa_-word for 16 bytes. - -7.74 '.org NEW-LC , FILL' -========================= - -Advance the location counter of the current section to NEW-LC. NEW-LC -is either an absolute expression or an expression with the same section -as the current subsection. That is, you can't use '.org' to cross -sections: if NEW-LC has the wrong section, the '.org' directive is -ignored. To be compatible with former assemblers, if the section of -NEW-LC is absolute, 'as' issues a warning, then pretends the section of -NEW-LC is the same as the current subsection. - - '.org' may only increase the location counter, or leave it unchanged; -you cannot use '.org' to move the location counter backwards. - - Because 'as' tries to assemble programs in one pass, NEW-LC may not -be undefined. If you really detest this restriction we eagerly await a -chance to share your improved assembler. - - 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. - - When the location counter (of the current subsection) is advanced, -the intervening bytes are filled with FILL which should be an absolute -expression. If the comma and FILL are omitted, FILL defaults to zero. - -7.75 '.p2align[wl] ABS-EXPR, ABS-EXPR, 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 '.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. - - 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. - - 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. - - The '.p2alignw' and '.p2alignl' directives are variants of the -'.p2align' directive. The '.p2alignw' directive treats the fill pattern -as a two byte word value. The '.p2alignl' directives treats the fill -pattern as a four byte longword value. For example, '.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. - -7.76 '.previous' -================ - -This is one of the ELF section stack manipulation directives. The -others are '.section' (*note Section::), '.subsection' (*note -SubSection::), '.pushsection' (*note PushSection::), and '.popsection' -(*note PopSection::). - - This directive swaps the current section (and subsection) with most -recently referenced section (and subsection) prior to this one. -Multiple '.previous' directives in a row will flip between two sections -(and their subsections). - - In terms of the section stack, this directive swaps the current -section with the top section on the section stack. - -7.77 '.popsection' -================== - -This is one of the ELF section stack manipulation directives. The -others are '.section' (*note Section::), '.subsection' (*note -SubSection::), '.pushsection' (*note PushSection::), and '.previous' -(*note Previous::). - - 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. - -7.78 '.print STRING' -==================== - -'as' will print STRING on the standard output during assembly. You must -put STRING in double quotes. - -7.79 '.protected NAMES' -======================= - -This is one of the ELF visibility directives. The other two are -'.hidden' (*note Hidden::) and '.internal' (*note Internal::). - - This directive overrides the named symbols default visibility (which -is set by their binding: local, global or weak). The directive sets the -visibility to '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. - -7.80 '.psize LINES , COLUMNS' -============================= - -Use this directive to declare the number of lines--and, optionally, the -number of columns--to use for each page, when generating listings. - - If you do not use '.psize', listings use a default line-count of 60. -You may omit the comma and COLUMNS specification; the default width is -200 columns. - - 'as' generates formfeeds whenever the specified number of lines is -exceeded (or whenever you explicitly request one, using '.eject'). - - If you specify LINES as '0', no formfeeds are generated save those -explicitly specified with '.eject'. - -7.81 '.purgem NAME' -=================== - -Undefine the macro NAME, so that later uses of the string will not be -expanded. *Note Macro::. - -7.82 '.pushsection NAME , SUBSECTION' -===================================== - -This is one of the ELF section stack manipulation directives. The -others are '.section' (*note Section::), '.subsection' (*note -SubSection::), '.popsection' (*note PopSection::), and '.previous' -(*note Previous::). - - This directive pushes the current section (and subsection) onto the -top of the section stack, and then replaces the current section and -subsection with 'name' and 'subsection'. - -7.83 '.quad BIGNUMS' -==================== - -'.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. - - The term "quad" comes from contexts in which a "word" is two bytes; -hence _quad_-word for 8 bytes. - -7.84 '.reloc OFFSET, RELOC_NAME[, EXPRESSION]' -============================================== - -Generate a relocation at OFFSET of type RELOC_NAME with value -EXPRESSION. If OFFSET is a number, the relocation is generated in the -current section. If OFFSET is an expression that resolves to a symbol -plus offset, the relocation is generated in the given symbol's section. -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. - -7.85 '.rept COUNT' -================== - -Repeat the sequence of lines between the '.rept' directive and the next -'.endr' directive COUNT times. - - For example, assembling - - .rept 3 - .long 0 - .endr - - is equivalent to assembling - - .long 0 - .long 0 - .long 0 - -7.86 '.sbttl "SUBHEADING"' -========================== - -Use SUBHEADING as the title (third line, immediately after the title -line) when generating assembly listings. - - This directive affects subsequent pages, as well as the current page -if it appears within ten lines of the top of a page. - -7.87 '.section NAME' -==================== - -Use the '.section' directive to assemble the following code into a -section named NAME. - - This directive is only supported for targets that actually support -arbitrarily named sections; on 'a.out' targets, for example, it is not -accepted, even with a standard 'a.out' section name. - - This is one of the ELF section stack manipulation directives. The -others are '.subsection' (*note SubSection::), '.pushsection' (*note -PushSection::), '.popsection' (*note PopSection::), and '.previous' -(*note Previous::). - - For ELF targets, the '.section' directive is used like this: - - .section NAME [, "FLAGS"[, @TYPE[,FLAG_SPECIFIC_ARGUMENTS]]] - - The optional FLAGS argument is a quoted string which may contain any -combination of the following characters: -'a' - section is allocatable -'w' - section is writable -'x' - section is executable -'M' - section is mergeable -'S' - section contains zero terminated strings -'G' - section is a member of a section group -'T' - section is used for thread-local-storage - - The optional TYPE argument may contain one of the following -constants: -'@progbits' - section contains data -'@nobits' - section does not contain data (i.e., section only occupies space) -'@note' - section contains data which is used by things other than the - program -'@init_array' - section contains an array of pointers to init functions -'@fini_array' - section contains an array of pointers to finish functions -'@preinit_array' - section contains an array of pointers to pre-init functions - - Many targets only support the first three section types. - - Note on targets where the '@' character is the start of a comment (eg -ARM) then another character is used instead. For example the ARM port -uses the '%' character. - - If FLAGS contains the 'M' symbol then the TYPE argument must be -specified as well as an extra argument--ENTSIZE--like this: - - .section NAME , "FLAGS"M, @TYPE, ENTSIZE - - Sections with the 'M' flag but not 'S' flag must contain fixed size -constants, each ENTSIZE octets long. Sections with both 'M' and 'S' -must contain zero terminated strings where each character is ENTSIZE -bytes long. The linker may remove duplicates within sections with the -same name, same entity size and same flags. ENTSIZE must be an absolute -expression. - - If FLAGS contains the 'G' symbol then the TYPE argument must be -present along with an additional field like this: - - .section NAME , "FLAGS"G, @TYPE, GROUPNAME[, LINKAGE] - - The GROUPNAME field specifies the name of the section group to which -this particular section belongs. The optional linkage field can -contain: -'comdat' - indicates that only one copy of this section should be retained -'.gnu.linkonce' - an alias for comdat - - Note: if both the M and G flags are present then the fields for the -Merge flag should come first, like this: - - .section NAME , "FLAGS"MG, @TYPE, ENTSIZE, GROUPNAME[, LINKAGE] - - 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. - - For ELF targets, the assembler supports another type of '.section' -directive for compatibility with the Solaris assembler: - - .section "NAME"[, FLAGS...] - - Note that the section name is quoted. There may be a sequence of -comma separated flags: -'#alloc' - section is allocatable -'#write' - section is writable -'#execinstr' - section is executable -'#tls' - section is used for thread local storage - - This directive replaces the current section and subsection. See the -contents of the gas testsuite directory 'gas/testsuite/gas/elf' for some -examples of how this directive and the other section stack directives -work. - -7.88 '.set SYMBOL, EXPRESSION' -============================== - -Set the value of SYMBOL to EXPRESSION. This changes SYMBOL's value and -type to conform to EXPRESSION. If SYMBOL was flagged as external, it -remains flagged (*note Symbol Attributes::). - - You may '.set' a symbol many times in the same assembly. - - If you '.set' a global symbol, the value stored in the object file is -the last value stored into it. - -7.89 '.short EXPRESSIONS' -========================= - -This expects zero or more EXPRESSIONS, and emits a 16 bit number for -each. - -7.90 '.single FLONUMS' -====================== - -This directive assembles zero or more flonums, separated by commas. It -has the same effect as '.float'. - -7.91 '.size' -============ - -This directive is used to set the size associated with a symbol. - - For ELF targets, the '.size' directive is used like this: - - .size NAME , EXPRESSION - - This directive sets the size associated with a symbol NAME. The size -in bytes is computed from EXPRESSION which can make use of label -arithmetic. This directive is typically used to set the size of -function symbols. - -7.92 '.sleb128 EXPRESSIONS' -=========================== - -SLEB128 stands for "signed little endian base 128." This is a compact, -variable length representation of numbers used by the DWARF symbolic -debugging format. *Note '.uleb128': Uleb128. - -7.93 '.skip SIZE , FILL' -======================== - -This directive emits SIZE bytes, each of value FILL. Both SIZE and FILL -are absolute expressions. If the comma and FILL are omitted, FILL is -assumed to be zero. This is the same as '.space'. - -7.94 '.space SIZE , FILL' -========================= - -This directive emits SIZE bytes, each of value FILL. Both SIZE and FILL -are absolute expressions. If the comma and FILL are omitted, FILL is -assumed to be zero. This is the same as '.skip'. - -7.95 '.stabd, .stabn, .stabs' -============================= - -There are three directives that begin '.stab'. All emit symbols (*note -Symbols::), for use by symbolic debuggers. The symbols are not entered -in the 'as' hash table: they cannot be referenced elsewhere in the -source file. Up to five fields are required: - -STRING - This is the symbol's name. It may contain any character except - '\000', so is more general than ordinary symbol names. Some - debuggers used to code arbitrarily complex structures into symbol - names using this field. - -TYPE - An absolute expression. The symbol's type is set to the low 8 bits - of this expression. Any bit pattern is permitted, but 'ld' and - debuggers choke on silly bit patterns. - -OTHER - An absolute expression. The symbol's "other" attribute is set to - the low 8 bits of this expression. - -DESC - An absolute expression. The symbol's descriptor is set to the low - 16 bits of this expression. - -VALUE - An absolute expression which becomes the symbol's value. - - If a warning is detected while reading a '.stabd', '.stabn', or -'.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! - -'.stabd TYPE , OTHER , DESC' - - The "name" 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. - - 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 '.stabd' was assembled. - -'.stabn TYPE , OTHER , DESC , VALUE' - The name of the symbol is set to the empty string '""'. - -'.stabs STRING , TYPE , OTHER , DESC , VALUE' - All five fields are specified. - -7.96 '.string' "STR" -==================== - -Copy the characters in 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 *note Strings: Strings. - -7.97 '.struct EXPRESSION' -========================= - -Switch to the absolute section, and set the section offset to -EXPRESSION, which must be an absolute expression. You might use this as -follows: - .struct 0 - field1: - .struct field1 + 4 - field2: - .struct field2 + 4 - field3: - This would define the symbol 'field1' to have the value 0, the symbol -'field2' to have the value 4, and the symbol 'field3' to have the value -8. Assembly would be left in the absolute section, and you would need -to use a '.section' directive of some sort to change to some other -section before further assembly. - -7.98 '.subsection NAME' -======================= - -This is one of the ELF section stack manipulation directives. The -others are '.section' (*note Section::), '.pushsection' (*note -PushSection::), '.popsection' (*note PopSection::), and '.previous' -(*note Previous::). - - This directive replaces the current subsection with '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. - -7.99 '.symver' -============== - -Use the '.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. - - For ELF targets, the '.symver' directive can be used like this: - .symver NAME, NAME2@NODENAME - If the symbol NAME is defined within the file being assembled, the -'.symver' directive effectively creates a symbol alias with the name -NAME2@NODENAME, and in fact the main reason that we just don't try and -create a regular alias is that the @ character isn't permitted in symbol -names. The NAME2 part of the name is the actual name of the symbol by -which it will be externally referenced. The name 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 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 NODENAME should -correspond to the nodename of the symbol you are trying to override. - - If the symbol NAME is not defined within the file being assembled, -all references to NAME will be changed to NAME2@NODENAME. If no -reference to NAME is made, NAME2@NODENAME will be removed from the -symbol table. - - Another usage of the '.symver' directive is: - .symver NAME, NAME2@@NODENAME - In this case, the symbol NAME must exist and be defined within the -file being assembled. It is similar to NAME2@NODENAME. The difference -is NAME2@@NODENAME will also be used to resolve references to NAME2 by -the linker. - - The third usage of the '.symver' directive is: - .symver NAME, NAME2@@@NODENAME - When NAME is not defined within the file being assembled, it is -treated as NAME2@NODENAME. When NAME is defined within the file being -assembled, the symbol name, NAME, will be changed to NAME2@@NODENAME. - -7.100 '.text SUBSECTION' -======================== - -Tells 'as' to assemble the following statements onto the end of the text -subsection numbered SUBSECTION, which is an absolute expression. If -SUBSECTION is omitted, subsection number zero is used. - -7.101 '.title "HEADING"' -======================== - -Use HEADING as the title (second line, immediately after the source file -name and pagenumber) when generating assembly listings. - - This directive affects subsequent pages, as well as the current page -if it appears within ten lines of the top of a page. - -7.102 '.type' -============= - -This directive is used to set the type of a symbol. - - For ELF targets, the '.type' directive is used like this: - - .type NAME , TYPE DESCRIPTION - - This sets the type of symbol NAME to be either a function symbol or -an object symbol. There are five different syntaxes supported for the -TYPE DESCRIPTION field, in order to provide compatibility with various -other assemblers. - - Because some of the characters used in these syntaxes (such as '@' -and '#') 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. - - The syntaxes supported are: - - .type <name> STT_FUNCTION - .type <name> STT_OBJECT - - .type <name>,#function - .type <name>,#object - - .type <name>,@function - .type <name>,@object - - .type <name>,%function - .type <name>,%object - - .type <name>,"function" - .type <name>,"object" - -7.103 '.uleb128 EXPRESSIONS' -============================ - -ULEB128 stands for "unsigned little endian base 128." This is a -compact, variable length representation of numbers used by the DWARF -symbolic debugging format. *Note '.sleb128': Sleb128. - -7.104 '.version "STRING"' -========================= - -This directive creates a '.note' section and places into it an ELF -formatted note of type NT_VERSION. The note's name is set to 'string'. - -7.105 '.vtable_entry TABLE, OFFSET' -=================================== - -This directive finds or creates a symbol 'table' and creates a -'VTABLE_ENTRY' relocation for it with an addend of 'offset'. - -7.106 '.vtable_inherit CHILD, PARENT' -===================================== - -This directive finds the symbol 'child' and finds or creates the symbol -'parent' and then creates a 'VTABLE_INHERIT' relocation for the parent -whose addend is the value of the child symbol. As a special case the -parent name of '0' is treated as referring to the '*ABS*' section. - -7.107 '.warning "STRING"' -========================= - -Similar to the directive '.error' (*note '.error "STRING"': Error.), but -just emits a warning. - -7.108 '.weak NAMES' -=================== - -This directive sets the weak attribute on the comma separated list of -symbol 'names'. If the symbols do not already exist, they will be -created. - - 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 'names'. If the symbols do not already exist, they will be -created. - - 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. - -7.109 '.weakref ALIAS, 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. - - 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. - - The alias itself never makes to the symbol table, and is entirely -handled within the assembler. - -7.110 '.word EXPRESSIONS' -========================= - -This directive expects zero or more EXPRESSIONS, of any section, -separated by commas. For each expression, 'as' emits a 32-bit number. - -7.111 Deprecated Directives -=========================== - -One day these directives won't work. They are included for -compatibility with older assemblers. -.abort -.line - -8 ARM Dependent Features -************************ - -8.1 Options -=========== - -'-mcpu=PROCESSOR[+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: 'arm1', 'arm2', 'arm250', - 'arm3', 'arm6', 'arm60', 'arm600', 'arm610', 'arm620', 'arm7', - 'arm7m', 'arm7d', 'arm7dm', 'arm7di', 'arm7dmi', 'arm70', 'arm700', - 'arm700i', 'arm710', 'arm710t', 'arm720', 'arm720t', 'arm740t', - 'arm710c', 'arm7100', 'arm7500', 'arm7500fe', 'arm7t', 'arm7tdmi', - 'arm7tdmi-s', 'arm8', 'arm810', 'strongarm', 'strongarm1', - 'strongarm110', 'strongarm1100', 'strongarm1110', 'arm9', 'arm920', - 'arm920t', 'arm922t', 'arm940t', 'arm9tdmi', 'arm9e', 'arm926e', - 'arm926ej-s', 'arm946e-r0', 'arm946e', 'arm946e-s', 'arm966e-r0', - 'arm966e', 'arm966e-s', 'arm968e-s', 'arm10t', 'arm10tdmi', - 'arm10e', 'arm1020', 'arm1020t', 'arm1020e', 'arm1022e', - 'arm1026ej-s', 'arm1136j-s', 'arm1136jf-s', 'arm1156t2-s', - 'arm1156t2f-s', 'arm1176jz-s', 'arm1176jzf-s', 'mpcore', - 'mpcorenovfp', 'cortex-a8', 'cortex-r4', 'cortex-m3', 'ep9312' - (ARM920 with Cirrus Maverick coprocessor), 'i80200' (Intel XScale - processor) 'iwmmxt' (Intel(r) XScale processor with Wireless - MMX(tm) technology coprocessor) and 'xscale'. The special name - 'all' may be used to allow the assembler to accept instructions - valid for any ARM processor. - - 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, - '-mcpu=arm920+maverick' is equivalent to specifying '-mcpu=ep9312'. - The following extensions are currently supported: '+maverick' - '+iwmmxt' and '+xscale'. - -'-march=ARCHITECTURE[+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: 'armv1', 'armv2', - 'armv2a', 'armv2s', 'armv3', 'armv3m', 'armv4', 'armv4xm', - 'armv4t', 'armv4txm', 'armv5', 'armv5t', 'armv5txm', 'armv5te', - 'armv5texp', 'armv6', 'armv6j', 'armv6k', 'armv6z', 'armv6zk', - 'armv7', 'armv7-a', 'armv7-r', 'armv7-m', 'iwmmxt' and 'xscale'. - If both '-mcpu' and '-march' are specified, the assembler will use - the setting for '-mcpu'. - - The architecture option can be extended with the same instruction - set extension options as the '-mcpu' option. - -'-mfpu=FLOATING-POINT-FORMAT' - - 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: - 'softfpa', 'fpe', 'fpe2', 'fpe3', 'fpa', 'fpa10', 'fpa11', - 'arm7500fe', 'softvfp', 'softvfp+vfp', 'vfp', 'vfp10', 'vfp10-r0', - 'vfp9', 'vfpxd', 'arm1020t', 'arm1020e', 'arm1136jf-s' and - 'maverick'. - - In addition to determining which instructions are assembled, this - option also affects the way in which the '.double' assembler - directive behaves when assembling little-endian code. - - 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. - -'-mthumb' - This option specifies that the assembler should start assembling - Thumb instructions; that is, it should behave as though the file - starts with a '.code 16' directive. - -'-mthumb-interwork' - This option specifies that the output generated by the assembler - should be marked as supporting interworking. - -'-mapcs [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. - -'-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. - -'-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. - -'-mapcs-reentrant' - This indicates that the reentrant variant of the APCS should be - used. This variant supports position independent code. - -'-mfloat-abi=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: 'soft', 'softfp' and 'hard'. - -'-meabi=VER' - This option specifies which EABI version the produced object files - should conform to. The following values are recognized: 'gnu', '4' - and '5'. - -'-EB' - This option specifies that the output generated by the assembler - should be marked as being encoded for a big-endian processor. - -'-EL' - This option specifies that the output generated by the assembler - should be marked as being encoded for a little-endian processor. - -'-k' - This option specifies that the output of the assembler should be - marked as position-independent code (PIC). - -8.2 Syntax -========== - -8.2.1 Special Characters ------------------------- - -The presence of a '@' on a line indicates the start of a comment that -extends to the end of the current line. If a '#' appears as the first -character of a line, the whole line is treated as a comment. - - The ';' character can be used instead of a newline to separate -statements. - - Either '#' or '$' can be used to indicate immediate operands. - - *TODO* Explain about /data modifier on symbols. - -8.2.2 Register Names --------------------- - -*TODO* Explain about ARM register naming, and the predefined names. - -8.2.3 ARM relocation generation -------------------------------- - -Specific data relocations can be generated by putting the relocation -name in parentheses after the symbol name. For example: - - .word foo(TARGET1) - - This will generate an 'R_ARM_TARGET1' relocation against the symbol -FOO. The following relocations are supported: 'GOT', 'GOTOFF', -'TARGET1', 'TARGET2', 'SBREL', 'TLSGD', 'TLSLDM', 'TLSLDO', 'GOTTPOFF' -and 'TPOFF'. - - For compatibility with older toolchains the assembler also accepts -'(PLT)' after branch targets. This will generate the deprecated -'R_ARM_PLT32' relocation. - - Relocations for 'MOVW' and 'MOVT' instructions can be generated by -prefixing the value with '#:lower16:' and '#:upper16' respectively. For -example to load the 32-bit address of foo into r0: - - MOVW r0, #:lower16:foo - MOVT r0, #:upper16:foo - -8.3 Floating Point -================== - -The ARM family uses IEEE floating-point numbers. - -8.4 ARM Machine Directives -========================== - -'.align EXPRESSION [, EXPRESSION]' - This is the generic .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. - -'NAME .req REGISTER NAME' - This creates an alias for REGISTER NAME called NAME. For example: - - foo .req r0 - -'.unreq ALIAS-NAME' - This undefines a register alias which was previously defined using - the 'req', 'dn' or 'qn' directives. For example: - - foo .req r0 - .unreq foo - - 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. - -'NAME .dn REGISTER NAME [.TYPE] [[INDEX]]' -'NAME .qn REGISTER NAME [.TYPE] [[INDEX]]' - - The 'dn' and '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. - - 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: - - x .dn d2.f32 - y .dn d3.f32 - z .dn d4.f32[1] - vmul x,y,z - - This is equivalent to writing the following: - - vmul.f32 d2,d3,d4[1] - - Aliases created using 'dn' or 'qn' can be destroyed using 'unreq'. - -'.code [16|32]' - This directive selects the instruction set being generated. The - value 16 selects Thumb, with the value 32 selecting ARM. - -'.thumb' - This performs the same action as .CODE 16. - -'.arm' - This performs the same action as .CODE 32. - -'.force_thumb' - This directive forces the selection of Thumb instructions, even if - the target processor does not support those instructions - -'.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 '.thumb' - - This directive is not neccessary when generating EABI objects. On - these targets the encoding is implicit when generating Thumb code. - -'.thumb_set' - This performs the equivalent of a '.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 '.thumb_func' directive does. - -'.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). 'GAS' maintains a separate literal pool for each - section and each sub-section. The '.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. - - Note - older versions of '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. - -'.pool' - This is a synonym for .ltorg. - -'.unwind_fnstart' - Marks the start of a function with an unwind table entry. - -'.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. - - 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. - -'.cantunwind' - Prevents unwinding through the current function. No personality - routine or exception table data is required or permitted. - -'.personality NAME' - Sets the personality routine for the current function to NAME. - -'.personalityindex INDEX' - Sets the personality routine for the current function to the EABI - standard routine number INDEX - -'.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 '.fnend' directive will be added to the exception - table entry. - - Must be preceded by a '.personality' or '.personalityindex' - directive. - -'.save REGLIST' - Generate unwinder annotations to restore the registers in REGLIST. - The format of REGLIST is the same as the corresponding - store-multiple instruction. - - _core registers_ - .save {r4, r5, r6, lr} - stmfd sp!, {r4, r5, r6, lr} - _FPA registers_ - .save f4, 2 - sfmfd f4, 2, [sp]! - _VFP registers_ - .save {d8, d9, d10} - fstmdx sp!, {d8, d9, d10} - _iWMMXt registers_ - .save {wr10, wr11} - wstrd wr11, [sp, #-8]! - wstrd wr10, [sp, #-8]! - or - .save wr11 - wstrd wr11, [sp, #-8]! - .save wr10 - wstrd wr10, [sp, #-8]! - -'.vsave VFP-REGLIST' - Generate unwinder annotations to restore the VFP registers in - VFP-REGLIST using FLDMD. Also works for VFPv3 registers that are to - be restored using VLDM. The format of VFP-REGLIST is the same as - the corresponding store-multiple instruction. - - _VFP registers_ - .vsave {d8, d9, d10} - fstmdd sp!, {d8, d9, d10} - _VFPv3 registers_ - .vsave {d15, d16, d17} - vstm sp!, {d15, d16, d17} - - Since FLDMX and FSTMX are now deprecated, this directive should be - used in favour of '.save' for saving VFP registers for ARMv6 and - above. - -'.pad #COUNT' - Generate unwinder annotations for a stack adjustment of COUNT - bytes. A positive value indicates the function prologue allocated - stack space by decrementing the stack pointer. - -'.movsp REG [, #OFFSET]' - Tell the unwinder that REG contains an offset from the current - stack pointer. If OFFSET is not specified then it is assumed to be - zero. - -'.setfp FPREG, SPREG [, #OFFSET]' - Make all unwinder annotations relaive to a frame pointer. Without - this the unwinder will use offsets from the stack pointer. - - The syntax of this directive is the same as the 'sub' or 'mov' - instruction used to set the frame pointer. SPREG must be either - 'sp' or mentioned in a previous '.movsp' directive. - - .movsp ip - mov ip, sp - ... - .setfp fp, ip, #4 - sub fp, ip, #4 - -'.raw OFFSET, BYTE1, ...' - Insert one of more arbitary unwind opcode bytes, which are known to - adjust the stack pointer by OFFSET bytes. - - For example '.unwind_raw 4, 0xb1, 0x01' is equivalent to '.save - {r0}' - -'.cpu NAME' - Select the target processor. Valid values for NAME are the same as - for the '-mcpu' commandline option. - -'.arch NAME' - Select the target architecture. Valid values for NAME are the same - as for the '-march' commandline option. - -'.object_arch NAME' - Override the architecture recorded in the EABI object attribute - section. Valid values for NAME are the same as for the '.arch' - directive. Typically this is useful when code uses runtime - detection of CPU features. - -'.fpu NAME' - Select the floating point unit to assemble for. Valid values for - NAME are the same as for the '-mfpu' commandline option. - -'.eabi_attribute TAG, VALUE' - Set the EABI object attribute number TAG to VALUE. The value is - either a 'number', '"string"', or 'number, "string"' depending on - the tag. - -8.5 Opcodes -=========== - -'as' implements all the standard ARM opcodes. It also implements -several pseudo opcodes, including several synthetic load instructions. - -'NOP' - nop - - This pseudo op will always evaluate to a legal ARM instruction that - does nothing. Currently it will evaluate to MOV r0, r0. - -'LDR' - ldr <register> , = <expression> - - 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. - -'ADR' - adr <register> <label> - - This instruction will load the address of LABEL into the indicated - register. The instruction will evaluate to a PC relative ADD or - SUB instruction depending upon where the label is located. If the - label is out of range, or if it is not defined in the same file - (and section) as the ADR instruction, then an error will be - generated. This instruction will not make use of the literal pool. - -'ADRL' - adrl <register> <label> - - This instruction will load the address of LABEL into the indicated - register. The instruction will evaluate to one or two PC relative - ADD or SUB instructions depending upon where the label is located. - If a second instruction is not needed a NOP instruction will be - generated in its place, so that this instruction is always 8 bytes - long. - - If the label is out of range, or if it is not defined in the same - file (and section) as the ADRL instruction, then an error will be - generated. This instruction will not make use of the literal pool. - - For information on the ARM or Thumb instruction sets, see 'ARM -Software Development Toolkit Reference Manual', Advanced RISC Machines -Ltd. - -8.6 Mapping Symbols -=================== - -The ARM ELF specification requires that special symbols be inserted into -object files to mark certain features: - -'$a' - At the start of a region of code containing ARM instructions. - -'$t' - At the start of a region of code containing THUMB instructions. - -'$d' - At the start of a region of data. - - The assembler will automatically insert these symbols for you - there -is no need to code them yourself. Support for tagging symbols ($b, $f, -$p and $m) which is also mentioned in the current ARM ELF specification -is not implemented. This is because they have been dropped from the new -EABI and so tools cannot rely upon their presence. - -9 80386 Dependent Features -************************** - -The i386 version 'as' supports both the original Intel 386 architecture -in both 16 and 32-bit mode as well as AMD x86-64 architecture extending -the Intel architecture to 64-bits. - -9.1 Options -=========== - -The i386 version of 'as' has a few machine dependent options: - -'--32 | --64' - Select the word size, either 32 bits or 64 bits. Selecting 32-bit - implies Intel i386 architecture, while 64-bit implies AMD x86-64 - architecture. - - These options are only available with the ELF object file format, - and require that the necessary BFD support has been included (on a - 32-bit platform you have to add -enable-64-bit-bfd to configure - enable 64-bit usage and use x86-64 as target platform). - -'-n' - By default, x86 GAS replaces multiple nop instructions used for - alignment within code sections with multi-byte nop instructions - such as leal 0(%esi,1),%esi. This switch disables the - optimization. - -'--divide' - On SVR4-derived platforms, the character '/' is treated as a - comment character, which means that it cannot be used in - expressions. The '--divide' option turns '/' into a normal - character. This does not disable '/' at the beginning of a line - starting a comment, or affect using '#' for starting a comment. - -'-march=CPU' - This option specifies an instruction set architecture for - generating instructions. The following architectures are - recognized: 'i8086', 'i186', 'i286', 'i386', 'i486', 'i586', - 'i686', 'pentium', 'pentiumpro', 'pentiumii', 'pentiumiii', - 'pentium4', 'prescott', 'nocona', 'core', 'core2', 'k6', 'k6_2', - 'athlon', 'sledgehammer', 'opteron', 'k8', 'generic32' and - 'generic64'. - - This option only affects instructions generated by the assembler. - The '.arch' directive will take precedent. - -'-mtune=CPU' - This option specifies a processor to optimize for. When used in - conjunction with the '-march' option, only instructions of the - processor specified by the '-march' option will be generated. - - Valid CPU values are identical to '-march=CPU'. - -9.2 AT&T Syntax versus Intel Syntax -=================================== - -'as' now supports assembly using Intel assembler syntax. -'.intel_syntax' selects Intel mode, and '.att_syntax' switches back to -the usual AT&T mode for compatibility with the output of 'gcc'. Either -of these directives may have an optional argument, 'prefix', or -'noprefix' specifying whether registers require a '%' prefix. AT&T -System V/386 assembler syntax is quite different from Intel syntax. We -mention these differences because almost all 80386 documents use Intel -syntax. Notable differences between the two syntaxes are: - - * AT&T immediate operands are preceded by '$'; Intel immediate - operands are undelimited (Intel 'push 4' is AT&T 'pushl $4'). AT&T - register operands are preceded by '%'; Intel register operands are - undelimited. AT&T absolute (as opposed to PC relative) jump/call - operands are prefixed by '*'; they are undelimited in Intel syntax. - - * AT&T and Intel syntax use the opposite order for source and - destination operands. Intel 'add eax, 4' is 'addl $4, %eax'. The - 'source, dest' convention is maintained for compatibility with - previous Unix assemblers. Note that instructions with more than - one source operand, such as the 'enter' instruction, do _not_ have - reversed order. *note i386-Bugs::. - - * In AT&T syntax the size of memory operands is determined from the - last character of the instruction mnemonic. Mnemonic suffixes of - 'b', 'w', 'l' and 'q' specify byte (8-bit), word (16-bit), long - (32-bit) and quadruple word (64-bit) memory references. Intel - syntax accomplishes this by prefixing memory operands (_not_ the - instruction mnemonics) with 'byte ptr', 'word ptr', 'dword ptr' and - 'qword ptr'. Thus, Intel 'mov al, byte ptr FOO' is 'movb FOO, %al' - in AT&T syntax. - - * Immediate form long jumps and calls are 'lcall/ljmp $SECTION, - $OFFSET' in AT&T syntax; the Intel syntax is 'call/jmp far - SECTION:OFFSET'. Also, the far return instruction is 'lret - $STACK-ADJUST' in AT&T syntax; Intel syntax is 'ret far - STACK-ADJUST'. - - * The AT&T assembler does not provide support for multiple section - programs. Unix style systems expect all programs to be single - sections. - -9.3 Instruction Naming -====================== - -Instruction mnemonics are suffixed with one character modifiers which -specify the size of operands. The letters 'b', 'w', 'l' and 'q' specify -byte, word, long and quadruple word operands. If no suffix is specified -by an instruction then 'as' tries to fill in the missing suffix based on -the destination register operand (the last one by convention). Thus, -'mov %ax, %bx' is equivalent to 'movw %ax, %bx'; also, 'mov $1, %bx' is -equivalent to 'movw $1, bx'. Note that this is incompatible with the -AT&T Unix assembler which assumes that a missing mnemonic suffix implies -long operand size. (This incompatibility does not affect compiler -output since compilers always explicitly specify the mnemonic suffix.) - - Almost all instructions have the same names in AT&T and Intel format. -There are a few exceptions. The sign extend and zero extend -instructions need two sizes to specify them. They need a size to -sign/zero extend _from_ and a size to zero extend _to_. This is -accomplished by using two instruction mnemonic suffixes in AT&T syntax. -Base names for sign extend and zero extend are 'movs...' and 'movz...' -in AT&T syntax ('movsx' and 'movzx' in Intel syntax). The instruction -mnemonic suffixes are tacked on to this base name, the _from_ suffix -before the _to_ suffix. Thus, 'movsbl %al, %edx' is AT&T syntax for -"move sign extend _from_ %al _to_ %edx." Possible suffixes, thus, are -'bl' (from byte to long), 'bw' (from byte to word), 'wl' (from word to -long), 'bq' (from byte to quadruple word), 'wq' (from word to quadruple -word), and 'lq' (from long to quadruple word). - - The Intel-syntax conversion instructions - - * 'cbw' -- sign-extend byte in '%al' to word in '%ax', - - * 'cwde' -- sign-extend word in '%ax' to long in '%eax', - - * 'cwd' -- sign-extend word in '%ax' to long in '%dx:%ax', - - * 'cdq' -- sign-extend dword in '%eax' to quad in '%edx:%eax', - - * 'cdqe' -- sign-extend dword in '%eax' to quad in '%rax' (x86-64 - only), - - * 'cqo' -- sign-extend quad in '%rax' to octuple in '%rdx:%rax' - (x86-64 only), - -are called 'cbtw', 'cwtl', 'cwtd', 'cltd', 'cltq', and 'cqto' in AT&T -naming. 'as' accepts either naming for these instructions. - - Far call/jump instructions are 'lcall' and 'ljmp' in AT&T syntax, but -are 'call far' and 'jump far' in Intel convention. - -9.4 Register Naming -=================== - -Register operands are always prefixed with '%'. The 80386 registers -consist of - - * the 8 32-bit registers '%eax' (the accumulator), '%ebx', '%ecx', - '%edx', '%edi', '%esi', '%ebp' (the frame pointer), and '%esp' (the - stack pointer). - - * the 8 16-bit low-ends of these: '%ax', '%bx', '%cx', '%dx', '%di', - '%si', '%bp', and '%sp'. - - * the 8 8-bit registers: '%ah', '%al', '%bh', '%bl', '%ch', '%cl', - '%dh', and '%dl' (These are the high-bytes and low-bytes of '%ax', - '%bx', '%cx', and '%dx') - - * the 6 section registers '%cs' (code section), '%ds' (data section), - '%ss' (stack section), '%es', '%fs', and '%gs'. - - * the 3 processor control registers '%cr0', '%cr2', and '%cr3'. - - * the 6 debug registers '%db0', '%db1', '%db2', '%db3', '%db6', and - '%db7'. - - * the 2 test registers '%tr6' and '%tr7'. - - * the 8 floating point register stack '%st' or equivalently '%st(0)', - '%st(1)', '%st(2)', '%st(3)', '%st(4)', '%st(5)', '%st(6)', and - '%st(7)'. These registers are overloaded by 8 MMX registers - '%mm0', '%mm1', '%mm2', '%mm3', '%mm4', '%mm5', '%mm6' and '%mm7'. - - * the 8 SSE registers registers '%xmm0', '%xmm1', '%xmm2', '%xmm3', - '%xmm4', '%xmm5', '%xmm6' and '%xmm7'. - - The AMD x86-64 architecture extends the register set by: - - * enhancing the 8 32-bit registers to 64-bit: '%rax' (the - accumulator), '%rbx', '%rcx', '%rdx', '%rdi', '%rsi', '%rbp' (the - frame pointer), '%rsp' (the stack pointer) - - * the 8 extended registers '%r8'-'%r15'. - - * the 8 32-bit low ends of the extended registers: '%r8d'-'%r15d' - - * the 8 16-bit low ends of the extended registers: '%r8w'-'%r15w' - - * the 8 8-bit low ends of the extended registers: '%r8b'-'%r15b' - - * the 4 8-bit registers: '%sil', '%dil', '%bpl', '%spl'. - - * the 8 debug registers: '%db8'-'%db15'. - - * the 8 SSE registers: '%xmm8'-'%xmm15'. - -9.5 Instruction Prefixes -======================== - -Instruction prefixes are used to modify the following instruction. They -are used to repeat string instructions, to provide section overrides, to -perform bus lock operations, and to change operand and address sizes. -(Most instructions that normally operate on 32-bit operands will use -16-bit operands if the instruction has an "operand size" prefix.) -Instruction prefixes are best written on the same line as the -instruction they act upon. For example, the 'scas' (scan string) -instruction is repeated with: - - repne scas %es:(%edi),%al - - You may also place prefixes on the lines immediately preceding the -instruction, but this circumvents checks that 'as' does with prefixes, -and will not work with all prefixes. - - Here is a list of instruction prefixes: - - * Section override prefixes 'cs', 'ds', 'ss', 'es', 'fs', 'gs'. - These are automatically added by specifying using the - SECTION:MEMORY-OPERAND form for memory references. - - * Operand/Address size prefixes 'data16' and 'addr16' change 32-bit - operands/addresses into 16-bit operands/addresses, while 'data32' - and 'addr32' change 16-bit ones (in a '.code16' section) into - 32-bit operands/addresses. These prefixes _must_ appear on the - same line of code as the instruction they modify. For example, in - a 16-bit '.code16' section, you might write: - - addr32 jmpl *(%ebx) - - * The bus lock prefix 'lock' inhibits interrupts during execution of - the instruction it precedes. (This is only valid with certain - instructions; see a 80386 manual for details). - - * The wait for coprocessor prefix 'wait' waits for the coprocessor to - complete the current instruction. This should never be needed for - the 80386/80387 combination. - - * The 'rep', 'repe', and 'repne' prefixes are added to string - instructions to make them repeat '%ecx' times ('%cx' times if the - current address size is 16-bits). - * The 'rex' family of prefixes is used by x86-64 to encode extensions - to i386 instruction set. The 'rex' prefix has four bits -- an - operand size overwrite ('64') used to change operand size from - 32-bit to 64-bit and X, Y and Z extensions bits used to extend the - register set. - - You may write the 'rex' prefixes directly. The 'rex64xyz' - instruction emits 'rex' prefix with all the bits set. By omitting - the '64', 'x', 'y' or 'z' you may write other prefixes as well. - Normally, there is no need to write the prefixes explicitly, since - gas will automatically generate them based on the instruction - operands. - -9.6 Memory References -===================== - -An Intel syntax indirect memory reference of the form - - SECTION:[BASE + INDEX*SCALE + DISP] - -is translated into the AT&T syntax - - SECTION:DISP(BASE, INDEX, SCALE) - -where BASE and INDEX are the optional 32-bit base and index registers, -DISP is the optional displacement, and SCALE, taking the values 1, 2, 4, -and 8, multiplies INDEX to calculate the address of the operand. If no -SCALE is specified, SCALE is taken to be 1. SECTION specifies the -optional section register for the memory operand, and may override the -default section register (see a 80386 manual for section register -defaults). Note that section overrides in AT&T syntax _must_ be -preceded by a '%'. If you specify a section override which coincides -with the default section register, 'as' does _not_ output any section -register override prefixes to assemble the given instruction. Thus, -section overrides can be specified to emphasize which section register -is used for a given memory operand. - - Here are some examples of Intel and AT&T style memory references: - -AT&T: '-4(%ebp)', Intel: '[ebp - 4]' - BASE is '%ebp'; DISP is '-4'. SECTION is missing, and the default - section is used ('%ss' for addressing with '%ebp' as the base - register). INDEX, SCALE are both missing. - -AT&T: 'foo(,%eax,4)', Intel: '[foo + eax*4]' - INDEX is '%eax' (scaled by a SCALE 4); DISP is 'foo'. All other - fields are missing. The section register here defaults to '%ds'. - -AT&T: 'foo(,1)'; Intel '[foo]' - This uses the value pointed to by 'foo' as a memory operand. Note - that BASE and INDEX are both missing, but there is only _one_ ','. - This is a syntactic exception. - -AT&T: '%gs:foo'; Intel 'gs:foo' - This selects the contents of the variable 'foo' with section - register SECTION being '%gs'. - - Absolute (as opposed to PC relative) call and jump operands must be -prefixed with '*'. If no '*' is specified, 'as' always chooses PC -relative addressing for jump/call labels. - - Any instruction that has a memory operand, but no register operand, -_must_ specify its size (byte, word, long, or quadruple) with an -instruction mnemonic suffix ('b', 'w', 'l' or 'q', respectively). - - The x86-64 architecture adds an RIP (instruction pointer relative) -addressing. This addressing mode is specified by using 'rip' as a base -register. Only constant offsets are valid. For example: - -AT&T: '1234(%rip)', Intel: '[rip + 1234]' - Points to the address 1234 bytes past the end of the current - instruction. - -AT&T: 'symbol(%rip)', Intel: '[rip + symbol]' - Points to the 'symbol' in RIP relative way, this is shorter than - the default absolute addressing. - - Other addressing modes remain unchanged in x86-64 architecture, -except registers used are 64-bit instead of 32-bit. - -9.7 Handling of Jump Instructions -================================= - -Jump instructions are always optimized to use the smallest possible -displacements. This is accomplished by using byte (8-bit) displacement -jumps whenever the target is sufficiently close. If a byte displacement -is insufficient a long displacement is used. We do not support word -(16-bit) displacement jumps in 32-bit mode (i.e. prefixing the jump -instruction with the 'data16' instruction prefix), since the 80386 -insists upon masking '%eip' to 16 bits after the word displacement is -added. (See also *note i386-Arch::) - - Note that the 'jcxz', 'jecxz', 'loop', 'loopz', 'loope', 'loopnz' and -'loopne' instructions only come in byte displacements, so that if you -use these instructions ('gcc' does not use them) you may get an error -message (and incorrect code). The AT&T 80386 assembler tries to get -around this problem by expanding 'jcxz foo' to - - jcxz cx_zero - jmp cx_nonzero - cx_zero: jmp foo - cx_nonzero: - -9.8 Floating Point -================== - -All 80387 floating point types except packed BCD are supported. (BCD -support may be added without much difficulty). These data types are -16-, 32-, and 64- bit integers, and single (32-bit), double (64-bit), -and extended (80-bit) precision floating point. Each supported type has -an instruction mnemonic suffix and a constructor associated with it. -Instruction mnemonic suffixes specify the operand's data type. -Constructors build these data types into memory. - - * Floating point constructors are '.float' or '.single', '.double', - and '.tfloat' for 32-, 64-, and 80-bit formats. These correspond - to instruction mnemonic suffixes 's', 'l', and 't'. 't' stands for - 80-bit (ten byte) real. The 80387 only supports this format via - the 'fldt' (load 80-bit real to stack top) and 'fstpt' (store - 80-bit real and pop stack) instructions. - - * Integer constructors are '.word', '.long' or '.int', and '.quad' - for the 16-, 32-, and 64-bit integer formats. The corresponding - instruction mnemonic suffixes are 's' (single), 'l' (long), and 'q' - (quad). As with the 80-bit real format, the 64-bit 'q' format is - only present in the 'fildq' (load quad integer to stack top) and - 'fistpq' (store quad integer and pop stack) instructions. - - Register to register operations should not use instruction mnemonic -suffixes. 'fstl %st, %st(1)' will give a warning, and be assembled as -if you wrote 'fst %st, %st(1)', since all register to register -operations use 80-bit floating point operands. (Contrast this with -'fstl %st, mem', which converts '%st' from 80-bit to 64-bit floating -point format, then stores the result in the 4 byte location 'mem') - -9.9 Intel's MMX and AMD's 3DNow! SIMD Operations -================================================ - -'as' supports Intel's MMX instruction set (SIMD instructions for integer -data), available on Intel's Pentium MMX processors and Pentium II -processors, AMD's K6 and K6-2 processors, Cyrix' M2 processor, and -probably others. It also supports AMD's 3DNow! instruction set (SIMD -instructions for 32-bit floating point data) available on AMD's K6-2 -processor and possibly others in the future. - - Currently, 'as' does not support Intel's floating point SIMD, Katmai -(KNI). - - The eight 64-bit MMX operands, also used by 3DNow!, are called -'%mm0', '%mm1', ... '%mm7'. They contain eight 8-bit integers, four -16-bit integers, two 32-bit integers, one 64-bit integer, or two 32-bit -floating point values. The MMX registers cannot be used at the same -time as the floating point stack. - - See Intel and AMD documentation, keeping in mind that the operand -order in instructions is reversed from the Intel syntax. - -9.10 Writing 16-bit Code -======================== - -While 'as' normally writes only "pure" 32-bit i386 code or 64-bit x86-64 -code depending on the default configuration, it also supports writing -code to run in real mode or in 16-bit protected mode code segments. To -do this, put a '.code16' or '.code16gcc' directive before the assembly -language instructions to be run in 16-bit mode. You can switch 'as' -back to writing normal 32-bit code with the '.code32' directive. - - '.code16gcc' provides experimental support for generating 16-bit code -from gcc, and differs from '.code16' in that 'call', 'ret', 'enter', -'leave', 'push', 'pop', 'pusha', 'popa', 'pushf', and 'popf' -instructions default to 32-bit size. This is so that the stack pointer -is manipulated in the same way over function calls, allowing access to -function parameters at the same stack offsets as in 32-bit mode. -'.code16gcc' also automatically adds address size prefixes where -necessary to use the 32-bit addressing modes that gcc generates. - - The code which 'as' generates in 16-bit mode will not necessarily run -on a 16-bit pre-80386 processor. To write code that runs on such a -processor, you must refrain from using _any_ 32-bit constructs which -require 'as' to output address or operand size prefixes. - - Note that writing 16-bit code instructions by explicitly specifying a -prefix or an instruction mnemonic suffix within a 32-bit code section -generates different machine instructions than those generated for a -16-bit code segment. In a 32-bit code section, the following code -generates the machine opcode bytes '66 6a 04', which pushes the value -'4' onto the stack, decrementing '%esp' by 2. - - pushw $4 - - The same code in a 16-bit code section would generate the machine -opcode bytes '6a 04' (i.e., without the operand size prefix), which is -correct since the processor default operand size is assumed to be 16 -bits in a 16-bit code section. - -9.11 AT&T Syntax bugs -===================== - -The UnixWare assembler, and probably other AT&T derived ix86 Unix -assemblers, generate floating point instructions with reversed source -and destination registers in certain cases. Unfortunately, gcc and -possibly many other programs use this reversed syntax, so we're stuck -with it. - - For example - - fsub %st,%st(3) -results in '%st(3)' being updated to '%st - %st(3)' rather than the -expected '%st(3) - %st'. This happens with all the non-commutative -arithmetic floating point operations with two register operands where -the source register is '%st' and the destination register is '%st(i)'. - -9.12 Specifying CPU Architecture -================================ - -'as' may be told to assemble for a particular CPU (sub-)architecture -with the '.arch CPU_TYPE' directive. This directive enables a warning -when gas detects an instruction that is not supported on the CPU -specified. The choices for CPU_TYPE are: - -'i8086' 'i186' 'i286' 'i386' -'i486' 'i586' 'i686' 'pentium' -'pentiumpro' 'pentiumii' 'pentiumiii' 'pentium4' -'prescott' 'nocona' 'core' 'core2' -'amdfam10' -'k6' 'athlon' 'sledgehammer' 'k8' -'.mmx' '.sse' '.sse2' '.sse3' -'.ssse3' '.sse4.1' '.sse4.2' '.sse4' -'.sse4a' '.3dnow' '.3dnowa' '.padlock' -'.pacifica' '.svme' '.abm' - - Apart from the warning, there are only two other effects on 'as' -operation; Firstly, if you specify a CPU other than 'i486', then shift -by one instructions such as 'sarl $1, %eax' will automatically use a two -byte opcode sequence. The larger three byte opcode sequence is used on -the 486 (and when no architecture is specified) because it executes -faster on the 486. Note that you can explicitly request the two byte -opcode by writing 'sarl %eax'. Secondly, if you specify 'i8086', -'i186', or 'i286', _and_ '.code16' or '.code16gcc' then byte offset -conditional jumps will be promoted when necessary to a two instruction -sequence consisting of a conditional jump of the opposite sense around -an unconditional jump to the target. - - Following the CPU architecture (but not a sub-architecture, which are -those starting with a dot), you may specify 'jumps' or 'nojumps' to -control automatic promotion of conditional jumps. 'jumps' is the -default, and enables jump promotion; All external jumps will be of the -long variety, and file-local jumps will be promoted as necessary. -(*note i386-Jumps::) 'nojumps' leaves external conditional jumps as byte -offset jumps, and warns about file-local conditional jumps that 'as' -promotes. Unconditional jumps are treated as for 'jumps'. - - For example - - .arch i8086,nojumps - -9.13 Notes -========== - -There is some trickery concerning the 'mul' and 'imul' instructions that -deserves mention. The 16-, 32-, 64- and 128-bit expanding multiplies -(base opcode '0xf6'; extension 4 for 'mul' and 5 for 'imul') can be -output only in the one operand form. Thus, 'imul %ebx, %eax' does _not_ -select the expanding multiply; the expanding multiply would clobber the -'%edx' register, and this would confuse 'gcc' output. Use 'imul %ebx' -to get the 64-bit product in '%edx:%eax'. - - We have added a two operand form of 'imul' when the first operand is -an immediate mode expression and the second operand is a register. This -is just a shorthand, so that, multiplying '%eax' by 69, for example, can -be done with 'imul $69, %eax' rather than 'imul $69, %eax, %eax'. - -10 IA-64 Dependent Features -*************************** - -10.1 Options -============ - -'-mconstant-gp' - This option instructs the assembler to mark the resulting object - file as using the "constant GP" model. With this model, it is - assumed that the entire program uses a single global pointer (GP) - value. Note that this option does not in any fashion affect the - machine code emitted by the assembler. All it does is turn on the - EF_IA_64_CONS_GP flag in the ELF file header. - -'-mauto-pic' - This option instructs the assembler to mark the resulting object - file as using the "constant GP without function descriptor" data - model. This model is like the "constant GP" model, except that it - additionally does away with function descriptors. What this means - is that the address of a function refers directly to the function's - code entry-point. Normally, such an address would refer to a - function descriptor, which contains both the code entry-point and - the GP-value needed by the function. Note that this option does - not in any fashion affect the machine code emitted by the - assembler. All it does is turn on the EF_IA_64_NOFUNCDESC_CONS_GP - flag in the ELF file header. - -'-milp32' -'-milp64' -'-mlp64' -'-mp64' - These options select the data model. The assembler defaults to - '-mlp64' (LP64 data model). - -'-mle' -'-mbe' - These options select the byte order. The '-mle' option selects - little-endian byte order (default) and '-mbe' selects big-endian - byte order. Note that IA-64 machine code always uses little-endian - byte order. - -'-mtune=itanium1' -'-mtune=itanium2' - Tune for a particular IA-64 CPU, ITANIUM1 or ITANIUM2. The default - is ITANIUM2. - -'-munwind-check=warning' -'-munwind-check=error' - These options control what the assembler will do when performing - consistency checks on unwind directives. '-munwind-check=warning' - will make the assembler issue a warning when an unwind directive - check fails. This is the default. '-munwind-check=error' will - make the assembler issue an error when an unwind directive check - fails. - -'-mhint.b=ok' -'-mhint.b=warning' -'-mhint.b=error' - These options control what the assembler will do when the 'hint.b' - instruction is used. '-mhint.b=ok' will make the assembler accept - 'hint.b'. '-mint.b=warning' will make the assembler issue a - warning when 'hint.b' is used. '-mhint.b=error' will make the - assembler treat 'hint.b' as an error, which is the default. - -'-x' -'-xexplicit' - These options turn on dependency violation checking. - -'-xauto' - This option instructs the assembler to automatically insert stop - bits where necessary to remove dependency violations. This is the - default mode. - -'-xnone' - This option turns off dependency violation checking. - -'-xdebug' - This turns on debug output intended to help tracking down bugs in - the dependency violation checker. - -'-xdebugn' - This is a shortcut for -xnone -xdebug. - -'-xdebugx' - This is a shortcut for -xexplicit -xdebug. - -10.2 Syntax -=========== - -The assembler syntax closely follows the IA-64 Assembly Language -Reference Guide. - -10.2.1 Special Characters -------------------------- - -'//' is the line comment token. - - ';' can be used instead of a newline to separate statements. - -10.2.2 Register Names ---------------------- - -The 128 integer registers are referred to as 'rN'. The 128 -floating-point registers are referred to as 'fN'. The 128 application -registers are referred to as 'arN'. The 128 control registers are -referred to as 'crN'. The 64 one-bit predicate registers are referred -to as 'pN'. The 8 branch registers are referred to as 'bN'. In -addition, the assembler defines a number of aliases: 'gp' ('r1'), 'sp' -('r12'), 'rp' ('b0'), 'ret0' ('r8'), 'ret1' ('r9'), 'ret2' ('r10'), -'ret3' ('r9'), 'fargN' ('f8+N'), and 'fretN' ('f8+N'). - - For convenience, the assembler also defines aliases for all named -application and control registers. For example, 'ar.bsp' refers to the -register backing store pointer ('ar17'). Similarly, 'cr.eoi' refers to -the end-of-interrupt register ('cr67'). - -10.2.3 IA-64 Processor-Status-Register (PSR) Bit Names ------------------------------------------------------- - -The assembler defines bit masks for each of the bits in the IA-64 -processor status register. For example, 'psr.ic' corresponds to a value -of 0x2000. These masks are primarily intended for use with the -'ssm'/'sum' and 'rsm'/'rum' instructions, but they can be used anywhere -else where an integer constant is expected. - -10.3 Opcodes -============ - -For detailed information on the IA-64 machine instruction set, see the -IA-64 Architecture Handbook -(http://developer.intel.com/design/itanium/arch_spec.htm). - -11 MIPS Dependent Features -************************** - -GNU 'as' for MIPS architectures supports several different MIPS -processors, and MIPS ISA levels I through V, MIPS32, and MIPS64. For -information about the MIPS instruction set, see 'MIPS RISC -Architecture', by Kane and Heindrich (Prentice-Hall). For an overview -of MIPS assembly conventions, see "Appendix D: Assembly Language -Programming" in the same work. - -11.1 Assembler options -====================== - -The MIPS configurations of GNU 'as' support these special options: - -'-G NUM' - This option sets the largest size of an object that can be - referenced implicitly with the 'gp' register. It is only accepted - for targets that use ECOFF format. The default value is 8. - -'-EB' -'-EL' - Any MIPS configuration of 'as' can select big-endian or - little-endian output at run time (unlike the other GNU development - tools, which must be configured for one or the other). Use '-EB' - to select big-endian output, and '-EL' for little-endian. - -'-KPIC' - Generate SVR4-style PIC. This option tells the assembler to - generate SVR4-style position-independent macro expansions. It also - tells the assembler to mark the output file as PIC. - -'-mvxworks-pic' - Generate VxWorks PIC. This option tells the assembler to generate - VxWorks-style position-independent macro expansions. - -'-mips1' -'-mips2' -'-mips3' -'-mips4' -'-mips5' -'-mips32' -'-mips32r2' -'-mips64' -'-mips64r2' - Generate code for a particular MIPS Instruction Set Architecture - level. '-mips1' corresponds to the R2000 and R3000 processors, - '-mips2' to the R6000 processor, '-mips3' to the R4000 processor, - and '-mips4' to the R8000 and R10000 processors. '-mips5', - '-mips32', '-mips32r2', '-mips64', and '-mips64r2' correspond to - generic MIPS V, MIPS32, MIPS32 RELEASE 2, MIPS64, and MIPS64 - RELEASE 2 ISA processors, respectively. You can also switch - instruction sets during the assembly; see *note Directives to - override the ISA level: MIPS ISA. - -'-mgp32' -'-mfp32' - Some macros have different expansions for 32-bit and 64-bit - registers. The register sizes are normally inferred from the ISA - and ABI, but these flags force a certain group of registers to be - treated as 32 bits wide at all times. '-mgp32' controls the size - of general-purpose registers and '-mfp32' controls the size of - floating-point registers. - - The '.set gp=32' and '.set fp=32' directives allow the size of - registers to be changed for parts of an object. The default value - is restored by '.set gp=default' and '.set fp=default'. - - On some MIPS variants there is a 32-bit mode flag; when this flag - is set, 64-bit instructions generate a trap. Also, some 32-bit - OSes only save the 32-bit registers on a context switch, so it is - essential never to use the 64-bit registers. - -'-mgp64' -'-mfp64' - Assume that 64-bit registers are available. This is provided in - the interests of symmetry with '-mgp32' and '-mfp32'. - - The '.set gp=64' and '.set fp=64' directives allow the size of - registers to be changed for parts of an object. The default value - is restored by '.set gp=default' and '.set fp=default'. - -'-mips16' -'-no-mips16' - Generate code for the MIPS 16 processor. This is equivalent to - putting '.set mips16' at the start of the assembly file. - '-no-mips16' turns off this option. - -'-msmartmips' -'-mno-smartmips' - Enables the SmartMIPS extensions to the MIPS32 instruction set, - which provides a number of new instructions which target smartcard - and cryptographic applications. This is equivalent to putting - '.set smartmips' at the start of the assembly file. - '-mno-smartmips' turns off this option. - -'-mips3d' -'-no-mips3d' - Generate code for the MIPS-3D Application Specific Extension. This - tells the assembler to accept MIPS-3D instructions. '-no-mips3d' - turns off this option. - -'-mdmx' -'-no-mdmx' - Generate code for the MDMX Application Specific Extension. This - tells the assembler to accept MDMX instructions. '-no-mdmx' turns - off this option. - -'-mdsp' -'-mno-dsp' - Generate code for the DSP Release 1 Application Specific Extension. - This tells the assembler to accept DSP Release 1 instructions. - '-mno-dsp' turns off this option. - -'-mdspr2' -'-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. '-mno-dspr2' turns off this option. - -'-mmt' -'-mno-mt' - Generate code for the MT Application Specific Extension. This - tells the assembler to accept MT instructions. '-mno-mt' turns off - this option. - -'-mfix7000' -'-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. - -'-mfix-vr4120' -'-no-mfix-vr4120' - Insert nops to work around certain VR4120 errata. This option is - intended to be used on GCC-generated code: it is not designed to - catch all problems in hand-written assembler code. - -'-mfix-vr4130' -'-no-mfix-vr4130' - Insert nops to work around the VR4130 'mflo'/'mfhi' errata. - -'-m4010' -'-no-m4010' - Generate code for the LSI R4010 chip. This tells the assembler to - accept the R4010 specific instructions ('addciu', 'ffc', etc.), and - to not schedule 'nop' instructions around accesses to the 'HI' and - 'LO' registers. '-no-m4010' turns off this option. - -'-m4650' -'-no-m4650' - Generate code for the MIPS R4650 chip. This tells the assembler to - accept the 'mad' and 'madu' instruction, and to not schedule 'nop' - instructions around accesses to the 'HI' and 'LO' registers. - '-no-m4650' turns off this option. - -'-m3900' -'-no-m3900' -'-m4100' -'-no-m4100' - For each option '-mNNNN', generate code for the MIPS RNNNN chip. - This tells the assembler to accept instructions specific to that - chip, and to schedule for that chip's hazards. - -'-march=CPU' - Generate code for a particular MIPS cpu. It is exactly equivalent - to '-mCPU', except that there are more value of CPU understood. - Valid CPU value are: - - 2000, 3000, 3900, 4000, 4010, 4100, 4111, vr4120, vr4130, - vr4181, 4300, 4400, 4600, 4650, 5000, rm5200, rm5230, rm5231, - rm5261, rm5721, vr5400, vr5500, 6000, rm7000, 8000, rm9000, - 10000, 12000, 4kc, 4km, 4kp, 4ksc, 4kec, 4kem, 4kep, 4ksd, - m4k, m4kp, 24kc, 24kf, 24kx, 24kec, 24kef, 24kex, 34kc, 34kf, - 34kx, 74kc, 74kf, 74kx, 5kc, 5kf, 20kc, 25kf, sb1, sb1a - -'-mtune=CPU' - Schedule and tune for a particular MIPS cpu. Valid CPU values are - identical to '-march=CPU'. - -'-mabi=ABI' - Record which ABI the source code uses. The recognized arguments - are: '32', 'n32', 'o64', '64' and 'eabi'. - -'-msym32' -'-mno-sym32' - Equivalent to adding '.set sym32' or '.set nosym32' to the - beginning of the assembler input. *Note MIPS symbol sizes::. - -'-nocpp' - This option is ignored. It is accepted for command-line - compatibility with other assemblers, which use it to turn off C - style preprocessing. With GNU 'as', there is no need for '-nocpp', - because the GNU assembler itself never runs the C preprocessor. - -'--construct-floats' -'--no-construct-floats' - The '--no-construct-floats' option disables the construction of - double width floating point constants by loading the two halves of - the value into the two single width floating point registers that - make up the double width register. This feature is useful if the - processor support the FR bit in its status register, and this bit - is known (by the programmer) to be set. This bit prevents the - aliasing of the double width register by the single width - registers. - - By default '--construct-floats' is selected, allowing construction - of these floating point constants. - -'--trap' -'--no-break' - 'as' automatically macro expands certain division and - multiplication instructions to check for overflow and division by - zero. This option causes 'as' to generate code to take a trap - exception rather than a break exception when an error is detected. - The trap instructions are only supported at Instruction Set - Architecture level 2 and higher. - -'--break' -'--no-trap' - Generate code to take a break exception rather than a trap - exception when an error is detected. This is the default. - -'-mpdr' -'-mno-pdr' - Control generation of '.pdr' sections. Off by default on IRIX, on - elsewhere. - -'-mshared' -'-mno-shared' - When generating code using the Unix calling conventions (selected - by '-KPIC' or '-mcall_shared'), gas will normally generate code - which can go into a shared library. The '-mno-shared' option tells - gas to generate code which uses the calling convention, but can not - go into a shared library. The resulting code is slightly more - efficient. This option only affects the handling of the '.cpload' - and '.cpsetup' pseudo-ops. - -11.2 MIPS ECOFF object code -=========================== - -Assembling for a MIPS ECOFF target supports some additional sections -besides the usual '.text', '.data' and '.bss'. The additional sections -are '.rdata', used for read-only data, '.sdata', used for small data, -and '.sbss', used for small common objects. - - When assembling for ECOFF, the assembler uses the '$gp' ('$28') -register to form the address of a "small object". Any object in the -'.sdata' or '.sbss' sections is considered "small" in this sense. For -external objects, or for objects in the '.bss' section, you can use the -'gcc' '-G' option to control the size of objects addressed via '$gp'; -the default value is 8, meaning that a reference to any object eight -bytes or smaller uses '$gp'. Passing '-G 0' to 'as' prevents it from -using the '$gp' register on the basis of object size (but the assembler -uses '$gp' for objects in '.sdata' or 'sbss' in any case). The size of -an object in the '.bss' section is set by the '.comm' or '.lcomm' -directive that defines it. The size of an external object may be set -with the '.extern' directive. For example, '.extern sym,4' declares -that the object at 'sym' is 4 bytes in length, whie leaving 'sym' -otherwise undefined. - - Using small ECOFF objects requires linker support, and assumes that -the '$gp' register is correctly initialized (normally done automatically -by the startup code). MIPS ECOFF assembly code must not modify the -'$gp' register. - -11.3 Directives for debugging information -========================================= - -MIPS ECOFF 'as' supports several directives used for generating -debugging information which are not support by traditional MIPS -assemblers. These are '.def', '.endef', '.dim', '.file', '.scl', -'.size', '.tag', '.type', '.val', '.stabd', '.stabn', and '.stabs'. The -debugging information generated by the three '.stab' directives can only -be read by GDB, not by traditional MIPS debuggers (this enhancement is -required to fully support C++ debugging). These directives are -primarily used by compilers, not assembly language programmers! - -11.4 Directives to override the size of symbols -=============================================== - -The n64 ABI allows symbols to have any 64-bit value. Although this -provides a great deal of flexibility, it means that some macros have -much longer expansions than their 32-bit counterparts. For example, the -non-PIC expansion of 'dla $4,sym' is usually: - - lui $4,%highest(sym) - lui $1,%hi(sym) - daddiu $4,$4,%higher(sym) - daddiu $1,$1,%lo(sym) - dsll32 $4,$4,0 - daddu $4,$4,$1 - - whereas the 32-bit expansion is simply: - - lui $4,%hi(sym) - daddiu $4,$4,%lo(sym) - - n64 code is sometimes constructed in such a way that all symbolic -constants are known to have 32-bit values, and in such cases, it's -preferable to use the 32-bit expansion instead of the 64-bit expansion. - - You can use the '.set sym32' directive to tell the assembler that, -from this point on, all expressions of the form 'SYMBOL' or 'SYMBOL + -OFFSET' have 32-bit values. For example: - - .set sym32 - dla $4,sym - lw $4,sym+16 - sw $4,sym+0x8000($4) - - will cause the assembler to treat 'sym', 'sym+16' and 'sym+0x8000' as -32-bit values. The handling of non-symbolic addresses is not affected. - - The directive '.set nosym32' ends a '.set sym32' block and reverts to -the normal behavior. It is also possible to change the symbol size -using the command-line options '-msym32' and '-mno-sym32'. - - These options and directives are always accepted, but at present, -they have no effect for anything other than n64. - -11.5 Directives to override the ISA level -========================================= - -GNU 'as' supports an additional directive to change the MIPS Instruction -Set Architecture level on the fly: '.set mipsN'. N should be a number -from 0 to 5, or 32, 32r2, 64 or 64r2. The values other than 0 make the -assembler accept instructions for the corresponding ISA level, from that -point on in the assembly. '.set mipsN' affects not only which -instructions are permitted, but also how certain macros are expanded. -'.set mips0' restores the ISA level to its original level: either the -level you selected with command line options, or the default for your -configuration. You can use this feature to permit specific MIPS3 -instructions while assembling in 32 bit mode. Use this directive with -care! - - The '.set arch=CPU' directive provides even finer control. It -changes the effective CPU target and allows the assembler to use -instructions specific to a particular CPU. All CPUs supported by the -'-march' command line option are also selectable by this directive. The -original value is restored by '.set arch=default'. - - The directive '.set mips16' puts the assembler into MIPS 16 mode, in -which it will assemble instructions for the MIPS 16 processor. Use -'.set nomips16' to return to normal 32 bit mode. - - Traditional MIPS assemblers do not support this directive. - -11.6 Directives for extending MIPS 16 bit instructions -====================================================== - -By default, MIPS 16 instructions are automatically extended to 32 bits -when necessary. The directive '.set noautoextend' will turn this off. -When '.set noautoextend' is in effect, any 32 bit instruction must be -explicitly extended with the '.e' modifier (e.g., 'li.e $4,1000'). The -directive '.set autoextend' may be used to once again automatically -extend instructions when necessary. - - This directive is only meaningful when in MIPS 16 mode. Traditional -MIPS assemblers do not support this directive. - -11.7 Directive to mark data as an instruction -============================================= - -The '.insn' directive tells 'as' that the following data is actually -instructions. This makes a difference in MIPS 16 mode: when loading the -address of a label which precedes instructions, 'as' automatically adds -1 to the value, so that jumping to the loaded address will do the right -thing. - -11.8 Directives to save and restore options -=========================================== - -The directives '.set push' and '.set pop' may be used to save and -restore the current settings for all the options which are controlled by -'.set'. The '.set push' directive saves the current settings on a -stack. The '.set pop' directive pops the stack and restores the -settings. - - These directives can be useful inside an macro which must change an -option such as the ISA level or instruction reordering but does not want -to change the state of the code which invoked the macro. - - Traditional MIPS assemblers do not support these directives. - -11.9 Directives to control generation of MIPS ASE instructions -============================================================== - -The directive '.set mips3d' makes the assembler accept instructions from -the MIPS-3D Application Specific Extension from that point on in the -assembly. The '.set nomips3d' directive prevents MIPS-3D instructions -from being accepted. - - The directive '.set smartmips' makes the assembler accept -instructions from the SmartMIPS Application Specific Extension to the -MIPS32 ISA from that point on in the assembly. The '.set nosmartmips' -directive prevents SmartMIPS instructions from being accepted. - - The directive '.set mdmx' makes the assembler accept instructions -from the MDMX Application Specific Extension from that point on in the -assembly. The '.set nomdmx' directive prevents MDMX instructions from -being accepted. - - The directive '.set dsp' makes the assembler accept instructions from -the DSP Release 1 Application Specific Extension from that point on in -the assembly. The '.set nodsp' directive prevents DSP Release 1 -instructions from being accepted. - - The directive '.set dspr2' makes the assembler accept instructions -from the DSP Release 2 Application Specific Extension from that point on -in the assembly. This dirctive implies '.set dsp'. The '.set nodspr2' -directive prevents DSP Release 2 instructions from being accepted. - - The directive '.set mt' makes the assembler accept instructions from -the MT Application Specific Extension from that point on in the -assembly. The '.set nomt' directive prevents MT instructions from being -accepted. - - Traditional MIPS assemblers do not support these directives. - -12 PowerPC Dependent Features -***************************** - -12.1 Options -============ - -The PowerPC chip family includes several successive levels, using the -same core instruction set, but including a few additional instructions -at each level. There are exceptions to this however. For details on -what instructions each variant supports, please see the chip's -architecture reference manual. - - The following table lists all available PowerPC options. - -'-mpwrx | -mpwr2' - Generate code for POWER/2 (RIOS2). - -'-mpwr' - Generate code for POWER (RIOS1) - -'-m601' - Generate code for PowerPC 601. - -'-mppc, -mppc32, -m603, -m604' - Generate code for PowerPC 603/604. - -'-m403, -m405' - Generate code for PowerPC 403/405. - -'-m440' - Generate code for PowerPC 440. BookE and some 405 instructions. - -'-m7400, -m7410, -m7450, -m7455' - Generate code for PowerPC 7400/7410/7450/7455. - -'-mppc64, -m620' - Generate code for PowerPC 620/625/630. - -'-me500, -me500x2' - Generate code for Motorola e500 core complex. - -'-mspe' - Generate code for Motorola SPE instructions. - -'-mppc64bridge' - Generate code for PowerPC 64, including bridge insns. - -'-mbooke64' - Generate code for 64-bit BookE. - -'-mbooke, mbooke32' - Generate code for 32-bit BookE. - -'-me300' - Generate code for PowerPC e300 family. - -'-maltivec' - Generate code for processors with AltiVec instructions. - -'-mpower4' - Generate code for Power4 architecture. - -'-mpower5' - Generate code for Power5 architecture. - -'-mpower6' - Generate code for Power6 architecture. - -'-mcell' - Generate code for Cell Broadband Engine architecture. - -'-mcom' - Generate code Power/PowerPC common instructions. - -'-many' - Generate code for any architecture (PWR/PWRX/PPC). - -'-mregnames' - Allow symbolic names for registers. - -'-mno-regnames' - Do not allow symbolic names for registers. - -'-mrelocatable' - Support for GCC's -mrelocatable option. - -'-mrelocatable-lib' - Support for GCC's -mrelocatable-lib option. - -'-memb' - Set PPC_EMB bit in ELF flags. - -'-mlittle, -mlittle-endian' - Generate code for a little endian machine. - -'-mbig, -mbig-endian' - Generate code for a big endian machine. - -'-msolaris' - Generate code for Solaris. - -'-mno-solaris' - Do not generate code for Solaris. - -12.2 PowerPC Assembler Directives -================================= - -A number of assembler directives are available for PowerPC. The -following table is far from complete. - -'.machine "string"' - This directive allows you to change the machine for which code is - generated. '"string"' may be any of the -m cpu selection options - (without the -m) enclosed in double quotes, '"push"', or '"pop"'. - '.machine "push"' saves the currently selected cpu, which may be - restored with '.machine "pop"'. - -13 SPARC Dependent Features -*************************** - -13.1 Options -============ - -The SPARC chip family includes several successive levels, using the same -core instruction set, but including a few additional instructions at -each level. There are exceptions to this however. For details on what -instructions each variant supports, please see the chip's architecture -reference manual. - - By default, 'as' assumes the core instruction set (SPARC v6), but -"bumps" the architecture level as needed: it switches to successively -higher architectures as it encounters instructions that only exist in -the higher levels. - - If not configured for SPARC v9 ('sparc64-*-*') GAS will not bump -passed sparclite by default, an option must be passed to enable the v9 -instructions. - - GAS treats sparclite as being compatible with v8, unless an -architecture is explicitly requested. SPARC v9 is always incompatible -with sparclite. - -'-Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite' -'-Av8plus | -Av8plusa | -Av9 | -Av9a' - Use one of the '-A' options to select one of the SPARC - architectures explicitly. If you select an architecture - explicitly, 'as' reports a fatal error if it encounters an - instruction or feature requiring an incompatible or higher level. - - '-Av8plus' and '-Av8plusa' select a 32 bit environment. - - '-Av9' and '-Av9a' select a 64 bit environment and are not - available unless GAS is explicitly configured with 64 bit - environment support. - - '-Av8plusa' and '-Av9a' enable the SPARC V9 instruction set with - UltraSPARC extensions. - -'-xarch=v8plus | -xarch=v8plusa' - For compatibility with the Solaris v9 assembler. These options are - equivalent to -Av8plus and -Av8plusa, respectively. - -'-bump' - Warn whenever it is necessary to switch to another level. If an - architecture level is explicitly requested, GAS will not issue - warnings until that level is reached, and will then bump the level - as required (except between incompatible levels). - -'-32 | -64' - Select the word size, either 32 bits or 64 bits. These options are - only available with the ELF object file format, and require that - the necessary BFD support has been included. - -13.2 Enforcing aligned data -=========================== - -SPARC GAS normally permits data to be misaligned. For example, it -permits the '.long' pseudo-op to be used on a byte boundary. However, -the native SunOS and Solaris assemblers issue an error when they see -misaligned data. - - You can use the '--enforce-aligned-data' option to make SPARC GAS -also issue an error about misaligned data, just as the SunOS and Solaris -assemblers do. - - The '--enforce-aligned-data' option is not the default because gcc -issues misaligned data pseudo-ops when it initializes certain packed -data structures (structures defined using the 'packed' attribute). You -may have to assemble with GAS in order to initialize packed data -structures in your own code. - -13.3 Floating Point -=================== - -The Sparc uses IEEE floating-point numbers. - -13.4 Sparc Machine Directives -============================= - -The Sparc version of 'as' supports the following additional machine -directives: - -'.align' - This must be followed by the desired alignment in bytes. - -'.common' - This must be followed by a symbol name, a positive number, and - '"bss"'. This behaves somewhat like '.comm', but the syntax is - different. - -'.half' - This is functionally identical to '.short'. - -'.nword' - On the Sparc, the '.nword' directive produces native word sized - value, ie. if assembling with -32 it is equivalent to '.word', if - assembling with -64 it is equivalent to '.xword'. - -'.proc' - This directive is ignored. Any text following it on the same line - is also ignored. - -'.register' - This directive declares use of a global application or system - register. It must be followed by a register name %g2, %g3, %g6 or - %g7, comma and the symbol name for that register. If symbol name - is '#scratch', it is a scratch register, if it is '#ignore', it - just suppresses any errors about using undeclared global register, - but does not emit any information about it into the object file. - This can be useful e.g. if you save the register before use and - restore it after. - -'.reserve' - This must be followed by a symbol name, a positive number, and - '"bss"'. This behaves somewhat like '.lcomm', but the syntax is - different. - -'.seg' - This must be followed by '"text"', '"data"', or '"data1"'. It - behaves like '.text', '.data', or '.data 1'. - -'.skip' - This is functionally identical to the '.space' directive. - -'.word' - On the Sparc, the '.word' directive produces 32 bit values, instead - of the 16 bit values it produces on many other machines. - -'.xword' - On the Sparc V9 processor, the '.xword' directive produces 64 bit - values. - -14 Reporting Bugs -***************** - -Your bug reports play an essential role in making 'as' reliable. - - 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 'as' work -better. Bug reports are your contribution to the maintenance of 'as'. - - In order for a bug report to serve its purpose, you must include the -information that enables us to fix the bug. - -14.1 Have You Found a Bug? -========================== - -If you are not sure whether you have found a bug, here are some -guidelines: - - * If the assembler gets a fatal signal, for any input whatever, that - is a 'as' bug. Reliable assemblers never crash. - - * If 'as' produces an error message for valid input, that is a bug. - - * If 'as' does not produce an error message for invalid input, that - is a bug. However, you should note that your idea of "invalid - input" might be our idea of "an extension" or "support for - traditional practice". - - * If you are an experienced user of assemblers, your suggestions for - improvement of 'as' are welcome in any case. - -14.2 How to Report Bugs -======================= - -A number of companies and individuals offer support for GNU products. -If you obtained 'as' from a support organization, we recommend you -contact that organization first. - - You can find contact information for many support companies and -individuals in the file 'etc/SERVICE' in the GNU Emacs distribution. - - The fundamental principle of reporting bugs usefully is this: *report -all the facts*. If you are not sure whether to state a fact or leave it -out, state it! - - Often people omit facts because they think they know what causes the -problem and assume that some details do not matter. Thus, you might -assume that the name of a symbol you use in an example does not matter. -Well, probably it does not, but one cannot be sure. Perhaps the bug is -a stray memory reference which happens to fetch from the location where -that name is stored in memory; perhaps, if the name were different, the -contents of that location would fool the assembler into doing the right -thing despite the bug. Play it safe and give a specific, complete -example. That is the easiest thing for you to do, and the most helpful. - - 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. - - Sometimes people give a few sketchy facts and ask, "Does this ring a -bell?" 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. - - To enable us to fix the bug, you should include all these things: - - * The version of 'as'. 'as' announces it if you start it with the - '--version' argument. - - Without this, we will not know whether there is any point in - looking for the bug in the current version of 'as'. - - * Any patches you may have applied to the 'as' source. - - * The type of machine you are using, and the operating system name - and version number. - - * What compiler (and its version) was used to compile 'as'--e.g. - "'gcc-2.7'". - - * The command arguments you gave the assembler to assemble your - example and observe the bug. To guarantee you will not omit - something important, list them all. A copy of the Makefile (or the - output from make) is sufficient. - - If we were to try to guess the arguments, we would probably guess - wrong and then we might not encounter the bug. - - * A complete input file that will reproduce the bug. If the bug is - observed when the assembler is invoked via a compiler, send the - assembler source, not the high level language source. Most - compilers will produce the assembler source when run with the '-S' - option. If you are using 'gcc', use the options '-v --save-temps'; - this will save the assembler source in a file with an extension of - '.s', and also show you exactly how 'as' is being run. - - * A description of what behavior you observe that you believe is - incorrect. For example, "It gets a fatal signal." - - Of course, if the bug is that 'as' gets a fatal signal, then we - will certainly notice it. But if the bug is incorrect output, we - might not notice unless it is glaringly wrong. You might as well - not give us a chance to make a mistake. - - 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 'as' is out of sync, or you have encountered - a bug in the C library on your system. (This has happened!) Your - copy might crash and ours would not. If you told us to expect a - crash, then when ours fails to crash, we would know that the bug - was not happening for us. If you had not told us to expect a - crash, then we would not be able to draw any conclusion from our - observations. - - * If you wish to suggest changes to the 'as' source, send us context - diffs, as generated by 'diff' with the '-u', '-c', or '-p' option. - Always send diffs from the old file to the new file. If you even - discuss something in the 'as' source, refer to it by context, not - by line number. - - The line numbers in our development sources will not match those in - your sources. Your line numbers would convey no useful information - to us. - - Here are some things that are not necessary: - - * A description of the envelope of the bug. - - 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. - - 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. - - Of course, if you can find a simpler example to report _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. - - 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. - - * A patch for the bug. - - 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. - - Sometimes with a program as complicated as 'as' it is very hard to - construct an example that will make the program follow a certain - path through the code. If you do not send us the example, we will - not be able to construct one, so we will not be able to verify that - the bug is fixed. - - 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. - - * A guess about what the bug is or what it depends on. - - Such guesses are usually wrong. Even we cannot guess right about - such things without first using the debugger to find the facts. - -15 Acknowledgements -******************* - -If you have contributed to GAS and your name isn't listed here, it is -not meant as a slight. We just don't know about it. Send mail to the -maintainer, and we'll correct the situation. Currently the maintainer -is Ken Raeburn (email address 'raeburn@cygnus.com'). - - Dean Elsner wrote the original GNU assembler for the VAX.(1) - - Jay Fenlason maintained GAS for a while, adding support for -GDB-specific debug information and the 68k series machines, most of the -preprocessing pass, and extensive changes in 'messages.c', -'input-file.c', 'write.c'. - - K. Richard Pixley maintained GAS for a while, adding various -enhancements and many bug fixes, including merging support for several -processors, breaking GAS up to handle multiple object file format back -ends (including heavy rewrite, testing, an integration of the coff and -b.out back ends), adding configuration including heavy testing and -verification of cross assemblers and file splits and renaming, converted -GAS to strictly ANSI C including full prototypes, added support for -m680[34]0 and cpu32, did considerable work on i960 including a COFF port -(including considerable amounts of reverse engineering), a SPARC opcode -file rewrite, DECstation, rs6000, and hp300hpux host ports, updated -"know" assertions and made them work, much other reorganization, -cleanup, and lint. - - Ken Raeburn wrote the high-level BFD interface code to replace most -of the code in format-specific I/O modules. - - The original VMS support was contributed by David L. Kashtan. Eric -Youngdale has done much work with it since. - - The Intel 80386 machine description was written by Eliot Dresselhaus. - - Minh Tran-Le at IntelliCorp contributed some AIX 386 support. - - The Motorola 88k machine description was contributed by Devon Bowen -of Buffalo University and Torbjorn Granlund of the Swedish Institute of -Computer Science. - - Keith Knowles at the Open Software Foundation wrote the original MIPS -back end ('tc-mips.c', 'tc-mips.h'), and contributed Rose format support -(which hasn't been merged in yet). Ralph Campbell worked with the MIPS -code to support a.out format. - - Support for the Zilog Z8k and Renesas H8/300 processors (tc-z8k, -tc-h8300), and IEEE 695 object file format (obj-ieee), was written by -Steve Chamberlain of Cygnus Support. Steve also modified the COFF back -end to use BFD for some low-level operations, for use with the H8/300 -and AMD 29k targets. - - John Gilmore built the AMD 29000 support, added '.include' support, -and simplified the configuration of which versions accept which -directives. He updated the 68k machine description so that Motorola's -opcodes always produced fixed-size instructions (e.g., 'jsr'), while -synthetic instructions remained shrinkable ('jbsr'). John fixed many -bugs, including true tested cross-compilation support, and one bug in -relaxation that took a week and required the proverbial one-bit fix. - - Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntax -for the 68k, completed support for some COFF targets (68k, i386 SVR3, -and SCO Unix), added support for MIPS ECOFF and ELF targets, wrote the -initial RS/6000 and PowerPC assembler, and made a few other minor -patches. - - Steve Chamberlain made GAS able to generate listings. - - Hewlett-Packard contributed support for the HP9000/300. - - Jeff Law wrote GAS and BFD support for the native HPPA object format -(SOM) along with a fairly extensive HPPA testsuite (for both SOM and ELF -object formats). This work was supported by both the Center for -Software Science at the University of Utah and Cygnus Support. - - Support for ELF format files has been worked on by Mark Eichin of -Cygnus Support (original, incomplete implementation for SPARC), Pete -Hoogenboom and Jeff Law at the University of Utah (HPPA mainly), Michael -Meissner of the Open Software Foundation (i386 mainly), and Ken Raeburn -of Cygnus Support (sparc, and some initial 64-bit support). - - Linas Vepstas added GAS support for the ESA/390 "IBM 370" -architecture. - - Richard Henderson rewrote the Alpha assembler. Klaus Kaempf wrote -GAS and BFD support for openVMS/Alpha. - - Timothy Wall, Michael Hayes, and Greg Smart contributed to the -various tic* flavors. - - David Heine, Sterling Augustine, Bob Wilson and John Ruttenberg from -Tensilica, Inc. added support for Xtensa processors. - - Several engineers at Cygnus Support have also provided many small bug -fixes and configuration enhancements. - - Many others have contributed large or small bugfixes and -enhancements. If you have contributed significant work and are not -mentioned on this list, and want to be, let us know. Some of the -history has been lost; we are not intentionally leaving anyone out. - -Appendix A GNU Free Documentation License -***************************************** - - Version 1.1, March 2000 - - Copyright (C) 2000, 2003 Free Software Foundation, Inc. - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - 0. PREAMBLE - - The purpose of this License is to make a manual, textbook, or other - written document "free" in the sense of freedom: to assure everyone - the effective freedom to copy and redistribute it, with or without - modifying it, either commercially or noncommercially. Secondarily, - this License preserves for the author and publisher a way to get - credit for their work, while not being considered responsible for - modifications made by others. - - This License is a kind of "copyleft", which means that derivative - works of the document must themselves be free in the same sense. - It complements the GNU General Public License, which is a copyleft - license designed for free software. - - 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. - - - 1. APPLICABILITY AND DEFINITIONS - - This License applies to any manual or other work that contains a - notice placed by the copyright holder saying it can be distributed - under the terms of this License. The "Document", below, refers to - any such manual or work. Any member of the public is a licensee, - and is addressed as "you." - - A "Modified Version" of the Document means any work containing the - Document or a portion of it, either copied verbatim, or with - modifications and/or translated into another language. - - A "Secondary Section" is a named appendix or a front-matter section - of the Document that deals exclusively with the relationship of the - publishers or authors of the Document to the Document's overall - subject (or to related matters) and contains nothing that could - fall directly within that overall subject. (For example, if the - Document is in part a textbook of mathematics, a Secondary Section - may not explain any mathematics.) The relationship could be a - matter of historical connection with the subject or with related - matters, or of legal, commercial, philosophical, ethical or - political position regarding them. - - The "Invariant Sections" are certain Secondary Sections whose - titles are designated, as being those of Invariant Sections, in the - notice that says that the Document is released under this License. - - The "Cover Texts" are certain short passages of text that are - listed, as Front-Cover Texts or Back-Cover Texts, in the notice - that says that the Document is released under this License. - - A "Transparent" copy of the Document means a machine-readable copy, - represented in a format whose specification is available to the - general public, whose contents can be viewed and edited directly - and straightforwardly with generic text editors or (for images - composed of pixels) generic paint programs or (for drawings) some - widely available drawing editor, and that is suitable for input to - text formatters or for automatic translation to a variety of - formats suitable for input to text formatters. A copy made in an - otherwise Transparent file format whose markup has been designed to - thwart or discourage subsequent modification by readers is not - Transparent. A copy that is not "Transparent" is called "Opaque." - - 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. - - The "Title Page" means, for a printed book, the title page itself, - plus such following pages as are needed to hold, legibly, the - material this License requires to appear in the title page. For - works in formats which do not have any title page as such, "Title - Page" means the text near the most prominent appearance of the - work's title, preceding the beginning of the body of the text. - - 2. VERBATIM COPYING - - 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. - - You may also lend copies, under the same conditions stated above, - and you may publicly display copies. - - 3. COPYING IN QUANTITY - - 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. - - 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. - - 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. - - 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. - - 4. MODIFICATIONS - - 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: - - A. Use in the Title Page (and on the covers, if any) a title - distinct from that of the Document, and from those of previous - versions (which should, if there were any, be listed in the History - section of the Document). You may use the same title as a previous - version if the original publisher of that version gives permission. - B. List on the Title Page, as authors, one or more persons or - entities responsible for authorship of the modifications in the - Modified Version, together with at least five of the principal - authors of the Document (all of its principal authors, if it has - less than five). - C. State on the Title page the name of the publisher of the - Modified Version, as the publisher. - D. Preserve all the copyright notices of the Document. - E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. - F. Include, immediately after the copyright notices, a license - notice giving the public permission to use the Modified Version - under the terms of this License, in the form shown in the Addendum - below. - G. Preserve in that license notice the full lists of Invariant - Sections and required Cover Texts given in the Document's license - notice. - H. Include an unaltered copy of this License. - I. Preserve the section entitled "History", and its title, and add - to it an item stating at least the title, year, new authors, and - publisher of the Modified Version as given on the Title Page. If - there is no section entitled "History" in the Document, create one - stating the title, year, authors, and publisher of the Document as - given on its Title Page, then add an item describing the Modified - Version as stated in the previous sentence. - J. Preserve the network location, if any, given in the Document for - public access to a Transparent copy of the Document, and likewise - the network locations given in the Document for previous versions - it was based on. These may be placed in the "History" section. - You may omit a network location for a work that was published at - least four years before the Document itself, or if the original - publisher of the version it refers to gives permission. - K. In any section entitled "Acknowledgements" or "Dedications", - preserve the section's title, and preserve in the section all the - substance and tone of each of the contributor acknowledgements - and/or dedications given therein. - L. Preserve all the Invariant Sections of the Document, unaltered - in their text and in their titles. Section numbers or the - equivalent are not considered part of the section titles. - M. Delete any section entitled "Endorsements." Such a section may - not be included in the Modified Version. - N. Do not retitle any existing section as "Endorsements" or to - conflict in title with any Invariant Section. - - 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. - - You may add a section entitled "Endorsements", provided it contains - nothing but endorsements of your Modified Version by various - parties-for example, statements of peer review or that the text has - been approved by an organization as the authoritative definition of - a standard. - - 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. - - 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. - - 5. COMBINING DOCUMENTS - - 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. - - 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. - - In the combination, you must combine any sections entitled - "History" in the various original documents, forming one section - entitled "History"; likewise combine any sections entitled - "Acknowledgements", and any sections entitled "Dedications." You - must delete all sections entitled "Endorsements." - - 6. COLLECTIONS OF DOCUMENTS - - 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. - - 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. - - 7. AGGREGATION WITH INDEPENDENT WORKS - - A compilation of the Document or its derivatives with other - separate and independent documents or works, in or on a volume of a - storage or distribution medium, does not as a whole count as a - Modified Version of the Document, provided no compilation copyright - is claimed for the compilation. Such a compilation is called an - "aggregate", and this License does not apply to the other - self-contained works thus compiled with the Document, on account of - their being thus compiled, if they are not themselves derivative - works of the Document. - - 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. - - 8. TRANSLATION - - 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. - - 9. TERMINATION - - 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. - - 10. FUTURE REVISIONS OF THIS LICENSE - - 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/. - - Each version of the License is given a distinguishing version - number. If the Document specifies that a particular numbered - version of this License "or any later version" applies to it, you - have the option of following the terms and conditions either of - that specified version or of any later version that has been - published (not as a draft) by the Free Software Foundation. If the - Document does not specify a version number of this License, you may - choose any version ever published (not as a draft) by the Free - Software Foundation. - -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: - - 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." - - If you have no Invariant Sections, write "with no Invariant Sections" -instead of saying which ones are invariant. If you have no Front-Cover -Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being -LIST"; likewise for Back-Cover Texts. - - 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. - - ---------- Footnotes ---------- - - (1) Any more details? - -AS Index -******** - -* Menu: - -* #: Comments. (line 1306) -* #APP: Preprocessing. (line 1268) -* #NO_APP: Preprocessing. (line 1268) -* '$a': ARM Mapping Symbols. - (line 4193) -* '$d': ARM Mapping Symbols. - (line 4199) -* '$t': ARM Mapping Symbols. - (line 4196) -* --: Command Line. (line 760) -* '--32' option, i386: i386-Options. (line 4220) -* '--32' option, x86-64: i386-Options. (line 4220) -* '--64' option, i386: i386-Options. (line 4220) -* '--64' option, x86-64: i386-Options. (line 4220) -* --alternate: alternate. (line 929) -* '--divide' option, i386: i386-Options. (line 4236) -* --enforce-aligned-data: Sparc-Aligned-Data. (line 5460) -* --fatal-warnings: W. (line 1222) -* --hash-size=NUMBER: Overview. (line 459) -* --listing-cont-lines: listing. (line 1015) -* --listing-lhs-width: listing. (line 997) -* --listing-lhs-width2: listing. (line 1002) -* --listing-rhs-width: listing. (line 1009) -* --MD: MD. (line 1149) -* --no-warn: W. (line 1217) -* --statistics: statistics. (line 1188) -* --traditional-format: traditional-format. (line 1196) -* --warn: W. (line 1225) -* -a: a. (line 894) -* -ac: a. (line 894) -* -ad: a. (line 894) -* -ah: a. (line 894) -* -al: a. (line 894) -* -an: a. (line 894) -* -as: a. (line 894) -* -Asparclet: Sparc-Opts. (line 5421) -* -Asparclite: Sparc-Opts. (line 5421) -* -Av6: Sparc-Opts. (line 5421) -* -Av8: Sparc-Opts. (line 5421) -* -Av9: Sparc-Opts. (line 5421) -* -Av9a: Sparc-Opts. (line 5421) -* -construct-floats: MIPS Opts. (line 5056) -* -D: D. (line 934) -* '-eabi=' command line option, ARM: ARM Options. (line 3844) -* '-EB' command line option, ARM: ARM Options. (line 3849) -* '-EB' option (MIPS): MIPS Opts. (line 4879) -* '-EL' command line option, ARM: ARM Options. (line 3853) -* '-EL' option (MIPS): MIPS Opts. (line 4879) -* -f: f. (line 940) -* '-G' option (MIPS): MIPS Opts. (line 4874) -* -I PATH: I. (line 952) -* -K: K. (line 962) -* '-k' command line option, ARM: ARM Options. (line 3857) -* '-KPIC' option, MIPS: MIPS Opts. (line 4887) -* -L: L. (line 972) -* -M: M. (line 1022) -* '-mapcs' command line option, ARM: ARM Options. (line 3817) -* '-mapcs-float' command line option, ARM: ARM Options. (line 3830) -* '-mapcs-reentrant' command line option, ARM: ARM Options. (line 3835) -* '-march=' command line option, ARM: ARM Options. (line 3773) -* '-march=' option, i386: i386-Options. (line 4243) -* '-march=' option, x86-64: i386-Options. (line 4243) -* '-matpcs' command line option, ARM: ARM Options. (line 3822) -* '-mconstant-gp' command line option, IA-64: IA-64 Options. (line 4733) -* '-mcpu=' command line option, ARM: ARM Options. (line 3742) -* '-mfloat-abi=' command line option, ARM: ARM Options. (line 3839) -* '-mfpu=' command line option, ARM: ARM Options. (line 3788) -* -mno-sym32: MIPS Opts. (line 5045) -* -msym32: MIPS Opts. (line 5045) -* '-mthumb' command line option, ARM: ARM Options. (line 3808) -* '-mthumb-interwork' command line option, ARM: ARM Options. (line 3813) -* '-mtune=' option, i386: i386-Options. (line 4255) -* '-mtune=' option, x86-64: i386-Options. (line 4255) -* '-mvxworks-pic' option, MIPS: MIPS Opts. (line 4892) -* -no-construct-floats: MIPS Opts. (line 5056) -* '-nocpp' ignored (MIPS): MIPS Opts. (line 5048) -* -o: o. (line 1160) -* -R: R. (line 1170) -* -v: v. (line 1206) -* -version: v. (line 1206) -* -W: W. (line 1217) -* '.' (symbol): Dot. (line 1898) -* '.arch' directive, ARM: ARM Directives. (line 4118) -* '.cantunwind' directive, ARM: ARM Directives. (line 4022) -* '.cpu' directive, ARM: ARM Directives. (line 4114) -* '.eabi_attribute' directive, ARM: ARM Directives. (line 4132) -* '.fnend' directive, ARM: ARM Directives. (line 4014) -* '.fnstart' directive, ARM: ARM Directives. (line 4011) -* '.fpu' directive, ARM: ARM Directives. (line 4128) -* '.handlerdata' directive, ARM: ARM Directives. (line 4033) -* '.insn': MIPS insn. (line 5223) -* '.ltorg' directive, ARM: ARM Directives. (line 3994) -* '.movsp' directive, ARM: ARM Directives. (line 4088) -* .o: Object. (line 827) -* '.object_arch' directive, ARM: ARM Directives. (line 4122) -* '.pad' directive, ARM: ARM Directives. (line 4083) -* '.personality' directive, ARM: ARM Directives. (line 4026) -* '.personalityindex' directive, ARM: ARM Directives. (line 4029) -* '.pool' directive, ARM: ARM Directives. (line 4008) -* '.save' directive, ARM: ARM Directives. (line 4042) -* '.set arch=CPU': MIPS ISA. (line 5195) -* '.set autoextend': MIPS autoextend. (line 5210) -* '.set dsp': MIPS ASE instruction generation overrides. - (line 5262) -* '.set dspr2': MIPS ASE instruction generation overrides. - (line 5267) -* '.set mdmx': MIPS ASE instruction generation overrides. - (line 5257) -* '.set mips3d': MIPS ASE instruction generation overrides. - (line 5247) -* '.set mipsN': MIPS ISA. (line 5183) -* '.set mt': MIPS ASE instruction generation overrides. - (line 5272) -* '.set noautoextend': MIPS autoextend. (line 5210) -* '.set nodsp': MIPS ASE instruction generation overrides. - (line 5262) -* '.set nodspr2': MIPS ASE instruction generation overrides. - (line 5267) -* '.set nomdmx': MIPS ASE instruction generation overrides. - (line 5257) -* '.set nomips3d': MIPS ASE instruction generation overrides. - (line 5247) -* '.set nomt': MIPS ASE instruction generation overrides. - (line 5272) -* '.set nosmartmips': MIPS ASE instruction generation overrides. - (line 5252) -* '.set nosym32': MIPS symbol sizes. (line 5140) -* '.set pop': MIPS option stack. (line 5232) -* '.set push': MIPS option stack. (line 5232) -* '.set smartmips': MIPS ASE instruction generation overrides. - (line 5252) -* '.set sym32': MIPS symbol sizes. (line 5140) -* '.setfp' directive, ARM: ARM Directives. (line 4093) -* '.unwind_raw' directive, ARM: ARM Directives. (line 4107) -* '.vsave' directive, ARM: ARM Directives. (line 4066) -* 16-bit code, i386: i386-16bit. (line 4615) -* 3DNow!, i386: i386-SIMD. (line 4593) -* 3DNow!, x86-64: i386-SIMD. (line 4593) -* ':' (label): Statements. (line 1355) -* '\"' (doublequote character): Strings. (line 1423) -* '\b' (backspace character): Strings. (line 1395) -* '\DDD' (octal character code): Strings. (line 1410) -* '\f' (formfeed character): Strings. (line 1398) -* '\n' (newline character): Strings. (line 1401) -* '\r' (carriage return character): Strings. (line 1404) -* '\t' (tab): Strings. (line 1407) -* '\XD...' (hex character code): Strings. (line 1416) -* '\\' ('\' character): Strings. (line 1420) -* a.out: Object. (line 827) -* 'abort' directive: Abort. (line 2114) -* absolute section: Ld Sections. (line 1632) -* addition, permitted arguments: Infix Ops. (line 2055) -* addresses: Expressions. (line 1946) -* addresses, format of: Secs Background. (line 1573) -* 'ADR reg,<label>' pseudo op, ARM: ARM Opcodes. (line 4159) -* 'ADRL reg,<label>' pseudo op, ARM: ARM Opcodes. (line 4169) -* advancing location counter: Org. (line 3101) -* 'align' directive: Align. (line 2123) -* 'align' directive, ARM: ARM Directives. (line 3915) -* 'align' directive, SPARC: Sparc-Directives. (line 5481) -* arch directive, i386: i386-Arch. (line 4670) -* arch directive, x86-64: i386-Arch. (line 4670) -* architectures, PowerPC: PowerPC-Opts. (line 5285) -* architectures, SPARC: Sparc-Opts. (line 5402) -* arguments for addition: Infix Ops. (line 2055) -* arguments for subtraction: Infix Ops. (line 2060) -* arguments in expressions: Arguments. (line 1973) -* arithmetic functions: Operators. (line 1998) -* arithmetic operands: Arguments. (line 1973) -* ARM data relocations: ARM-Relocations. (line 3886) -* 'arm' directive, ARM: ARM Directives. (line 3969) -* ARM floating point (IEEE): ARM Floating Point. (line 3910) -* ARM identifiers: ARM-Chars. (line 3876) -* ARM immediate character: ARM-Chars. (line 3874) -* ARM line comment character: ARM-Chars. (line 3867) -* ARM line separator: ARM-Chars. (line 3871) -* ARM machine directives: ARM Directives. (line 3915) -* ARM opcodes: ARM Opcodes. (line 4140) -* ARM options (none): ARM Options. (line 3742) -* ARM register names: ARM-Regs. (line 3881) -* ARM support: Machine Dependencies. - (line 3739) -* 'ascii' directive: Ascii. (line 2165) -* 'asciz' directive: Asciz. (line 2172) -* assembler bugs, reporting: Bug Reporting. (line 5566) -* assembler crash: Bug Criteria. (line 5550) -* assembler internal logic error: As Sections. (line 1674) -* assembler version: v. (line 1206) -* assembler, and linker: Secs Background. (line 1535) -* assembly listings, enabling: a. (line 894) -* assigning values to symbols: Setting Symbols. (line 1772) -* assigning values to symbols <1>: Equ. (line 2471) -* attributes, symbol: Symbol Attributes. (line 1907) -* att_syntax pseudo op, i386: i386-Syntax. (line 4265) -* att_syntax pseudo op, x86-64: i386-Syntax. (line 4265) -* Av7: Sparc-Opts. (line 5421) -* backslash ('\\'): Strings. (line 1420) -* backspace ('\b'): Strings. (line 1395) -* 'balign' directive: Balign. (line 2178) -* 'balignl' directive: Balign. (line 2199) -* 'balignw' directive: Balign. (line 2199) -* big endian output, MIPS: Overview. (line 560) -* big-endian output, MIPS: MIPS Opts. (line 4879) -* bignums: Bignums. (line 1485) -* binary files, including: Incbin. (line 2707) -* binary integers: Integers. (line 1466) -* bit names, IA-64: IA-64-Bits. (line 4846) -* bss section: Ld Sections. (line 1623) -* bss section <1>: bss. (line 1739) -* bug criteria: Bug Criteria. (line 5547) -* bug reports: Bug Reporting. (line 5566) -* bugs in assembler: Reporting Bugs. (line 5534) -* bus lock prefixes, i386: i386-Prefixes. (line 4444) -* 'byte' directive: Byte. (line 2211) -* call instructions, i386: i386-Mnemonics. (line 4353) -* call instructions, x86-64: i386-Mnemonics. (line 4353) -* carriage return ('\r'): Strings. (line 1404) -* 'cfi_endproc' directive: CFI directives. (line 2249) -* 'cfi_startproc' directive: CFI directives. (line 2239) -* character constants: Characters. (line 1377) -* character escape codes: Strings. (line 1395) -* character, single: Chars. (line 1443) -* characters used in symbols: Symbol Intro. (line 1325) -* 'code' directive, ARM: ARM Directives. (line 3962) -* 'code16' directive, i386: i386-16bit. (line 4615) -* 'code16gcc' directive, i386: i386-16bit. (line 4615) -* 'code32' directive, i386: i386-16bit. (line 4615) -* 'code64' directive, i386: i386-16bit. (line 4615) -* 'code64' directive, x86-64: i386-16bit. (line 4615) -* COMDAT: Linkonce. (line 2831) -* 'comm' directive: Comm. (line 2217) -* command line conventions: Command Line. (line 756) -* comments: Comments. (line 1288) -* comments, removed by preprocessor: Preprocessing. (line 1253) -* 'common' directive, SPARC: Sparc-Directives. (line 5484) -* common sections: Linkonce. (line 2831) -* common variable storage: bss. (line 1739) -* comparison expressions: Infix Ops. (line 2066) -* conditional assembly: If. (line 2629) -* constant, single character: Chars. (line 1443) -* constants: Constants. (line 1366) -* constants, bignum: Bignums. (line 1485) -* constants, character: Characters. (line 1377) -* constants, converted by preprocessor: Preprocessing. (line 1256) -* constants, floating point: Flonums. (line 1493) -* constants, integer: Integers. (line 1466) -* constants, number: Numbers. (line 1457) -* constants, string: Strings. (line 1386) -* conversion instructions, i386: i386-Mnemonics. (line 4334) -* conversion instructions, x86-64: i386-Mnemonics. (line 4334) -* coprocessor wait, i386: i386-Prefixes. (line 4448) -* crash of assembler: Bug Criteria. (line 5550) -* current address: Dot. (line 1898) -* current address, advancing: Org. (line 3101) -* data alignment on SPARC: Sparc-Aligned-Data. (line 5455) -* data and text sections, joining: R. (line 1170) -* 'data' directive: Data. (line 2421) -* data relocations, ARM: ARM-Relocations. (line 3886) -* debuggers, and symbol order: Symbols. (line 1757) -* decimal integers: Integers. (line 1472) -* dependency tracking: MD. (line 1149) -* deprecated directives: Deprecated. (line 3731) -* directives and instructions: Statements. (line 1347) -* directives for PowerPC: PowerPC-Pseudo. (line 5386) -* directives, machine independent: Pseudo Ops. (line 2105) -* 'dn' and 'qn' directives, ARM: ARM Directives. (line 3938) -* dollar local symbols: Symbol Names. (line 1879) -* dot (symbol): Dot. (line 1898) -* 'double' directive: Double. (line 2428) -* 'double' directive, i386: i386-Float. (line 4569) -* 'double' directive, x86-64: i386-Float. (line 4569) -* doublequote ('\"'): Strings. (line 1423) -* ECOFF sections: MIPS Object. (line 5100) -* eight-byte integer: Quad. (line 3245) -* 'eject' directive: Eject. (line 2434) -* ELF symbol type: Type. (line 3620) -* 'else' directive: Else. (line 2439) -* 'elseif' directive: Elseif. (line 2446) -* empty expressions: Empty Exprs. (line 1959) -* emulation: Overview. (line 663) -* 'end' directive: End. (line 2453) -* 'endfunc' directive: Endfunc. (line 2459) -* endianness, MIPS: Overview. (line 560) -* 'endif' directive: Endif. (line 2464) -* 'endm' directive: Macro. (line 3025) -* EOF, newline must precede: Statements. (line 1341) -* 'equ' directive: Equ. (line 2471) -* 'equiv' directive: Equiv. (line 2477) -* 'eqv' directive: Eqv. (line 2493) -* 'err' directive: Err. (line 2501) -* error directive: Error. (line 2509) -* error messages: Errors. (line 844) -* error on valid input: Bug Criteria. (line 5553) -* errors, caused by warnings: W. (line 1222) -* errors, continuing after: Z. (line 1231) -* escape codes, character: Strings. (line 1395) -* 'exitm' directive: Macro. (line 3028) -* expr (internal section): As Sections. (line 1678) -* expression arguments: Arguments. (line 1973) -* expressions: Expressions. (line 1946) -* expressions, comparison: Infix Ops. (line 2066) -* expressions, empty: Empty Exprs. (line 1959) -* expressions, integer: Integer Exprs. (line 1967) -* 'extern' directive: Extern. (line 2524) -* 'fail' directive: Fail. (line 2531) -* faster processing ('-f'): f. (line 940) -* fatal signal: Bug Criteria. (line 5550) -* 'file' directive: LNS directives. (line 2369) -* 'file' directive <1>: File. (line 2540) -* file name, logical: File. (line 2540) -* files, including: Include. (line 2721) -* files, input: Input Files. (line 780) -* 'fill' directive: Fill. (line 2550) -* filling memory: Skip. (line 3452) -* filling memory <1>: Space. (line 3459) -* 'float' directive: Float. (line 2568) -* 'float' directive, i386: i386-Float. (line 4569) -* 'float' directive, x86-64: i386-Float. (line 4569) -* floating point numbers: Flonums. (line 1493) -* floating point numbers (double): Double. (line 2428) -* floating point numbers (single): Float. (line 2568) -* floating point numbers (single) <1>: Single. (line 3425) -* floating point, ARM (IEEE): ARM Floating Point. (line 3910) -* floating point, i386: i386-Float. (line 4561) -* floating point, SPARC (IEEE): Sparc-Float. (line 5473) -* floating point, x86-64: i386-Float. (line 4561) -* flonums: Flonums. (line 1493) -* 'force_thumb' directive, ARM: ARM Directives. (line 3972) -* format of error messages: Errors. (line 861) -* format of warning messages: Errors. (line 850) -* formfeed ('\f'): Strings. (line 1398) -* 'func' directive: Func. (line 2574) -* functions, in expressions: Operators. (line 1998) -* 'global' directive: Global. (line 2585) -* 'gp' register, MIPS: MIPS Object. (line 5105) -* grouping data: Sub-Sections. (line 1686) -* 'half' directive, SPARC: Sparc-Directives. (line 5489) -* hex character code ('\XD...'): Strings. (line 1416) -* hexadecimal integers: Integers. (line 1475) -* 'hidden' directive: Hidden. (line 2597) -* 'hword' directive: hword. (line 2610) -* i386 16-bit code: i386-16bit. (line 4615) -* i386 arch directive: i386-Arch. (line 4670) -* i386 att_syntax pseudo op: i386-Syntax. (line 4265) -* i386 conversion instructions: i386-Mnemonics. (line 4334) -* i386 floating point: i386-Float. (line 4561) -* i386 immediate operands: i386-Syntax. (line 4274) -* i386 instruction naming: i386-Mnemonics. (line 4309) -* i386 instruction prefixes: i386-Prefixes. (line 4414) -* i386 intel_syntax pseudo op: i386-Syntax. (line 4265) -* i386 jump optimization: i386-Jumps. (line 4538) -* i386 jump, call, return: i386-Syntax. (line 4296) -* i386 jump/call operands: i386-Syntax. (line 4274) -* i386 memory references: i386-Memory. (line 4471) -* i386 'mul', 'imul' instructions: i386-Notes. (line 4714) -* i386 options: i386-Options. (line 4218) -* i386 register operands: i386-Syntax. (line 4274) -* i386 registers: i386-Regs. (line 4359) -* i386 sections: i386-Syntax. (line 4302) -* i386 size suffixes: i386-Syntax. (line 4287) -* i386 source, destination operands: i386-Syntax. (line 4280) -* i386 support: . (line 4211) -* i386 syntax compatibility: i386-Syntax. (line 4265) -* i80306 support: . (line 4211) -* IA-64 line comment character: IA-64-Chars. (line 4822) -* IA-64 line separator: IA-64-Chars. (line 4824) -* IA-64 options: IA-64 Options. (line 4733) -* IA-64 Processor-status-Register bit names: IA-64-Bits. (line 4846) -* IA-64 registers: IA-64-Regs. (line 4829) -* IA-64 support: . (line 4730) -* IA-64 Syntax: IA-64 Options. (line 4812) -* 'ident' directive: Ident. (line 2618) -* identifiers, ARM: ARM-Chars. (line 3876) -* 'if' directive: If. (line 2629) -* 'ifb' directive: If. (line 2644) -* 'ifc' directive: If. (line 2648) -* 'ifdef' directive: If. (line 2639) -* 'ifeq' directive: If. (line 2656) -* 'ifeqs' directive: If. (line 2659) -* 'ifge' directive: If. (line 2663) -* 'ifgt' directive: If. (line 2667) -* 'ifle' directive: If. (line 2671) -* 'iflt' directive: If. (line 2675) -* 'ifnb' directive: If. (line 2679) -* 'ifnc' directive: If. (line 2684) -* 'ifndef' directive: If. (line 2688) -* 'ifne' directive: If. (line 2695) -* 'ifnes' directive: If. (line 2699) -* 'ifnotdef' directive: If. (line 2688) -* immediate character, ARM: ARM-Chars. (line 3874) -* immediate operands, i386: i386-Syntax. (line 4274) -* immediate operands, x86-64: i386-Syntax. (line 4274) -* 'imul' instruction, i386: i386-Notes. (line 4714) -* 'imul' instruction, x86-64: i386-Notes. (line 4714) -* 'incbin' directive: Incbin. (line 2707) -* 'include' directive: Include. (line 2721) -* 'include' directive search path: I. (line 952) -* infix operators: Infix Ops. (line 2016) -* inhibiting interrupts, i386: i386-Prefixes. (line 4444) -* input: Input Files. (line 780) -* input file linenumbers: Input Files. (line 809) -* instruction naming, i386: i386-Mnemonics. (line 4309) -* instruction naming, x86-64: i386-Mnemonics. (line 4309) -* instruction prefixes, i386: i386-Prefixes. (line 4414) -* instructions and directives: Statements. (line 1347) -* 'int' directive: Int. (line 2732) -* 'int' directive, i386: i386-Float. (line 4576) -* 'int' directive, x86-64: i386-Float. (line 4576) -* integer expressions: Integer Exprs. (line 1967) -* integer, 16-byte: Octa. (line 3092) -* integer, 8-byte: Quad. (line 3245) -* integers: Integers. (line 1466) -* integers, 16-bit: hword. (line 2610) -* integers, 32-bit: Int. (line 2732) -* integers, binary: Integers. (line 1466) -* integers, decimal: Integers. (line 1472) -* integers, hexadecimal: Integers. (line 1475) -* integers, octal: Integers. (line 1469) -* integers, one byte: Byte. (line 2211) -* intel_syntax pseudo op, i386: i386-Syntax. (line 4265) -* intel_syntax pseudo op, x86-64: i386-Syntax. (line 4265) -* internal assembler sections: As Sections. (line 1667) -* 'internal' directive: Internal. (line 2740) -* invalid input: Bug Criteria. (line 5555) -* invocation summary: Overview. (line 249) -* 'irp' directive: Irp. (line 2754) -* 'irpc' directive: Irpc. (line 2779) -* joining text and data sections: R. (line 1170) -* jump instructions, i386: i386-Mnemonics. (line 4353) -* jump instructions, x86-64: i386-Mnemonics. (line 4353) -* jump optimization, i386: i386-Jumps. (line 4538) -* jump optimization, x86-64: i386-Jumps. (line 4538) -* jump/call operands, i386: i386-Syntax. (line 4274) -* jump/call operands, x86-64: i386-Syntax. (line 4274) -* label (':'): Statements. (line 1355) -* labels: Labels. (line 1763) -* 'lcomm' directive: Lcomm. (line 2805) -* ld: Object. (line 836) -* 'LDR reg,=<label>' pseudo op, ARM: ARM Opcodes. (line 4149) -* length of symbols: Symbol Intro. (line 1331) -* 'lflags' directive (ignored): Lflags. (line 2814) -* line comment character: Comments. (line 1301) -* line comment character, ARM: ARM-Chars. (line 3867) -* line comment character, IA-64: IA-64-Chars. (line 4822) -* 'line' directive: Line. (line 2820) -* line numbers, in input files: Input Files. (line 809) -* line numbers, in warnings/errors: Errors. (line 854) -* line separator character: Statements. (line 1336) -* line separator, ARM: ARM-Chars. (line 3871) -* line separator, IA-64: IA-64-Chars. (line 4824) -* lines starting with '#': Comments. (line 1306) -* linker: Object. (line 836) -* linker, and assembler: Secs Background. (line 1535) -* 'linkonce' directive: Linkonce. (line 2831) -* 'list' directive: List. (line 2876) -* listing control, turning off: Nolist. (line 3083) -* listing control, turning on: List. (line 2876) -* listing control: new page: Eject. (line 2434) -* listing control: paper size: Psize. (line 3208) -* listing control: subtitle: Sbttl. (line 3284) -* listing control: title line: Title. (line 3609) -* listings, enabling: a. (line 894) -* little endian output, MIPS: Overview. (line 563) -* little-endian output, MIPS: MIPS Opts. (line 4879) -* 'ln' directive: Ln. (line 2863) -* 'loc' directive: LNS directives. (line 2382) -* local common symbols: Lcomm. (line 2805) -* local labels: Symbol Names. (line 1810) -* local symbol names: Symbol Names. (line 1797) -* local symbols, retaining in output: L. (line 972) -* location counter: Dot. (line 1898) -* location counter, advancing: Org. (line 3101) -* 'loc_mark_blocks' directive: LNS directives. (line 2412) -* logical file name: File. (line 2540) -* logical line number: Line. (line 2820) -* logical line numbers: Comments. (line 1306) -* 'long' directive: Long. (line 2889) -* 'long' directive, i386: i386-Float. (line 4576) -* 'long' directive, x86-64: i386-Float. (line 4576) -* machine directives, ARM: ARM Directives. (line 3915) -* machine directives, SPARC: Sparc-Directives. (line 5478) -* machine independent directives: Pseudo Ops. (line 2105) -* machine instructions (not covered): Manual. (line 716) -* machine-independent syntax: Syntax. (line 1241) -* 'macro' directive: Macro. (line 2916) -* macros: Macro. (line 2894) -* macros, count executed: Macro. (line 3030) -* make rules: MD. (line 1149) -* manual, structure and purpose: Manual. (line 708) -* Maximum number of continuation lines: listing. (line 1015) -* memory references, i386: i386-Memory. (line 4471) -* memory references, x86-64: i386-Memory. (line 4471) -* merging text and data sections: R. (line 1170) -* messages from assembler: Errors. (line 844) -* minus, permitted arguments: Infix Ops. (line 2060) -* MIPS architecture options: MIPS Opts. (line 4895) -* MIPS big-endian output: MIPS Opts. (line 4879) -* MIPS CPU override: MIPS ISA. (line 5195) -* MIPS debugging directives: MIPS Stabs. (line 5128) -* MIPS DSP Release 1 instruction generation override: MIPS ASE instruction generation overrides. - (line 5262) -* MIPS DSP Release 2 instruction generation override: MIPS ASE instruction generation overrides. - (line 5267) -* MIPS ECOFF sections: MIPS Object. (line 5100) -* MIPS endianness: Overview. (line 560) -* MIPS ISA: Overview. (line 566) -* MIPS ISA override: MIPS ISA. (line 5183) -* MIPS little-endian output: MIPS Opts. (line 4879) -* MIPS MDMX instruction generation override: MIPS ASE instruction generation overrides. - (line 5257) -* MIPS MIPS-3D instruction generation override: MIPS ASE instruction generation overrides. - (line 5247) -* MIPS MT instruction generation override: MIPS ASE instruction generation overrides. - (line 5272) -* MIPS option stack: MIPS option stack. (line 5232) -* MIPS processor: . (line 4862) -* MMX, i386: i386-SIMD. (line 4593) -* MMX, x86-64: i386-SIMD. (line 4593) -* mnemonic suffixes, i386: i386-Syntax. (line 4287) -* mnemonic suffixes, x86-64: i386-Syntax. (line 4287) -* MOVW and MOVT relocations, ARM: ARM-Relocations. (line 3900) -* MRI compatibility mode: M. (line 1022) -* 'mri' directive: MRI. (line 2868) -* MRI mode, temporarily: MRI. (line 2868) -* 'mul' instruction, i386: i386-Notes. (line 4714) -* 'mul' instruction, x86-64: i386-Notes. (line 4714) -* named section: Section. (line 3293) -* named sections: Ld Sections. (line 1613) -* names, symbol: Symbol Names. (line 1781) -* naming object file: o. (line 1160) -* new page, in listings: Eject. (line 2434) -* newline ('\n'): Strings. (line 1401) -* newline, required at file end: Statements. (line 1341) -* 'nolist' directive: Nolist. (line 3083) -* 'NOP' pseudo op, ARM: ARM Opcodes. (line 4143) -* null-terminated strings: Asciz. (line 2172) -* number constants: Numbers. (line 1457) -* number of macros executed: Macro. (line 3030) -* numbered subsections: Sub-Sections. (line 1686) -* numbers, 16-bit: hword. (line 2610) -* numeric values: Expressions. (line 1946) -* 'nword' directive, SPARC: Sparc-Directives. (line 5492) -* object file: Object. (line 827) -* object file format: Object Formats. (line 746) -* object file name: o. (line 1160) -* object file, after errors: Z. (line 1231) -* obsolescent directives: Deprecated. (line 3731) -* 'octa' directive: Octa. (line 3092) -* octal character code ('\DDD'): Strings. (line 1410) -* octal integers: Integers. (line 1469) -* opcodes for ARM: ARM Opcodes. (line 4140) -* operand delimiters, i386: i386-Syntax. (line 4274) -* operand delimiters, x86-64: i386-Syntax. (line 4274) -* operands in expressions: Arguments. (line 1973) -* operator precedence: Infix Ops. (line 2021) -* operators, in expressions: Operators. (line 1998) -* operators, permitted arguments: Infix Ops. (line 2016) -* option summary: Overview. (line 249) -* options for ARM (none): ARM Options. (line 3742) -* options for i386: i386-Options. (line 4218) -* options for IA-64: IA-64 Options. (line 4733) -* options for PowerPC: PowerPC-Opts. (line 5285) -* options for SPARC: Sparc-Opts. (line 5402) -* options for x86-64: i386-Options. (line 4218) -* options, all versions of assembler: Invoking. (line 870) -* options, command line: Command Line. (line 763) -* 'org' directive: Org. (line 3101) -* output file: Object. (line 827) -* 'p2align' directive: P2align. (line 3127) -* 'p2alignl' directive: P2align. (line 3149) -* 'p2alignw' directive: P2align. (line 3149) -* padding the location counter: Align. (line 2123) -* padding the location counter given a power of two: P2align. - (line 3127) -* padding the location counter given number of bytes: Balign. - (line 2178) -* page, in listings: Eject. (line 2434) -* paper size, for listings: Psize. (line 3208) -* paths for '.include': I. (line 952) -* patterns, writing in memory: Fill. (line 2550) -* PIC code generation for ARM: ARM Options. (line 3857) -* PIC selection, MIPS: MIPS Opts. (line 4887) -* plus, permitted arguments: Infix Ops. (line 2055) -* 'popsection' directive: PopSection. (line 3177) -* PowerPC architectures: PowerPC-Opts. (line 5285) -* PowerPC directives: PowerPC-Pseudo. (line 5386) -* PowerPC options: PowerPC-Opts. (line 5285) -* PowerPC support: . (line 5282) -* precedence of operators: Infix Ops. (line 2021) -* precision, floating point: Flonums. (line 1493) -* prefix operators: Prefix Ops. (line 2005) -* prefixes, i386: i386-Prefixes. (line 4414) -* preprocessing: Preprocessing. (line 1248) -* preprocessing, turning on and off: Preprocessing. (line 1268) -* 'previous' directive: Previous. (line 3161) -* 'print' directive: Print. (line 3189) -* 'proc' directive, SPARC: Sparc-Directives. (line 5497) -* 'protected' directive: Protected. (line 3195) -* pseudo-ops, machine independent: Pseudo Ops. (line 2105) -* 'psize' directive: Psize. (line 3208) -* PSR bits: IA-64-Bits. (line 4846) -* 'purgem' directive: Purgem. (line 3224) -* purpose of GNU assembler: GNU Assembler. (line 734) -* 'pushsection' directive: PushSection. (line 3230) -* 'quad' directive: Quad. (line 3242) -* 'quad' directive, i386: i386-Float. (line 4576) -* 'quad' directive, x86-64: i386-Float. (line 4576) -* real-mode code, i386: i386-16bit. (line 4615) -* 'register' directive, SPARC: Sparc-Directives. (line 5501) -* register names, ARM: ARM-Regs. (line 3881) -* register names, IA-64: IA-64-Regs. (line 4829) -* register operands, i386: i386-Syntax. (line 4274) -* register operands, x86-64: i386-Syntax. (line 4274) -* registers, i386: i386-Regs. (line 4359) -* registers, x86-64: i386-Regs. (line 4359) -* 'reloc' directive: Reloc. (line 3253) -* relocation: Sections. (line 1528) -* relocation example: Ld Sections. (line 1643) -* repeat prefixes, i386: i386-Prefixes. (line 4452) -* reporting bugs in assembler: Reporting Bugs. (line 5534) -* 'rept' directive: Rept. (line 3266) -* 'req' directive, ARM: ARM Directives. (line 3922) -* 'reserve' directive, SPARC: Sparc-Directives. (line 5511) -* return instructions, i386: i386-Syntax. (line 4296) -* return instructions, x86-64: i386-Syntax. (line 4296) -* REX prefixes, i386: i386-Prefixes. (line 4454) -* 'sbttl' directive: Sbttl. (line 3284) -* search path for '.include': I. (line 952) -* 'section' directive (ELF version): Section. (line 3305) -* section override prefixes, i386: i386-Prefixes. (line 4431) -* Section Stack: Previous. (line 3161) -* Section Stack <1>: PopSection. (line 3177) -* Section Stack <2>: PushSection. (line 3230) -* Section Stack <3>: Section. (line 3300) -* Section Stack <4>: SubSection. (line 3545) -* section-relative addressing: Secs Background. (line 1573) -* sections: Sections. (line 1528) -* sections in messages, internal: As Sections. (line 1667) -* sections, i386: i386-Syntax. (line 4302) -* sections, named: Ld Sections. (line 1613) -* sections, x86-64: i386-Syntax. (line 4302) -* 'seg' directive, SPARC: Sparc-Directives. (line 5516) -* 'set' directive: Set. (line 3407) -* 'short' directive: Short. (line 3419) -* SIMD, i386: i386-SIMD. (line 4593) -* SIMD, x86-64: i386-SIMD. (line 4593) -* single character constant: Chars. (line 1443) -* 'single' directive: Single. (line 3425) -* 'single' directive, i386: i386-Float. (line 4569) -* 'single' directive, x86-64: i386-Float. (line 4569) -* sixteen bit integers: hword. (line 2610) -* sixteen byte integer: Octa. (line 3092) -* 'size' directive (ELF version): Size. (line 3433) -* size prefixes, i386: i386-Prefixes. (line 4435) -* sizes operands, i386: i386-Syntax. (line 4287) -* sizes operands, x86-64: i386-Syntax. (line 4287) -* 'skip' directive: Skip. (line 3452) -* 'skip' directive, SPARC: Sparc-Directives. (line 5520) -* 'sleb128' directive: Sleb128. (line 3445) -* small objects, MIPS ECOFF: MIPS Object. (line 5105) -* SmartMIPS instruction generation override: MIPS ASE instruction generation overrides. - (line 5252) -* source program: Input Files. (line 780) -* source, destination operands; i386: i386-Syntax. (line 4280) -* source, destination operands; x86-64: i386-Syntax. (line 4280) -* 'space' directive: Space. (line 3459) -* space used, maximum for assembly: statistics. (line 1188) -* SPARC architectures: Sparc-Opts. (line 5402) -* SPARC data alignment: Sparc-Aligned-Data. (line 5455) -* SPARC floating point (IEEE): Sparc-Float. (line 5473) -* SPARC machine directives: Sparc-Directives. (line 5478) -* SPARC options: Sparc-Opts. (line 5402) -* SPARC support: . (line 5399) -* 'stabd' directive: Stab. (line 3498) -* 'stabn' directive: Stab. (line 3509) -* 'stabs' directive: Stab. (line 3512) -* 'stabX' directives: Stab. (line 3466) -* standard assembler sections: Secs Background. (line 1550) -* standard input, as input file: Command Line. (line 760) -* statement separator character: Statements. (line 1336) -* statement separator, ARM: ARM-Chars. (line 3871) -* statement separator, IA-64: IA-64-Chars. (line 4824) -* statements, structure of: Statements. (line 1336) -* statistics, about assembly: statistics. (line 1188) -* stopping the assembly: Abort. (line 2114) -* string constants: Strings. (line 1386) -* 'string' directive: String. (line 3518) -* string literals: Ascii. (line 2165) -* string, copying to object file: String. (line 3518) -* 'struct' directive: Struct. (line 3527) -* subexpressions: Arguments. (line 1991) -* 'subsection' directive: SubSection. (line 3545) -* subtitles for listings: Sbttl. (line 3284) -* subtraction, permitted arguments: Infix Ops. (line 2060) -* summary of options: Overview. (line 249) -* supporting files, including: Include. (line 2721) -* suppressing warnings: W. (line 1217) -* symbol attributes: Symbol Attributes. (line 1907) -* symbol names: Symbol Names. (line 1781) -* symbol names, local: Symbol Names. (line 1797) -* symbol names, temporary: Symbol Names. (line 1810) -* symbol type: Symbol Type. (line 1938) -* symbol type, ELF: Type. (line 3620) -* symbol value: Symbol Value. (line 1918) -* symbol value, setting: Set. (line 3407) -* symbol values, assigning: Setting Symbols. (line 1772) -* symbol versioning: Symver. (line 3557) -* symbol, common: Comm. (line 2217) -* symbol, making visible to linker: Global. (line 2585) -* symbolic debuggers, information for: Stab. (line 3466) -* symbols: Symbols. (line 1753) -* symbols, assigning values to: Equ. (line 2471) -* symbols, local common: Lcomm. (line 2805) -* 'symver' directive: Symver. (line 3557) -* syntax compatibility, i386: i386-Syntax. (line 4265) -* syntax compatibility, x86-64: i386-Syntax. (line 4265) -* syntax, machine-independent: Syntax. (line 1241) -* tab ('\t'): Strings. (line 1407) -* temporary symbol names: Symbol Names. (line 1810) -* text and data sections, joining: R. (line 1170) -* 'text' directive: Text. (line 3602) -* 'tfloat' directive, i386: i386-Float. (line 4569) -* 'tfloat' directive, x86-64: i386-Float. (line 4569) -* 'thumb' directive, ARM: ARM Directives. (line 3966) -* Thumb support: Machine Dependencies. - (line 3739) -* 'thumb_func' directive, ARM: ARM Directives. (line 3976) -* 'thumb_set' directive, ARM: ARM Directives. (line 3987) -* time, total for assembly: statistics. (line 1188) -* 'title' directive: Title. (line 3609) -* trusted compiler: f. (line 940) -* turning preprocessing on and off: Preprocessing. (line 1268) -* 'type' directive (ELF version): Type. (line 3620) -* type of a symbol: Symbol Type. (line 1938) -* 'uleb128' directive: Uleb128. (line 3656) -* undefined section: Ld Sections. (line 1639) -* 'unreq' directive, ARM: ARM Directives. (line 3927) -* value of a symbol: Symbol Value. (line 1918) -* 'version' directive: Version. (line 3663) -* version of assembler: v. (line 1206) -* versions of symbols: Symver. (line 3557) -* visibility: Hidden. (line 2597) -* visibility <1>: Internal. (line 2740) -* visibility <2>: Protected. (line 3195) -* 'vtable_entry' directive: VTableEntry. (line 3669) -* 'vtable_inherit' directive: VTableInherit. (line 3675) -* warning directive: Warning. (line 3683) -* warning messages: Errors. (line 844) -* warnings, causing error: W. (line 1222) -* warnings, suppressing: W. (line 1217) -* warnings, switching on: W. (line 1225) -* 'weak' directive: Weak. (line 3689) -* 'weakref' directive: Weakref. (line 3705) -* whitespace: Whitespace. (line 1280) -* whitespace, removed by preprocessor: Preprocessing. (line 1249) -* Width of continuation lines of disassembly output: listing. - (line 1002) -* Width of first line disassembly output: listing. (line 997) -* Width of source line output: listing. (line 1009) -* 'word' directive: Word. (line 3725) -* 'word' directive, i386: i386-Float. (line 4576) -* 'word' directive, SPARC: Sparc-Directives. (line 5523) -* 'word' directive, x86-64: i386-Float. (line 4576) -* writing patterns in memory: Fill. (line 2550) -* x86-64 arch directive: i386-Arch. (line 4670) -* x86-64 att_syntax pseudo op: i386-Syntax. (line 4265) -* x86-64 conversion instructions: i386-Mnemonics. (line 4334) -* x86-64 floating point: i386-Float. (line 4561) -* x86-64 immediate operands: i386-Syntax. (line 4274) -* x86-64 instruction naming: i386-Mnemonics. (line 4309) -* x86-64 intel_syntax pseudo op: i386-Syntax. (line 4265) -* x86-64 jump optimization: i386-Jumps. (line 4538) -* x86-64 jump, call, return: i386-Syntax. (line 4296) -* x86-64 jump/call operands: i386-Syntax. (line 4274) -* x86-64 memory references: i386-Memory. (line 4471) -* x86-64 options: i386-Options. (line 4218) -* x86-64 register operands: i386-Syntax. (line 4274) -* x86-64 registers: i386-Regs. (line 4359) -* x86-64 sections: i386-Syntax. (line 4302) -* x86-64 size suffixes: i386-Syntax. (line 4287) -* x86-64 source, destination operands: i386-Syntax. (line 4280) -* x86-64 support: . (line 4211) -* x86-64 syntax compatibility: i386-Syntax. (line 4265) -* 'xword' directive, SPARC: Sparc-Directives. (line 5527) -* zero-terminated strings: Asciz. (line 2172) - diff --git a/contrib/binutils/ld/ld.7 b/contrib/binutils/ld/ld.7 new file mode 100644 index 000000000000..8ac5573b75c2 --- /dev/null +++ b/contrib/binutils/ld/ld.7 @@ -0,0 +1,7819 @@ +.Dd 2015-03-02 +.Dt LD 7 +.Os +.Sh NAME +.Nm ld +.Nd The GNU Linker +.Sh LD +This file documents the GNU linker ld version "2.17.50 [FreeBSD] 2007-07-03". +.Pp +This document is distributed under the terms of the GNU Free Documentation +License. A copy of the license is included in the section entitled \(lqGNU Free +Documentation License\(rq. +.Pp +.Sh Overview +.Xr ld +combines a number of object and archive files, relocates their data and ties +up symbol references. Usually the last step in compiling a program is to run +.Xr ld . +.Pp +.Xr ld +accepts Linker Command Language files written in a superset of AT&T's Link +Editor Command Language syntax, to provide explicit and total control over +the linking process. +.Pp +This version of +.Xr ld +uses the general purpose BFD libraries to operate on object files. This allows +.Xr ld +to read, combine, and write object files in many different formats---for example, +COFF or +.Li a.out . +Different formats may be linked together to produce any available kind of +object file.See Section +.Dq BFD , +for more information. +.Pp +Aside from its flexibility, the GNU linker is more helpful than other linkers +in providing diagnostic information. Many linkers abandon execution immediately +upon encountering an error; whenever possible, +.Xr ld +continues executing, allowing you to identify other errors (or, in some cases, +to get an output file in spite of the error). +.Pp +.Sh Invocation +The GNU linker +.Xr ld +is meant to cover a broad range of situations, and to be as compatible as +possible with other linkers. As a result, you have many choices to control +its behavior. +.Pp +.Ss Command Line Options +The linker supports a plethora of command-line options, but in actual practice +few of them are used in any particular context. For instance, a frequent use +of +.Xr ld +is to link standard Unix object files on a standard, supported Unix system. +On such a system, to link a file +.Li hello.o : +.Pp +.Bd -literal -offset indent +ld -o output /lib/crt0.o hello.o -lc +.Ed +.Pp +This tells +.Xr ld +to produce a file called +.Va output +as the result of linking the file +.Li /lib/crt0.o +with +.Li hello.o +and the library +.Li libc.a , +which will come from the standard search directories. (See the discussion +of the +.Li -l +option below.) +.Pp +Some of the command-line options to +.Xr ld +may be specified at any point in the command line. However, options which +refer to files, such as +.Li -l +or +.Li -T , +cause the file to be read at the point at which the option appears in the +command line, relative to the object files and other file options. Repeating +non-file options with a different argument will either have no further effect, +or override prior occurrences (those further to the left on the command line) +of that option. Options which may be meaningfully specified more than once +are noted in the descriptions below. +.Pp +Non-option arguments are object files or archives which are to be linked together. +They may follow, precede, or be mixed in with command-line options, except +that an object file argument may not be placed between an option and its argument. +.Pp +Usually the linker is invoked with at least one object file, but you can specify +other forms of binary input files using +.Li -l , +.Li -R , +and the script command language. If +.Em no +binary input files at all are specified, the linker does not produce any output, +and issues the message +.Li No input files . +.Pp +If the linker cannot recognize the format of an object file, it will assume +that it is a linker script. A script specified in this way augments the main +linker script used for the link (either the default linker script or the one +specified by using +.Li -T ) . +This feature permits the linker to link against a file which appears to be +an object or an archive, but actually merely defines some symbol values, or +uses +.Li INPUT +or +.Li GROUP +to load other objects. Note that specifying a script in this way merely augments +the main linker script; use the +.Li -T +option to replace the default linker script entirely.See Section +.Dq Scripts . +.Pp +For options whose names are a single letter, option arguments must either +follow the option letter without intervening whitespace, or be given as separate +arguments immediately following the option that requires them. +.Pp +For options whose names are multiple letters, either one dash or two can precede +the option name; for example, +.Li -trace-symbol +and +.Li --trace-symbol +are equivalent. Note---there is one exception to this rule. Multiple letter +options that start with a lower case 'o' can only be preceded by two dashes. +This is to reduce confusion with the +.Li -o +option. So for example +.Li -omagic +sets the output file name to +.Li magic +whereas +.Li --omagic +sets the NMAGIC flag on the output. +.Pp +Arguments to multiple-letter options must either be separated from the option +name by an equals sign, or be given as separate arguments immediately following +the option that requires them. For example, +.Li --trace-symbol foo +and +.Li --trace-symbol=foo +are equivalent. Unique abbreviations of the names of multiple-letter options +are accepted. +.Pp +Note---if the linker is being invoked indirectly, via a compiler driver (e.g. +.Li gcc ) +then all the linker command line options should be prefixed by +.Li -Wl, +(or whatever is appropriate for the particular compiler driver) like this: +.Pp +.Bd -literal -offset indent + gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup +.Ed +.Pp +This is important, because otherwise the compiler driver program may silently +drop the linker options, resulting in a bad link. +.Pp +Here is a table of the generic command line switches accepted by the GNU linker: +.Pp +.Bl -tag -width Ds +.It @ Va file +Read command-line options from +.Va file . +The options read are inserted in place of the original @ +.Va file +option. If +.Va file +does not exist, or cannot be read, then the option will be treated literally, +and not removed. +.Pp +Options in +.Va file +are separated by whitespace. A whitespace character may be included in an +option by surrounding the entire option in either single or double quotes. +Any character (including a backslash) may be included by prefixing the character +to be included with a backslash. The +.Va file +may itself contain additional @ +.Va file +options; any such options will be processed recursively. +.Pp +.It -a Va keyword +This option is supported for HP/UX compatibility. The +.Va keyword +argument must be one of the strings +.Li archive , +.Li shared , +or +.Li default . +.Li -aarchive +is functionally equivalent to +.Li -Bstatic , +and the other two keywords are functionally equivalent to +.Li -Bdynamic . +This option may be used any number of times. +.Pp +.It -A Va architecture +.It --architecture= Va architecture +In the current release of +.Xr ld , +this option is useful only for the Intel 960 family of architectures. In that +.Xr ld +configuration, the +.Va architecture +argument identifies the particular architecture in the 960 family, enabling +some safeguards and modifying the archive-library search path.See Section +.Dq i960 , +for details. +.Pp +Future releases of +.Xr ld +may support similar functionality for other architecture families. +.Pp +.It -b Va input-format +.It --format= Va input-format +.Xr ld +may be configured to support more than one kind of object file. If your +.Xr ld +is configured this way, you can use the +.Li -b +option to specify the binary format for input object files that follow this +option on the command line. Even when +.Xr ld +is configured to support alternative object formats, you don't usually need +to specify this, as +.Xr ld +should be configured to expect as a default input format the most usual format +on each machine. +.Va input-format +is a text string, the name of a particular format supported by the BFD libraries. +(You can list the available binary formats with +.Li objdump -i . ) +See Section.Dq BFD . +.Pp +You may want to use this option if you are linking files with an unusual binary +format. You can also use +.Li -b +to switch formats explicitly (when linking object files of different formats), +by including +.Li -b Va input-format +before each group of object files in a particular format. +.Pp +The default format is taken from the environment variable +.Li GNUTARGET . +See Section.Dq Environment . +You can also define the input format from a script, using the command +.Li TARGET ; +see Format Commands. +.Pp +.It -c Va MRI-commandfile +.It --mri-script= Va MRI-commandfile +For compatibility with linkers produced by MRI, +.Xr ld +accepts script files written in an alternate, restricted command language, +described in MRI,,MRI Compatible Script Files. Introduce MRI script files +with the option +.Li -c ; +use the +.Li -T +option to run linker scripts written in the general-purpose +.Xr ld +scripting language. If +.Va MRI-cmdfile +does not exist, +.Xr ld +looks for it in the directories specified by any +.Li -L +options. +.Pp +.It -d +.It -dc +.It -dp +These three options are equivalent; multiple forms are supported for compatibility +with other linkers. They assign space to common symbols even if a relocatable +output file is specified (with +.Li -r ) . +The script command +.Li FORCE_COMMON_ALLOCATION +has the same effect.See Section +.Dq Miscellaneous Commands . +.Pp +.It -e Va entry +.It --entry= Va entry +Use +.Va entry +as the explicit symbol for beginning execution of your program, rather than +the default entry point. If there is no symbol named +.Va entry , +the linker will try to parse +.Va entry +as a number, and use that as the entry address (the number will be interpreted +in base 10; you may use a leading +.Li 0x +for base 16, or a leading +.Li 0 +for base 8).See Section +.Dq Entry Point , +for a discussion of defaults and other ways of specifying the entry point. +.Pp +.It --exclude-libs Va lib, Va lib,... +Specifies a list of archive libraries from which symbols should not be automatically +exported. The library names may be delimited by commas or colons. Specifying +.Li --exclude-libs ALL +excludes symbols in all archive libraries from automatic export. This option +is available only for the i386 PE targeted port of the linker and for ELF +targeted ports. For i386 PE, symbols explicitly listed in a .def file are +still exported, regardless of this option. For ELF targeted ports, symbols +affected by this option will be treated as hidden. +.Pp +.It -E +.It --export-dynamic +When creating a dynamically linked executable, add all symbols to the dynamic +symbol table. The dynamic symbol table is the set of symbols which are visible +from dynamic objects at run time. +.Pp +If you do not use this option, the dynamic symbol table will normally contain +only those symbols which are referenced by some dynamic object mentioned in +the link. +.Pp +If you use +.Li dlopen +to load a dynamic object which needs to refer back to the symbols defined +by the program, rather than some other dynamic object, then you will probably +need to use this option when linking the program itself. +.Pp +You can also use the dynamic list to control what symbols should be added +to the dynamic symbol table if the output format supports it. See the description +of +.Li --dynamic-list . +.Pp +.It -EB +Link big-endian objects. This affects the default output format. +.Pp +.It -EL +Link little-endian objects. This affects the default output format. +.Pp +.It -f +.It --auxiliary Va name +When creating an ELF shared object, set the internal DT_AUXILIARY field to +the specified name. This tells the dynamic linker that the symbol table of +the shared object should be used as an auxiliary filter on the symbol table +of the shared object +.Va name . +.Pp +If you later link a program against this filter object, then, when you run +the program, the dynamic linker will see the DT_AUXILIARY field. If the dynamic +linker resolves any symbols from the filter object, it will first check whether +there is a definition in the shared object +.Va name . +If there is one, it will be used instead of the definition in the filter object. +The shared object +.Va name +need not exist. Thus the shared object +.Va name +may be used to provide an alternative implementation of certain functions, +perhaps for debugging or for machine specific performance. +.Pp +This option may be specified more than once. The DT_AUXILIARY entries will +be created in the order in which they appear on the command line. +.Pp +.It -F Va name +.It --filter Va name +When creating an ELF shared object, set the internal DT_FILTER field to the +specified name. This tells the dynamic linker that the symbol table of the +shared object which is being created should be used as a filter on the symbol +table of the shared object +.Va name . +.Pp +If you later link a program against this filter object, then, when you run +the program, the dynamic linker will see the DT_FILTER field. The dynamic +linker will resolve symbols according to the symbol table of the filter object +as usual, but it will actually link to the definitions found in the shared +object +.Va name . +Thus the filter object can be used to select a subset of the symbols provided +by the object +.Va name . +.Pp +Some older linkers used the +.Op -F +option throughout a compilation toolchain for specifying object-file format +for both input and output object files. The GNU linker uses other mechanisms +for this purpose: the +.Op -b , +.Op --format , +.Op --oformat +options, the +.Li TARGET +command in linker scripts, and the +.Li GNUTARGET +environment variable. The GNU linker will ignore the +.Op -F +option when not creating an ELF shared object. +.Pp +.It -fini Va name +When creating an ELF executable or shared object, call NAME when the executable +or shared object is unloaded, by setting DT_FINI to the address of the function. +By default, the linker uses +.Li _fini +as the function to call. +.Pp +.It -g +Ignored. Provided for compatibility with other tools. +.Pp +.It -G Va value +.It --gpsize= Va value +Set the maximum size of objects to be optimized using the GP register to +.Va size . +This is only meaningful for object file formats such as MIPS ECOFF which supports +putting large and small objects into different sections. This is ignored for +other object file formats. +.Pp +.It -h Va name +.It -soname= Va name +When creating an ELF shared object, set the internal DT_SONAME field to the +specified name. When an executable is linked with a shared object which has +a DT_SONAME field, then when the executable is run the dynamic linker will +attempt to load the shared object specified by the DT_SONAME field rather +than the using the file name given to the linker. +.Pp +.It -i +Perform an incremental link (same as option +.Li -r ) . +.Pp +.It -init Va name +When creating an ELF executable or shared object, call NAME when the executable +or shared object is loaded, by setting DT_INIT to the address of the function. +By default, the linker uses +.Li _init +as the function to call. +.Pp +.It -l Va namespec +.It --library= Va namespec +Add the archive or object file specified by +.Va namespec +to the list of files to link. This option may be used any number of times. +If +.Va namespec +is of the form +.Pa : Va filename , +.Xr ld +will search the library path for a file called +.Va filename , +otherise it will search the library path for a file called +.Pa lib Va namespec.a . +.Pp +On systems which support shared libraries, +.Xr ld +may also search for files other than +.Pa lib Va namespec.a . +Specifically, on ELF and SunOS systems, +.Xr ld +will search a directory for a library called +.Pa lib Va namespec.so +before searching for one called +.Pa lib Va namespec.a . +(By convention, a +.Li .so +extension indicates a shared library.) Note that this behavior does not apply +to +.Pa : Va filename , +which always specifies a file called +.Va filename . +.Pp +The linker will search an archive only once, at the location where it is specified +on the command line. If the archive defines a symbol which was undefined in +some object which appeared before the archive on the command line, the linker +will include the appropriate file(s) from the archive. However, an undefined +symbol in an object appearing later on the command line will not cause the +linker to search the archive again. +.Pp +See the +.Op -( +option for a way to force the linker to search archives multiple times. +.Pp +You may list the same archive multiple times on the command line. +.Pp +This type of archive searching is standard for Unix linkers. However, if you +are using +.Xr ld +on AIX, note that it is different from the behaviour of the AIX linker. +.Pp +.It -L Va searchdir +.It --library-path= Va searchdir +Add path +.Va searchdir +to the list of paths that +.Xr ld +will search for archive libraries and +.Xr ld +control scripts. You may use this option any number of times. The directories +are searched in the order in which they are specified on the command line. +Directories specified on the command line are searched before the default +directories. All +.Op -L +options apply to all +.Op -l +options, regardless of the order in which the options appear. +.Pp +If +.Va searchdir +begins with +.Li = , +then the +.Li = +will be replaced by the +.Em sysroot prefix , +a path specified when the linker is configured. +.Pp +The default set of paths searched (without being specified with +.Li -L ) +depends on which emulation mode +.Xr ld +is using, and in some cases also on how it was configured.See Section +.Dq Environment . +.Pp +The paths can also be specified in a link script with the +.Li SEARCH_DIR +command. Directories specified this way are searched at the point in which +the linker script appears in the command line. +.Pp +.It -m Va emulation +Emulate the +.Va emulation +linker. You can list the available emulations with the +.Li --verbose +or +.Li -V +options. +.Pp +If the +.Li -m +option is not used, the emulation is taken from the +.Li LDEMULATION +environment variable, if that is defined. +.Pp +Otherwise, the default emulation depends upon how the linker was configured. +.Pp +.It -M +.It --print-map +Print a link map to the standard output. A link map provides information about +the link, including the following: +.Pp +.Bl -bullet +.It +Where object files are mapped into memory. +.It +How common symbols are allocated. +.It +All archive members included in the link, with a mention of the symbol which +caused the archive member to be brought in. +.It +The values assigned to symbols. +.Pp +Note - symbols whose values are computed by an expression which involves a +reference to a previous value of the same symbol may not have correct result +displayed in the link map. This is because the linker discards intermediate +results and only retains the final value of an expression. Under such circumstances +the linker will display the final value enclosed by square brackets. Thus +for example a linker script containing: +.Pp +.Bd -literal -offset indent + foo = 1 + foo = foo * 4 + foo = foo + 8 +.Ed +.Pp +will produce the following output in the link map if the +.Op -M +option is used: +.Pp +.Bd -literal -offset indent + 0x00000001 foo = 0x1 + [0x0000000c] foo = (foo * 0x4) + [0x0000000c] foo = (foo + 0x8) +.Ed +.Pp +See Expressions for more information about expressions in linker scripts. +.El +.Pp +.It -n +.It --nmagic +Turn off page alignment of sections, and mark the output as +.Li NMAGIC +if possible. +.Pp +.It -N +.It --omagic +Set the text and data sections to be readable and writable. Also, do not page-align +the data segment, and disable linking against shared libraries. If the output +format supports Unix style magic numbers, mark the output as +.Li OMAGIC . +Note: Although a writable text section is allowed for PE-COFF targets, it +does not conform to the format specification published by Microsoft. +.Pp +.It --no-omagic +This option negates most of the effects of the +.Op -N +option. It sets the text section to be read-only, and forces the data segment +to be page-aligned. Note - this option does not enable linking against shared +libraries. Use +.Op -Bdynamic +for this. +.Pp +.It -o Va output +.It --output= Va output +Use +.Va output +as the name for the program produced by +.Xr ld ; +if this option is not specified, the name +.Pa a.out +is used by default. The script command +.Li OUTPUT +can also specify the output file name. +.Pp +.It -O Va level +If +.Va level +is a numeric values greater than zero +.Xr ld +optimizes the output. This might take significantly longer and therefore probably +should only be enabled for the final binary. +.Pp +.It -q +.It --emit-relocs +Leave relocation sections and contents in fully linked executables. Post link +analysis and optimization tools may need this information in order to perform +correct modifications of executables. This results in larger executables. +.Pp +This option is currently only supported on ELF platforms. +.Pp +.It --force-dynamic +Force the output file to have dynamic sections. This option is specific to +VxWorks targets. +.Pp +.It -r +.It --relocatable +Generate relocatable output---i.e., generate an output file that can in turn +serve as input to +.Xr ld . +This is often called +.Em partial linking . +As a side effect, in environments that support standard Unix magic numbers, +this option also sets the output file's magic number to +.Li OMAGIC . +If this option is not specified, an absolute file is produced. When linking +C++ programs, this option +.Em will not +resolve references to constructors; to do that, use +.Li -Ur . +.Pp +When an input file does not have the same format as the output file, partial +linking is only supported if that input file does not contain any relocations. +Different output formats can have further restrictions; for example some +.Li a.out +-based formats do not support partial linking with input files in other formats +at all. +.Pp +This option does the same thing as +.Li -i . +.Pp +.It -R Va filename +.It --just-symbols= Va filename +Read symbol names and their addresses from +.Va filename , +but do not relocate it or include it in the output. This allows your output +file to refer symbolically to absolute locations of memory defined in other +programs. You may use this option more than once. +.Pp +For compatibility with other ELF linkers, if the +.Op -R +option is followed by a directory name, rather than a file name, it is treated +as the +.Op -rpath +option. +.Pp +.It -s +.It --strip-all +Omit all symbol information from the output file. +.Pp +.It -S +.It --strip-debug +Omit debugger symbol information (but not all symbols) from the output file. +.Pp +.It -t +.It --trace +Print the names of the input files as +.Xr ld +processes them. +.Pp +.It -T Va scriptfile +.It --script= Va scriptfile +Use +.Va scriptfile +as the linker script. This script replaces +.Xr ld +\&'s default linker script (rather than adding to it), so +.Va commandfile +must specify everything necessary to describe the output file.See Section +.Dq Scripts . +If +.Va scriptfile +does not exist in the current directory, +.Li ld +looks for it in the directories specified by any preceding +.Li -L +options. Multiple +.Li -T +options accumulate. +.Pp +.It -dT Va scriptfile +.It --default-script= Va scriptfile +Use +.Va scriptfile +as the default linker script.See Section +.Dq Scripts . +.Pp +This option is similar to the +.Op --script +option except that processing of the script is delayed until after the rest +of the command line has been processed. This allows options placed after the +.Op --default-script +option on the command line to affect the behaviour of the linker script, which +can be important when the linker command line cannot be directly controlled +by the user. (eg because the command line is being constructed by another +tool, such as +.Li gcc ) . +.Pp +.It -u Va symbol +.It --undefined= Va symbol +Force +.Va symbol +to be entered in the output file as an undefined symbol. Doing this may, for +example, trigger linking of additional modules from standard libraries. +.Li -u +may be repeated with different option arguments to enter additional undefined +symbols. This option is equivalent to the +.Li EXTERN +linker script command. +.Pp +.It -Ur +For anything other than C++ programs, this option is equivalent to +.Li -r : +it generates relocatable output---i.e., an output file that can in turn serve +as input to +.Xr ld . +When linking C++ programs, +.Li -Ur +.Em does +resolve references to constructors, unlike +.Li -r . +It does not work to use +.Li -Ur +on files that were themselves linked with +.Li -Ur ; +once the constructor table has been built, it cannot be added to. Use +.Li -Ur +only for the last partial link, and +.Li -r +for the others. +.Pp +.It --unique[= Va SECTION] +Creates a separate output section for every input section matching +.Va SECTION , +or if the optional wildcard +.Va SECTION +argument is missing, for every orphan input section. An orphan section is +one not specifically mentioned in a linker script. You may use this option +multiple times on the command line; It prevents the normal merging of input +sections with the same name, overriding output section assignments in a linker +script. +.Pp +.It -v +.It --version +.It -V +Display the version number for +.Xr ld . +The +.Op -V +option also lists the supported emulations. +.Pp +.It -x +.It --discard-all +Delete all local symbols. +.Pp +.It -X +.It --discard-locals +Delete all temporary local symbols. (These symbols start with system-specific +local label prefixes, typically +.Li .L +for ELF systems or +.Li L +for traditional a.out systems.) +.Pp +.It -y Va symbol +.It --trace-symbol= Va symbol +Print the name of each linked file in which +.Va symbol +appears. This option may be given any number of times. On many systems it +is necessary to prepend an underscore. +.Pp +This option is useful when you have an undefined symbol in your link but don't +know where the reference is coming from. +.Pp +.It -Y Va path +Add +.Va path +to the default library search path. This option exists for Solaris compatibility. +.Pp +.It -z Va keyword +The recognized keywords are: +.Bl -tag -width Ds +.It combreloc +Combines multiple reloc sections and sorts them to make dynamic symbol lookup +caching possible. +.Pp +.It defs +Disallows undefined symbols in object files. Undefined symbols in shared libraries +are still allowed. +.Pp +.It execstack +Marks the object as requiring executable stack. +.Pp +.It initfirst +This option is only meaningful when building a shared object. It marks the +object so that its runtime initialization will occur before the runtime initialization +of any other objects brought into the process at the same time. Similarly +the runtime finalization of the object will occur after the runtime finalization +of any other objects. +.Pp +.It interpose +Marks the object that its symbol table interposes before all symbols but the +primary executable. +.Pp +.It lazy +When generating an executable or shared library, mark it to tell the dynamic +linker to defer function call resolution to the point when the function is +called (lazy binding), rather than at load time. Lazy binding is the default. +.Pp +.It loadfltr +Marks the object that its filters be processed immediately at runtime. +.Pp +.It muldefs +Allows multiple definitions. +.Pp +.It nocombreloc +Disables multiple reloc sections combining. +.Pp +.It nocopyreloc +Disables production of copy relocs. +.Pp +.It nodefaultlib +Marks the object that the search for dependencies of this object will ignore +any default library search paths. +.Pp +.It nodelete +Marks the object shouldn't be unloaded at runtime. +.Pp +.It nodlopen +Marks the object not available to +.Li dlopen . +.Pp +.It nodump +Marks the object can not be dumped by +.Li dldump . +.Pp +.It noexecstack +Marks the object as not requiring executable stack. +.Pp +.It norelro +Don't create an ELF +.Li PT_GNU_RELRO +segment header in the object. +.Pp +.It now +When generating an executable or shared library, mark it to tell the dynamic +linker to resolve all symbols when the program is started, or when the shared +library is linked to using dlopen, instead of deferring function call resolution +to the point when the function is first called. +.Pp +.It origin +Marks the object may contain $ORIGIN. +.Pp +.It relro +Create an ELF +.Li PT_GNU_RELRO +segment header in the object. +.Pp +.It max-page-size= Va value +Set the emulation maximum page size to +.Va value . +.Pp +.It common-page-size= Va value +Set the emulation common page size to +.Va value . +.Pp +.El +Other keywords are ignored for Solaris compatibility. +.Pp +.It -( Va archives -) +.It --start-group Va archives --end-group +The +.Va archives +should be a list of archive files. They may be either explicit file names, +or +.Li -l +options. +.Pp +The specified archives are searched repeatedly until no new undefined references +are created. Normally, an archive is searched only once in the order that +it is specified on the command line. If a symbol in that archive is needed +to resolve an undefined symbol referred to by an object in an archive that +appears later on the command line, the linker would not be able to resolve +that reference. By grouping the archives, they all be searched repeatedly +until all possible references are resolved. +.Pp +Using this option has a significant performance cost. It is best to use it +only when there are unavoidable circular references between two or more archives. +.Pp +.It --accept-unknown-input-arch +.It --no-accept-unknown-input-arch +Tells the linker to accept input files whose architecture cannot be recognised. +The assumption is that the user knows what they are doing and deliberately +wants to link in these unknown input files. This was the default behaviour +of the linker, before release 2.14. The default behaviour from release 2.14 +onwards is to reject such input files, and so the +.Li --accept-unknown-input-arch +option has been added to restore the old behaviour. +.Pp +.It --as-needed +.It --no-as-needed +This option affects ELF DT_NEEDED tags for dynamic libraries mentioned on +the command line after the +.Op --as-needed +option. Normally, the linker will add a DT_NEEDED tag for each dynamic library +mentioned on the command line, regardless of whether the library is actually +needed. +.Op --as-needed +causes DT_NEEDED tags to only be emitted for libraries that satisfy some symbol +reference from regular objects which is undefined at the point that the library +was linked. +.Op --no-as-needed +restores the default behaviour. +.Pp +.It --add-needed +.It --no-add-needed +This option affects the treatment of dynamic libraries from ELF DT_NEEDED +tags in dynamic libraries mentioned on the command line after the +.Op --no-add-needed +option. Normally, the linker will add a DT_NEEDED tag for each dynamic library +from DT_NEEDED tags. +.Op --no-add-needed +causes DT_NEEDED tags will never be emitted for those libraries from DT_NEEDED +tags. +.Op --add-needed +restores the default behaviour. +.Pp +.It -assert Va keyword +This option is ignored for SunOS compatibility. +.Pp +.It -Bdynamic +.It -dy +.It -call_shared +Link against dynamic libraries. This is only meaningful on platforms for which +shared libraries are supported. This option is normally the default on such +platforms. The different variants of this option are for compatibility with +various systems. You may use this option multiple times on the command line: +it affects library searching for +.Op -l +options which follow it. +.Pp +.It -Bgroup +Set the +.Li DF_1_GROUP +flag in the +.Li DT_FLAGS_1 +entry in the dynamic section. This causes the runtime linker to handle lookups +in this object and its dependencies to be performed only inside the group. +.Op --unresolved-symbols=report-all +is implied. This option is only meaningful on ELF platforms which support +shared libraries. +.Pp +.It -Bstatic +.It -dn +.It -non_shared +.It -static +Do not link against shared libraries. This is only meaningful on platforms +for which shared libraries are supported. The different variants of this option +are for compatibility with various systems. You may use this option multiple +times on the command line: it affects library searching for +.Op -l +options which follow it. This option also implies +.Op --unresolved-symbols=report-all . +This option can be used with +.Op -shared . +Doing so means that a shared library is being created but that all of the +library's external references must be resolved by pulling in entries from +static libraries. +.Pp +.It -Bsymbolic +When creating a shared library, bind references to global symbols to the definition +within the shared library, if any. Normally, it is possible for a program +linked against a shared library to override the definition within the shared +library. This option is only meaningful on ELF platforms which support shared +libraries. +.Pp +.It -Bsymbolic-functions +When creating a shared library, bind references to global function symbols +to the definition within the shared library, if any. This option is only meaningful +on ELF platforms which support shared libraries. +.Pp +.It --dynamic-list= Va dynamic-list-file +Specify the name of a dynamic list file to the linker. This is typically used +when creating shared libraries to specify a list of global symbols whose references +shouldn't be bound to the definition within the shared library, or creating +dynamically linked executables to specify a list of symbols which should be +added to the symbol table in the executable. This option is only meaningful +on ELF platforms which support shared libraries. +.Pp +The format of the dynamic list is the same as the version node without scope +and node name. See VERSION for more information. +.Pp +.It --dynamic-list-data +Include all global data symbols to the dynamic list. +.Pp +.It --dynamic-list-cpp-new +Provide the builtin dynamic list for C++ operator new and delete. It is mainly +useful for building shared libstdc++. +.Pp +.It --dynamic-list-cpp-typeinfo +Provide the builtin dynamic list for C++ runtime type identification. +.Pp +.It --check-sections +.It --no-check-sections +Asks the linker +.Em not +to check section addresses after they have been assigned to see if there are +any overlaps. Normally the linker will perform this check, and if it finds +any overlaps it will produce suitable error messages. The linker does know +about, and does make allowances for sections in overlays. The default behaviour +can be restored by using the command line switch +.Op --check-sections . +.Pp +.It --cref +Output a cross reference table. If a linker map file is being generated, the +cross reference table is printed to the map file. Otherwise, it is printed +on the standard output. +.Pp +The format of the table is intentionally simple, so that it may be easily +processed by a script if necessary. The symbols are printed out, sorted by +name. For each symbol, a list of file names is given. If the symbol is defined, +the first file listed is the location of the definition. The remaining files +contain references to the symbol. +.Pp +.It --no-define-common +This option inhibits the assignment of addresses to common symbols. The script +command +.Li INHIBIT_COMMON_ALLOCATION +has the same effect.See Section +.Dq Miscellaneous Commands . +.Pp +The +.Li --no-define-common +option allows decoupling the decision to assign addresses to Common symbols +from the choice of the output file type; otherwise a non-Relocatable output +type forces assigning addresses to Common symbols. Using +.Li --no-define-common +allows Common symbols that are referenced from a shared library to be assigned +addresses only in the main program. This eliminates the unused duplicate space +in the shared library, and also prevents any possible confusion over resolving +to the wrong duplicate when there are many dynamic modules with specialized +search paths for runtime symbol resolution. +.Pp +.It --defsym Va symbol= Va expression +Create a global symbol in the output file, containing the absolute address +given by +.Va expression . +You may use this option as many times as necessary to define multiple symbols +in the command line. A limited form of arithmetic is supported for the +.Va expression +in this context: you may give a hexadecimal constant or the name of an existing +symbol, or use +.Li + +and +.Li - +to add or subtract hexadecimal constants or symbols. If you need more elaborate +expressions, consider using the linker command language from a script (see Section +.Dq Assignments ) . +.Em Note: +there should be no white space between +.Va symbol , +the equals sign (\(lq=\(rq), and +.Va expression . +.Pp +.It --demangle[= Va style] +.It --no-demangle +These options control whether to demangle symbol names in error messages and +other output. When the linker is told to demangle, it tries to present symbol +names in a readable fashion: it strips leading underscores if they are used +by the object file format, and converts C++ mangled symbol names into user +readable names. Different compilers have different mangling styles. The optional +demangling style argument can be used to choose an appropriate demangling +style for your compiler. The linker will demangle by default unless the environment +variable +.Li COLLECT_NO_DEMANGLE +is set. These options may be used to override the default. +.Pp +.It --dynamic-linker Va file +Set the name of the dynamic linker. This is only meaningful when generating +dynamically linked ELF executables. The default dynamic linker is normally +correct; don't use this unless you know what you are doing. +.Pp +.It --fatal-warnings +Treat all warnings as errors. +.Pp +.It --force-exe-suffix +Make sure that an output file has a .exe suffix. +.Pp +If a successfully built fully linked output file does not have a +.Li .exe +or +.Li .dll +suffix, this option forces the linker to copy the output file to one of the +same name with a +.Li .exe +suffix. This option is useful when using unmodified Unix makefiles on a Microsoft +Windows host, since some versions of Windows won't run an image unless it +ends in a +.Li .exe +suffix. +.Pp +.It --gc-sections +.It --no-gc-sections +Enable garbage collection of unused input sections. It is ignored on targets +that do not support this option. This option is not compatible with +.Li -r +or +.Li --emit-relocs . +The default behaviour (of not performing this garbage collection) can be restored +by specifying +.Li --no-gc-sections +on the command line. +.Pp +.It --print-gc-sections +.It --no-print-gc-sections +List all sections removed by garbage collection. The listing is printed on +stderr. This option is only effective if garbage collection has been enabled +via the +.Li --gc-sections ) +option. The default behaviour (of not listing the sections that are removed) +can be restored by specifying +.Li --no-print-gc-sections +on the command line. +.Pp +.It --help +Print a summary of the command-line options on the standard output and exit. +.Pp +.It --target-help +Print a summary of all target specific options on the standard output and +exit. +.Pp +.It -Map Va mapfile +Print a link map to the file +.Va mapfile . +See the description of the +.Op -M +option, above. +.Pp +.It --no-keep-memory +.Xr ld +normally optimizes for speed over memory usage by caching the symbol tables +of input files in memory. This option tells +.Xr ld +to instead optimize for memory usage, by rereading the symbol tables as necessary. +This may be required if +.Xr ld +runs out of memory space while linking a large executable. +.Pp +.It --no-undefined +.It -z defs +Report unresolved symbol references from regular object files. This is done +even if the linker is creating a non-symbolic shared library. The switch +.Op --[no-]allow-shlib-undefined +controls the behaviour for reporting unresolved references found in shared +libraries being linked in. +.Pp +.It --allow-multiple-definition +.It -z muldefs +Normally when a symbol is defined multiple times, the linker will report a +fatal error. These options allow multiple definitions and the first definition +will be used. +.Pp +.It --allow-shlib-undefined +.It --no-allow-shlib-undefined +Allows (the default) or disallows undefined symbols in shared libraries. This +switch is similar to +.Op --no-undefined +except that it determines the behaviour when the undefined symbols are in +a shared library rather than a regular object file. It does not affect how +undefined symbols in regular object files are handled. +.Pp +The reason that +.Op --allow-shlib-undefined +is the default is that the shared library being specified at link time may +not be the same as the one that is available at load time, so the symbols +might actually be resolvable at load time. Plus there are some systems, (eg +BeOS) where undefined symbols in shared libraries is normal. (The kernel patches +them at load time to select which function is most appropriate for the current +architecture. This is used for example to dynamically select an appropriate +memset function). Apparently it is also normal for HPPA shared libraries to +have undefined symbols. +.Pp +.It --no-undefined-version +Normally when a symbol has an undefined version, the linker will ignore it. +This option disallows symbols with undefined version and a fatal error will +be issued instead. +.Pp +.It --default-symver +Create and use a default symbol version (the soname) for unversioned exported +symbols. +.Pp +.It --default-imported-symver +Create and use a default symbol version (the soname) for unversioned imported +symbols. +.Pp +.It --no-warn-mismatch +Normally +.Xr ld +will give an error if you try to link together input files that are mismatched +for some reason, perhaps because they have been compiled for different processors +or for different endiannesses. This option tells +.Xr ld +that it should silently permit such possible errors. This option should only +be used with care, in cases when you have taken some special action that ensures +that the linker errors are inappropriate. +.Pp +.It --no-warn-search-mismatch +Normally +.Xr ld +will give a warning if it finds an incompatible library during a library search. +This option silences the warning. +.Pp +.It --no-whole-archive +Turn off the effect of the +.Op --whole-archive +option for subsequent archive files. +.Pp +.It --noinhibit-exec +Retain the executable output file whenever it is still usable. Normally, the +linker will not produce an output file if it encounters errors during the +link process; it exits without writing an output file when it issues any error +whatsoever. +.Pp +.It -nostdlib +Only search library directories explicitly specified on the command line. +Library directories specified in linker scripts (including linker scripts +specified on the command line) are ignored. +.Pp +.It --oformat Va output-format +.Xr ld +may be configured to support more than one kind of object file. If your +.Xr ld +is configured this way, you can use the +.Li --oformat +option to specify the binary format for the output object file. Even when +.Xr ld +is configured to support alternative object formats, you don't usually need +to specify this, as +.Xr ld +should be configured to produce as a default output format the most usual +format on each machine. +.Va output-format +is a text string, the name of a particular format supported by the BFD libraries. +(You can list the available binary formats with +.Li objdump -i . ) +The script command +.Li OUTPUT_FORMAT +can also specify the output format, but this option overrides it.See Section +.Dq BFD . +.Pp +.It -pie +.It --pic-executable +Create a position independent executable. This is currently only supported +on ELF platforms. Position independent executables are similar to shared libraries +in that they are relocated by the dynamic linker to the virtual address the +OS chooses for them (which can vary between invocations). Like normal dynamically +linked executables they can be executed and symbols defined in the executable +cannot be overridden by shared libraries. +.Pp +.It -qmagic +This option is ignored for Linux compatibility. +.Pp +.It -Qy +This option is ignored for SVR4 compatibility. +.Pp +.It --relax +An option with machine dependent effects. This option is only supported on +a few targets.See Section +.Dq H8/300 . +See Section.Dq i960 . +See Section.Dq Xtensa . +See Section.Dq M68HC11/68HC12 . +See Section.Dq PowerPC ELF32 . +.Pp +On some platforms, the +.Li --relax +option performs global optimizations that become possible when the linker +resolves addressing in the program, such as relaxing address modes and synthesizing +new instructions in the output object file. +.Pp +On some platforms these link time global optimizations may make symbolic debugging +of the resulting executable impossible. This is known to be the case for the +Matsushita MN10200 and MN10300 family of processors. +.Pp +On platforms where this is not supported, +.Li --relax +is accepted, but ignored. +.Pp +.It --retain-symbols-file Va filename +Retain +.Em only +the symbols listed in the file +.Va filename , +discarding all others. +.Va filename +is simply a flat file, with one symbol name per line. This option is especially +useful in environments (such as VxWorks) where a large global symbol table +is accumulated gradually, to conserve run-time memory. +.Pp +.Li --retain-symbols-file +does +.Em not +discard undefined symbols, or symbols needed for relocations. +.Pp +You may only specify +.Li --retain-symbols-file +once in the command line. It overrides +.Li -s +and +.Li -S . +.Pp +.It -rpath Va dir +Add a directory to the runtime library search path. This is used when linking +an ELF executable with shared objects. All +.Op -rpath +arguments are concatenated and passed to the runtime linker, which uses them +to locate shared objects at runtime. The +.Op -rpath +option is also used when locating shared objects which are needed by shared +objects explicitly included in the link; see the description of the +.Op -rpath-link +option. If +.Op -rpath +is not used when linking an ELF executable, the contents of the environment +variable +.Li LD_RUN_PATH +will be used if it is defined. +.Pp +The +.Op -rpath +option may also be used on SunOS. By default, on SunOS, the linker will form +a runtime search patch out of all the +.Op -L +options it is given. If a +.Op -rpath +option is used, the runtime search path will be formed exclusively using the +.Op -rpath +options, ignoring the +.Op -L +options. This can be useful when using gcc, which adds many +.Op -L +options which may be on NFS mounted file systems. +.Pp +For compatibility with other ELF linkers, if the +.Op -R +option is followed by a directory name, rather than a file name, it is treated +as the +.Op -rpath +option. +.Pp +.It -rpath-link Va DIR +When using ELF or SunOS, one shared library may require another. This happens +when an +.Li ld -shared +link includes a shared library as one of the input files. +.Pp +When the linker encounters such a dependency when doing a non-shared, non-relocatable +link, it will automatically try to locate the required shared library and +include it in the link, if it is not included explicitly. In such a case, +the +.Op -rpath-link +option specifies the first set of directories to search. The +.Op -rpath-link +option may specify a sequence of directory names either by specifying a list +of names separated by colons, or by appearing multiple times. +.Pp +This option should be used with caution as it overrides the search path that +may have been hard compiled into a shared library. In such a case it is possible +to use unintentionally a different search path than the runtime linker would +do. +.Pp +The linker uses the following search paths to locate required shared libraries: +.Bl -enum +.It +Any directories specified by +.Op -rpath-link +options. +.It +Any directories specified by +.Op -rpath +options. The difference between +.Op -rpath +and +.Op -rpath-link +is that directories specified by +.Op -rpath +options are included in the executable and used at runtime, whereas the +.Op -rpath-link +option is only effective at link time. Searching +.Op -rpath +in this way is only supported by native linkers and cross linkers which have +been configured with the +.Op --with-sysroot +option. +.It +On an ELF system, if the +.Op -rpath +and +.Li rpath-link +options were not used, search the contents of the environment variable +.Li LD_RUN_PATH . +It is for the native linker only. +.It +On SunOS, if the +.Op -rpath +option was not used, search any directories specified using +.Op -L +options. +.It +For a native linker, the contents of the environment variable +.Li LD_LIBRARY_PATH . +.It +For a native ELF linker, the directories in +.Li DT_RUNPATH +or +.Li DT_RPATH +of a shared library are searched for shared libraries needed by it. The +.Li DT_RPATH +entries are ignored if +.Li DT_RUNPATH +entries exist. +.It +The default directories, normally +.Pa /lib +and +.Pa /usr/lib . +.It +For a native linker on an ELF system, if the file +.Pa /etc/ld.so.conf +exists, the list of directories found in that file. +.El +.Pp +If the required shared library is not found, the linker will issue a warning +and continue with the link. +.Pp +.It -shared +.It -Bshareable +Create a shared library. This is currently only supported on ELF, XCOFF and +SunOS platforms. On SunOS, the linker will automatically create a shared library +if the +.Op -e +option is not used and there are undefined symbols in the link. +.Pp +.It --sort-common +This option tells +.Xr ld +to sort the common symbols by size when it places them in the appropriate +output sections. First come all the one byte symbols, then all the two byte, +then all the four byte, and then everything else. This is to prevent gaps +between symbols due to alignment constraints. +.Pp +.It --sort-section name +This option will apply +.Li SORT_BY_NAME +to all wildcard section patterns in the linker script. +.Pp +.It --sort-section alignment +This option will apply +.Li SORT_BY_ALIGNMENT +to all wildcard section patterns in the linker script. +.Pp +.It --split-by-file [ Va size] +Similar to +.Op --split-by-reloc +but creates a new output section for each input file when +.Va size +is reached. +.Va size +defaults to a size of 1 if not given. +.Pp +.It --split-by-reloc [ Va count] +Tries to creates extra sections in the output file so that no single output +section in the file contains more than +.Va count +relocations. This is useful when generating huge relocatable files for downloading +into certain real time kernels with the COFF object file format; since COFF +cannot represent more than 65535 relocations in a single section. Note that +this will fail to work with object file formats which do not support arbitrary +sections. The linker will not split up individual input sections for redistribution, +so if a single input section contains more than +.Va count +relocations one output section will contain that many relocations. +.Va count +defaults to a value of 32768. +.Pp +.It --stats +Compute and display statistics about the operation of the linker, such as +execution time and memory usage. +.Pp +.It --sysroot= Va directory +Use +.Va directory +as the location of the sysroot, overriding the configure-time default. This +option is only supported by linkers that were configured using +.Op --with-sysroot . +.Pp +.It --traditional-format +For some targets, the output of +.Xr ld +is different in some ways from the output of some existing linker. This switch +requests +.Xr ld +to use the traditional format instead. +.Pp +For example, on SunOS, +.Xr ld +combines duplicate entries in the symbol string table. This can reduce the +size of an output file with full debugging information by over 30 percent. +Unfortunately, the SunOS +.Li dbx +program can not read the resulting program ( +.Li gdb +has no trouble). The +.Li --traditional-format +switch tells +.Xr ld +to not combine duplicate entries. +.Pp +.It --section-start Va sectionname= Va org +Locate a section in the output file at the absolute address given by +.Va org . +You may use this option as many times as necessary to locate multiple sections +in the command line. +.Va org +must be a single hexadecimal integer; for compatibility with other linkers, +you may omit the leading +.Li 0x +usually associated with hexadecimal values. +.Em Note: +there should be no white space between +.Va sectionname , +the equals sign (\(lq=\(rq), and +.Va org . +.Pp +.It -Tbss Va org +.It -Tdata Va org +.It -Ttext Va org +Same as --section-start, with +.Li .bss , +.Li .data +or +.Li .text +as the +.Va sectionname . +.Pp +.It --unresolved-symbols= Va method +Determine how to handle unresolved symbols. There are four possible values +for +.Li method : +.Pp +.Bl -tag -width Ds +.It ignore-all +Do not report any unresolved symbols. +.Pp +.It report-all +Report all unresolved symbols. This is the default. +.Pp +.It ignore-in-object-files +Report unresolved symbols that are contained in shared libraries, but ignore +them if they come from regular object files. +.Pp +.It ignore-in-shared-libs +Report unresolved symbols that come from regular object files, but ignore +them if they come from shared libraries. This can be useful when creating +a dynamic binary and it is known that all the shared libraries that it should +be referencing are included on the linker's command line. +.El +.Pp +The behaviour for shared libraries on their own can also be controlled by +the +.Op --[no-]allow-shlib-undefined +option. +.Pp +Normally the linker will generate an error message for each reported unresolved +symbol but the option +.Op --warn-unresolved-symbols +can change this to a warning. +.Pp +.It --dll-verbose +.It --verbose +Display the version number for +.Xr ld +and list the linker emulations supported. Display which input files can and +cannot be opened. Display the linker script being used by the linker. +.Pp +.It --version-script= Va version-scriptfile +Specify the name of a version script to the linker. This is typically used +when creating shared libraries to specify additional information about the +version hierarchy for the library being created. This option is only meaningful +on ELF platforms which support shared libraries.See Section +.Dq VERSION . +.Pp +.It --warn-common +Warn when a common symbol is combined with another common symbol or with a +symbol definition. Unix linkers allow this somewhat sloppy practise, but linkers +on some other operating systems do not. This option allows you to find potential +problems from combining global symbols. Unfortunately, some C libraries use +this practise, so you may get some warnings about symbols in the libraries +as well as in your programs. +.Pp +There are three kinds of global symbols, illustrated here by C examples: +.Pp +.Bl -tag -width Ds +.It int i = 1; +A definition, which goes in the initialized data section of the output file. +.Pp +.It extern int i; +An undefined reference, which does not allocate space. There must be either +a definition or a common symbol for the variable somewhere. +.Pp +.It int i; +A common symbol. If there are only (one or more) common symbols for a variable, +it goes in the uninitialized data area of the output file. The linker merges +multiple common symbols for the same variable into a single symbol. If they +are of different sizes, it picks the largest size. The linker turns a common +symbol into a declaration, if there is a definition of the same variable. +.El +.Pp +The +.Li --warn-common +option can produce five kinds of warnings. Each warning consists of a pair +of lines: the first describes the symbol just encountered, and the second +describes the previous symbol encountered with the same name. One or both +of the two symbols will be a common symbol. +.Pp +.Bl -enum +.It +Turning a common symbol into a reference, because there is already a definition +for the symbol. +.Bd -literal -offset indent +file(section): warning: common of `symbol' + overridden by definition +file(section): warning: defined here +.Ed +.Pp +.It +Turning a common symbol into a reference, because a later definition for the +symbol is encountered. This is the same as the previous case, except that +the symbols are encountered in a different order. +.Bd -literal -offset indent +file(section): warning: definition of `symbol' + overriding common +file(section): warning: common is here +.Ed +.Pp +.It +Merging a common symbol with a previous same-sized common symbol. +.Bd -literal -offset indent +file(section): warning: multiple common + of `symbol' +file(section): warning: previous common is here +.Ed +.Pp +.It +Merging a common symbol with a previous larger common symbol. +.Bd -literal -offset indent +file(section): warning: common of `symbol' + overridden by larger common +file(section): warning: larger common is here +.Ed +.Pp +.It +Merging a common symbol with a previous smaller common symbol. This is the +same as the previous case, except that the symbols are encountered in a different +order. +.Bd -literal -offset indent +file(section): warning: common of `symbol' + overriding smaller common +file(section): warning: smaller common is here +.Ed +.El +.Pp +.It --warn-constructors +Warn if any global constructors are used. This is only useful for a few object +file formats. For formats like COFF or ELF, the linker can not detect the +use of global constructors. +.Pp +.It --warn-multiple-gp +Warn if multiple global pointer values are required in the output file. This +is only meaningful for certain processors, such as the Alpha. Specifically, +some processors put large-valued constants in a special section. A special +register (the global pointer) points into the middle of this section, so that +constants can be loaded efficiently via a base-register relative addressing +mode. Since the offset in base-register relative mode is fixed and relatively +small (e.g., 16 bits), this limits the maximum size of the constant pool. +Thus, in large programs, it is often necessary to use multiple global pointer +values in order to be able to address all possible constants. This option +causes a warning to be issued whenever this case occurs. +.Pp +.It --warn-once +Only warn once for each undefined symbol, rather than once per module which +refers to it. +.Pp +.It --warn-section-align +Warn if the address of an output section is changed because of alignment. +Typically, the alignment will be set by an input section. The address will +only be changed if it not explicitly specified; that is, if the +.Li SECTIONS +command does not specify a start address for the section (see Section +.Dq SECTIONS ) . +.Pp +.It --warn-shared-textrel +Warn if the linker adds a DT_TEXTREL to a shared object. +.Pp +.It --warn-unresolved-symbols +If the linker is going to report an unresolved symbol (see the option +.Op --unresolved-symbols ) +it will normally generate an error. This option makes it generate a warning +instead. +.Pp +.It --error-unresolved-symbols +This restores the linker's default behaviour of generating errors when it +is reporting unresolved symbols. +.Pp +.It --whole-archive +For each archive mentioned on the command line after the +.Op --whole-archive +option, include every object file in the archive in the link, rather than +searching the archive for the required object files. This is normally used +to turn an archive file into a shared library, forcing every object to be +included in the resulting shared library. This option may be used more than +once. +.Pp +Two notes when using this option from gcc: First, gcc doesn't know about this +option, so you have to use +.Op -Wl,-whole-archive . +Second, don't forget to use +.Op -Wl,-no-whole-archive +after your list of archives, because gcc will add its own list of archives +to your link and you may not want this flag to affect those as well. +.Pp +.It --wrap Va symbol +Use a wrapper function for +.Va symbol . +Any undefined reference to +.Va symbol +will be resolved to +.Li __wrap_ Va symbol . +Any undefined reference to +.Li __real_ Va symbol +will be resolved to +.Va symbol . +.Pp +This can be used to provide a wrapper for a system function. The wrapper function +should be called +.Li __wrap_ Va symbol . +If it wishes to call the system function, it should call +.Li __real_ Va symbol . +.Pp +Here is a trivial example: +.Pp +.Bd -literal -offset indent +void * +__wrap_malloc (size_t c) +{ + printf ("malloc called with %zu\en", c); + return __real_malloc (c); +} +.Ed +.Pp +If you link other code with this file using +.Op --wrap malloc , +then all calls to +.Li malloc +will call the function +.Li __wrap_malloc +instead. The call to +.Li __real_malloc +in +.Li __wrap_malloc +will call the real +.Li malloc +function. +.Pp +You may wish to provide a +.Li __real_malloc +function as well, so that links without the +.Op --wrap +option will succeed. If you do this, you should not put the definition of +.Li __real_malloc +in the same file as +.Li __wrap_malloc ; +if you do, the assembler may resolve the call before the linker has a chance +to wrap it to +.Li malloc . +.Pp +.It --eh-frame-hdr +Request creation of +.Li .eh_frame_hdr +section and ELF +.Li PT_GNU_EH_FRAME +segment header. +.Pp +.It --enable-new-dtags +.It --disable-new-dtags +This linker can create the new dynamic tags in ELF. But the older ELF systems +may not understand them. If you specify +.Op --enable-new-dtags , +the dynamic tags will be created as needed. If you specify +.Op --disable-new-dtags , +no new dynamic tags will be created. By default, the new dynamic tags are +not created. Note that those options are only available for ELF systems. +.Pp +.It --hash-size= Va number +Set the default size of the linker's hash tables to a prime number close to +.Va number . +Increasing this value can reduce the length of time it takes the linker to +perform its tasks, at the expense of increasing the linker's memory requirements. +Similarly reducing this value can reduce the memory requirements at the expense +of speed. +.Pp +.It --hash-style= Va style +Set the type of linker's hash table(s). +.Va style +can be either +.Li sysv +for classic ELF +.Li .hash +section, +.Li GNU +for new style GNU +.Li .GNU.hash +section or +.Li both +for both the classic ELF +.Li .hash +and new style GNU +.Li .GNU.hash +hash tables. The default is +.Li sysv . +.Pp +.It --reduce-memory-overheads +This option reduces memory requirements at ld runtime, at the expense of linking +speed. This was introduced to select the old O(n^2) algorithm for link map +file generation, rather than the new O(n) algorithm which uses about 40% more +memory for symbol storage. +.Pp +Another effect of the switch is to set the default hash table size to 1021, +which again saves memory at the cost of lengthening the linker's run time. +This is not done however if the +.Op --hash-size +switch has been used. +.Pp +The +.Op --reduce-memory-overheads +switch may be also be used to enable other tradeoffs in future versions of +the linker. +.Pp +.El +.Em Options Specific to i386 PE Targets +.Pp +The i386 PE linker supports the +.Op -shared +option, which causes the output to be a dynamically linked library (DLL) instead +of a normal executable. You should name the output +.Li *.dll +when you use this option. In addition, the linker fully supports the standard +.Li *.def +files, which may be specified on the linker command line like an object file +(in fact, it should precede archives it exports symbols from, to ensure that +they get linked in, just like a normal object file). +.Pp +In addition to the options common to all targets, the i386 PE linker support +additional command line options that are specific to the i386 PE target. Options +that take values may be separated from their values by either a space or an +equals sign. +.Pp +.Bl -tag -width Ds +.It --add-stdcall-alias +If given, symbols with a stdcall suffix (@ +.Va nn ) +will be exported as-is and also with the suffix stripped. [This option is +specific to the i386 PE targeted port of the linker] +.Pp +.It --base-file Va file +Use +.Va file +as the name of a file in which to save the base addresses of all the relocations +needed for generating DLLs with +.Pa dlltool . +[This is an i386 PE specific option] +.Pp +.It --dll +Create a DLL instead of a regular executable. You may also use +.Op -shared +or specify a +.Li LIBRARY +in a given +.Li .def +file. [This option is specific to the i386 PE targeted port of the linker] +.Pp +.It --enable-stdcall-fixup +.It --disable-stdcall-fixup +If the link finds a symbol that it cannot resolve, it will attempt to do \(lqfuzzy +linking\(rq by looking for another defined symbol that differs only in the format +of the symbol name (cdecl vs stdcall) and will resolve that symbol by linking +to the match. For example, the undefined symbol +.Li _foo +might be linked to the function +.Li _foo@12 , +or the undefined symbol +.Li _bar@16 +might be linked to the function +.Li _bar . +When the linker does this, it prints a warning, since it normally should have +failed to link, but sometimes import libraries generated from third-party +dlls may need this feature to be usable. If you specify +.Op --enable-stdcall-fixup , +this feature is fully enabled and warnings are not printed. If you specify +.Op --disable-stdcall-fixup , +this feature is disabled and such mismatches are considered to be errors. +[This option is specific to the i386 PE targeted port of the linker] +.Pp +.It --export-all-symbols +If given, all global symbols in the objects used to build a DLL will be exported +by the DLL. Note that this is the default if there otherwise wouldn't be any +exported symbols. When symbols are explicitly exported via DEF files or implicitly +exported via function attributes, the default is to not export anything else +unless this option is given. Note that the symbols +.Li DllMain@12 , +.Li DllEntryPoint@0 , +.Li DllMainCRTStartup@12 , +and +.Li impure_ptr +will not be automatically exported. Also, symbols imported from other DLLs +will not be re-exported, nor will symbols specifying the DLL's internal layout +such as those beginning with +.Li _head_ +or ending with +.Li _iname . +In addition, no symbols from +.Li libgcc , +.Li libstd++ , +.Li libmingw32 , +or +.Li crtX.o +will be exported. Symbols whose names begin with +.Li __rtti_ +or +.Li __builtin_ +will not be exported, to help with C++ DLLs. Finally, there is an extensive +list of cygwin-private symbols that are not exported (obviously, this applies +on when building DLLs for cygwin targets). These cygwin-excludes are: +.Li _cygwin_dll_entry@12 , +.Li _cygwin_crt0_common@8 , +.Li _cygwin_noncygwin_dll_entry@12 , +.Li _fmode , +.Li _impure_ptr , +.Li cygwin_attach_dll , +.Li cygwin_premain0 , +.Li cygwin_premain1 , +.Li cygwin_premain2 , +.Li cygwin_premain3 , +and +.Li environ . +[This option is specific to the i386 PE targeted port of the linker] +.Pp +.It --exclude-symbols Va symbol, Va symbol,... +Specifies a list of symbols which should not be automatically exported. The +symbol names may be delimited by commas or colons. [This option is specific +to the i386 PE targeted port of the linker] +.Pp +.It --file-alignment +Specify the file alignment. Sections in the file will always begin at file +offsets which are multiples of this number. This defaults to 512. [This option +is specific to the i386 PE targeted port of the linker] +.Pp +.It --heap Va reserve +.It --heap Va reserve, Va commit +Specify the amount of memory to reserve (and optionally commit) to be used +as heap for this program. The default is 1Mb reserved, 4K committed. [This +option is specific to the i386 PE targeted port of the linker] +.Pp +.It --image-base Va value +Use +.Va value +as the base address of your program or dll. This is the lowest memory location +that will be used when your program or dll is loaded. To reduce the need to +relocate and improve performance of your dlls, each should have a unique base +address and not overlap any other dlls. The default is 0x400000 for executables, +and 0x10000000 for dlls. [This option is specific to the i386 PE targeted +port of the linker] +.Pp +.It --kill-at +If given, the stdcall suffixes (@ +.Va nn ) +will be stripped from symbols before they are exported. [This option is specific +to the i386 PE targeted port of the linker] +.Pp +.It --large-address-aware +If given, the appropriate bit in the \(lqCharacteristics\(rq field of the COFF header +is set to indicate that this executable supports virtual addresses greater +than 2 gigabytes. This should be used in conjunction with the /3GB or /USERVA= +.Va value +megabytes switch in the \(lq[operating systems]\(rq section of the BOOT.INI. Otherwise, +this bit has no effect. [This option is specific to PE targeted ports of the +linker] +.Pp +.It --major-image-version Va value +Sets the major number of the \(lqimage version\(rq. Defaults to 1. [This option is +specific to the i386 PE targeted port of the linker] +.Pp +.It --major-os-version Va value +Sets the major number of the \(lqos version\(rq. Defaults to 4. [This option is specific +to the i386 PE targeted port of the linker] +.Pp +.It --major-subsystem-version Va value +Sets the major number of the \(lqsubsystem version\(rq. Defaults to 4. [This option +is specific to the i386 PE targeted port of the linker] +.Pp +.It --minor-image-version Va value +Sets the minor number of the \(lqimage version\(rq. Defaults to 0. [This option is +specific to the i386 PE targeted port of the linker] +.Pp +.It --minor-os-version Va value +Sets the minor number of the \(lqos version\(rq. Defaults to 0. [This option is specific +to the i386 PE targeted port of the linker] +.Pp +.It --minor-subsystem-version Va value +Sets the minor number of the \(lqsubsystem version\(rq. Defaults to 0. [This option +is specific to the i386 PE targeted port of the linker] +.Pp +.It --output-def Va file +The linker will create the file +.Va file +which will contain a DEF file corresponding to the DLL the linker is generating. +This DEF file (which should be called +.Li *.def ) +may be used to create an import library with +.Li dlltool +or may be used as a reference to automatically or implicitly exported symbols. +[This option is specific to the i386 PE targeted port of the linker] +.Pp +.It --out-implib Va file +The linker will create the file +.Va file +which will contain an import lib corresponding to the DLL the linker is generating. +This import lib (which should be called +.Li *.dll.a +or +.Li *.a +may be used to link clients against the generated DLL; this behaviour makes +it possible to skip a separate +.Li dlltool +import library creation step. [This option is specific to the i386 PE targeted +port of the linker] +.Pp +.It --enable-auto-image-base +Automatically choose the image base for DLLs, unless one is specified using +the +.Li --image-base +argument. By using a hash generated from the dllname to create unique image +bases for each DLL, in-memory collisions and relocations which can delay program +execution are avoided. [This option is specific to the i386 PE targeted port +of the linker] +.Pp +.It --disable-auto-image-base +Do not automatically generate a unique image base. If there is no user-specified +image base ( +.Li --image-base ) +then use the platform default. [This option is specific to the i386 PE targeted +port of the linker] +.Pp +.It --dll-search-prefix Va string +When linking dynamically to a dll without an import library, search for +.Li <string><basename>.dll +in preference to +.Li lib<basename>.dll . +This behaviour allows easy distinction between DLLs built for the various +"subplatforms": native, cygwin, uwin, pw, etc. For instance, cygwin DLLs typically +use +.Li --dll-search-prefix=cyg . +[This option is specific to the i386 PE targeted port of the linker] +.Pp +.It --enable-auto-import +Do sophisticated linking of +.Li _symbol +to +.Li __imp__symbol +for DATA imports from DLLs, and create the necessary thunking symbols when +building the import libraries with those DATA exports. Note: Use of the 'auto-import' +extension will cause the text section of the image file to be made writable. +This does not conform to the PE-COFF format specification published by Microsoft. +.Pp +Using 'auto-import' generally will 'just work' -- but sometimes you may see +this message: +.Pp +"variable '<var>' can't be auto-imported. Please read the documentation for +ld's +.Li --enable-auto-import +for details." +.Pp +This message occurs when some (sub)expression accesses an address ultimately +given by the sum of two constants (Win32 import tables only allow one). Instances +where this may occur include accesses to member fields of struct variables +imported from a DLL, as well as using a constant index into an array variable +imported from a DLL. Any multiword variable (arrays, structs, long long, etc) +may trigger this error condition. However, regardless of the exact data type +of the offending exported variable, ld will always detect it, issue the warning, +and exit. +.Pp +There are several ways to address this difficulty, regardless of the data +type of the exported variable: +.Pp +One way is to use --enable-runtime-pseudo-reloc switch. This leaves the task +of adjusting references in your client code for runtime environment, so this +method works only when runtime environment supports this feature. +.Pp +A second solution is to force one of the 'constants' to be a variable -- that +is, unknown and un-optimizable at compile time. For arrays, there are two +possibilities: a) make the indexee (the array's address) a variable, or b) +make the 'constant' index a variable. Thus: +.Pp +.Bd -literal -offset indent +extern type extern_array[]; +extern_array[1] --> + { volatile type *t=extern_array; t[1] } +.Ed +.Pp +or +.Pp +.Bd -literal -offset indent +extern type extern_array[]; +extern_array[1] --> + { volatile int t=1; extern_array[t] } +.Ed +.Pp +For structs (and most other multiword data types) the only option is to make +the struct itself (or the long long, or the ...) variable: +.Pp +.Bd -literal -offset indent +extern struct s extern_struct; +extern_struct.field --> + { volatile struct s *t=&extern_struct; t->field } +.Ed +.Pp +or +.Pp +.Bd -literal -offset indent +extern long long extern_ll; +extern_ll --> + { volatile long long * local_ll=&extern_ll; *local_ll } +.Ed +.Pp +A third method of dealing with this difficulty is to abandon 'auto-import' +for the offending symbol and mark it with +.Li __declspec(dllimport) . +However, in practise that requires using compile-time #defines to indicate +whether you are building a DLL, building client code that will link to the +DLL, or merely building/linking to a static library. In making the choice +between the various methods of resolving the 'direct address with constant +offset' problem, you should consider typical real-world usage: +.Pp +Original: +.Bd -literal -offset indent +--foo.h +extern int arr[]; +--foo.c +#include "foo.h" +void main(int argc, char **argv){ + printf("%d\en",arr[1]); +} +.Ed +.Pp +Solution 1: +.Bd -literal -offset indent +--foo.h +extern int arr[]; +--foo.c +#include "foo.h" +void main(int argc, char **argv){ + /* This workaround is for win32 and cygwin; do not "optimize" */ + volatile int *parr = arr; + printf("%d\en",parr[1]); +} +.Ed +.Pp +Solution 2: +.Bd -literal -offset indent +--foo.h +/* Note: auto-export is assumed (no __declspec(dllexport)) */ +#if (defined(_WIN32) || defined(__CYGWIN__)) && \e + !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC)) +#define FOO_IMPORT __declspec(dllimport) +#else +#define FOO_IMPORT +#endif +extern FOO_IMPORT int arr[]; +--foo.c +#include "foo.h" +void main(int argc, char **argv){ + printf("%d\en",arr[1]); +} +.Ed +.Pp +A fourth way to avoid this problem is to re-code your library to use a functional +interface rather than a data interface for the offending variables (e.g. set_foo() +and get_foo() accessor functions). [This option is specific to the i386 PE +targeted port of the linker] +.Pp +.It --disable-auto-import +Do not attempt to do sophisticated linking of +.Li _symbol +to +.Li __imp__symbol +for DATA imports from DLLs. [This option is specific to the i386 PE targeted +port of the linker] +.Pp +.It --enable-runtime-pseudo-reloc +If your code contains expressions described in --enable-auto-import section, +that is, DATA imports from DLL with non-zero offset, this switch will create +a vector of 'runtime pseudo relocations' which can be used by runtime environment +to adjust references to such data in your client code. [This option is specific +to the i386 PE targeted port of the linker] +.Pp +.It --disable-runtime-pseudo-reloc +Do not create pseudo relocations for non-zero offset DATA imports from DLLs. +This is the default. [This option is specific to the i386 PE targeted port +of the linker] +.Pp +.It --enable-extra-pe-debug +Show additional debug info related to auto-import symbol thunking. [This option +is specific to the i386 PE targeted port of the linker] +.Pp +.It --section-alignment +Sets the section alignment. Sections in memory will always begin at addresses +which are a multiple of this number. Defaults to 0x1000. [This option is specific +to the i386 PE targeted port of the linker] +.Pp +.It --stack Va reserve +.It --stack Va reserve, Va commit +Specify the amount of memory to reserve (and optionally commit) to be used +as stack for this program. The default is 2Mb reserved, 4K committed. [This +option is specific to the i386 PE targeted port of the linker] +.Pp +.It --subsystem Va which +.It --subsystem Va which: Va major +.It --subsystem Va which: Va major. Va minor +Specifies the subsystem under which your program will execute. The legal values +for +.Va which +are +.Li native , +.Li windows , +.Li console , +.Li posix , +and +.Li xbox . +You may optionally set the subsystem version also. Numeric values are also +accepted for +.Va which . +[This option is specific to the i386 PE targeted port of the linker] +.Pp +.El +.Em Options specific to Motorola 68HC11 and 68HC12 targets +.Pp +The 68HC11 and 68HC12 linkers support specific options to control the memory +bank switching mapping and trampoline code generation. +.Pp +.Bl -tag -width Ds +.It --no-trampoline +This option disables the generation of trampoline. By default a trampoline +is generated for each far function which is called using a +.Li jsr +instruction (this happens when a pointer to a far function is taken). +.Pp +.It --bank-window Va name +This option indicates to the linker the name of the memory region in the +.Li MEMORY +specification that describes the memory bank window. The definition of such +region is then used by the linker to compute paging and addresses within the +memory window. +.Pp +.El +.Ss Environment Variables +You can change the behaviour of +.Xr ld +with the environment variables +.Li GNUTARGET , +.Li LDEMULATION +and +.Li COLLECT_NO_DEMANGLE . +.Pp +.Li GNUTARGET +determines the input-file object format if you don't use +.Li -b +(or its synonym +.Li --format ) . +Its value should be one of the BFD names for an input format (see Section +.Dq BFD ) . +If there is no +.Li GNUTARGET +in the environment, +.Xr ld +uses the natural format of the target. If +.Li GNUTARGET +is set to +.Li default +then BFD attempts to discover the input format by examining binary input files; +this method often succeeds, but there are potential ambiguities, since there +is no method of ensuring that the magic number used to specify object-file +formats is unique. However, the configuration procedure for BFD on each system +places the conventional format for that system first in the search-list, so +ambiguities are resolved in favor of convention. +.Pp +.Li LDEMULATION +determines the default emulation if you don't use the +.Li -m +option. The emulation can affect various aspects of linker behaviour, particularly +the default linker script. You can list the available emulations with the +.Li --verbose +or +.Li -V +options. If the +.Li -m +option is not used, and the +.Li LDEMULATION +environment variable is not defined, the default emulation depends upon how +the linker was configured. +.Pp +Normally, the linker will default to demangling symbols. However, if +.Li COLLECT_NO_DEMANGLE +is set in the environment, then it will default to not demangling symbols. +This environment variable is used in a similar fashion by the +.Li gcc +linker wrapper program. The default may be overridden by the +.Li --demangle +and +.Li --no-demangle +options. +.Pp +.Sh Linker Scripts +Every link is controlled by a +.Em linker script . +This script is written in the linker command language. +.Pp +The main purpose of the linker script is to describe how the sections in the +input files should be mapped into the output file, and to control the memory +layout of the output file. Most linker scripts do nothing more than this. +However, when necessary, the linker script can also direct the linker to perform +many other operations, using the commands described below. +.Pp +The linker always uses a linker script. If you do not supply one yourself, +the linker will use a default script that is compiled into the linker executable. +You can use the +.Li --verbose +command line option to display the default linker script. Certain command +line options, such as +.Li -r +or +.Li -N , +will affect the default linker script. +.Pp +You may supply your own linker script by using the +.Li -T +command line option. When you do this, your linker script will replace the +default linker script. +.Pp +You may also use linker scripts implicitly by naming them as input files to +the linker, as though they were files to be linked.See Section +.Dq Implicit Linker Scripts . +.Pp +.Ss Basic Linker Script Concepts +We need to define some basic concepts and vocabulary in order to describe +the linker script language. +.Pp +The linker combines input files into a single output file. The output file +and each input file are in a special data format known as an +.Em object file format . +Each file is called an +.Em object file . +The output file is often called an +.Em executable , +but for our purposes we will also call it an object file. Each object file +has, among other things, a list of +.Em sections . +We sometimes refer to a section in an input file as an +.Em input section ; +similarly, a section in the output file is an +.Em output section . +.Pp +Each section in an object file has a name and a size. Most sections also have +an associated block of data, known as the +.Em section contents . +A section may be marked as +.Em loadable , +which mean that the contents should be loaded into memory when the output +file is run. A section with no contents may be +.Em allocatable , +which means that an area in memory should be set aside, but nothing in particular +should be loaded there (in some cases this memory must be zeroed out). A section +which is neither loadable nor allocatable typically contains some sort of +debugging information. +.Pp +Every loadable or allocatable output section has two addresses. The first +is the +.Em VMA , +or virtual memory address. This is the address the section will have when +the output file is run. The second is the +.Em LMA , +or load memory address. This is the address at which the section will be loaded. +In most cases the two addresses will be the same. An example of when they +might be different is when a data section is loaded into ROM, and then copied +into RAM when the program starts up (this technique is often used to initialize +global variables in a ROM based system). In this case the ROM address would +be the LMA, and the RAM address would be the VMA. +.Pp +You can see the sections in an object file by using the +.Li objdump +program with the +.Li -h +option. +.Pp +Every object file also has a list of +.Em symbols , +known as the +.Em symbol table . +A symbol may be defined or undefined. Each symbol has a name, and each defined +symbol has an address, among other information. If you compile a C or C++ +program into an object file, you will get a defined symbol for every defined +function and global or static variable. Every undefined function or global +variable which is referenced in the input file will become an undefined symbol. +.Pp +You can see the symbols in an object file by using the +.Li nm +program, or by using the +.Li objdump +program with the +.Li -t +option. +.Pp +.Ss Linker Script Format +Linker scripts are text files. +.Pp +You write a linker script as a series of commands. Each command is either +a keyword, possibly followed by arguments, or an assignment to a symbol. You +may separate commands using semicolons. Whitespace is generally ignored. +.Pp +Strings such as file or format names can normally be entered directly. If +the file name contains a character such as a comma which would otherwise serve +to separate file names, you may put the file name in double quotes. There +is no way to use a double quote character in a file name. +.Pp +You may include comments in linker scripts just as in C, delimited by +.Li /* +and +.Li */ . +As in C, comments are syntactically equivalent to whitespace. +.Pp +.Ss Simple Linker Script Example +Many linker scripts are fairly simple. +.Pp +The simplest possible linker script has just one command: +.Li SECTIONS . +You use the +.Li SECTIONS +command to describe the memory layout of the output file. +.Pp +The +.Li SECTIONS +command is a powerful command. Here we will describe a simple use of it. Let's +assume your program consists only of code, initialized data, and uninitialized +data. These will be in the +.Li .text , +.Li .data , +and +.Li .bss +sections, respectively. Let's assume further that these are the only sections +which appear in your input files. +.Pp +For this example, let's say that the code should be loaded at address 0x10000, +and that the data should start at address 0x8000000. Here is a linker script +which will do that: +.Bd -literal -offset indent +SECTIONS +{ + . = 0x10000; + .text : { *(.text) } + . = 0x8000000; + .data : { *(.data) } + .bss : { *(.bss) } +} +.Ed +.Pp +You write the +.Li SECTIONS +command as the keyword +.Li SECTIONS , +followed by a series of symbol assignments and output section descriptions +enclosed in curly braces. +.Pp +The first line inside the +.Li SECTIONS +command of the above example sets the value of the special symbol +.Li . , +which is the location counter. If you do not specify the address of an output +section in some other way (other ways are described later), the address is +set from the current value of the location counter. The location counter is +then incremented by the size of the output section. At the start of the +.Li SECTIONS +command, the location counter has the value +.Li 0 . +.Pp +The second line defines an output section, +.Li .text . +The colon is required syntax which may be ignored for now. Within the curly +braces after the output section name, you list the names of the input sections +which should be placed into this output section. The +.Li * +is a wildcard which matches any file name. The expression +.Li *(.text) +means all +.Li .text +input sections in all input files. +.Pp +Since the location counter is +.Li 0x10000 +when the output section +.Li .text +is defined, the linker will set the address of the +.Li .text +section in the output file to be +.Li 0x10000 . +.Pp +The remaining lines define the +.Li .data +and +.Li .bss +sections in the output file. The linker will place the +.Li .data +output section at address +.Li 0x8000000 . +After the linker places the +.Li .data +output section, the value of the location counter will be +.Li 0x8000000 +plus the size of the +.Li .data +output section. The effect is that the linker will place the +.Li .bss +output section immediately after the +.Li .data +output section in memory. +.Pp +The linker will ensure that each output section has the required alignment, +by increasing the location counter if necessary. In this example, the specified +addresses for the +.Li .text +and +.Li .data +sections will probably satisfy any alignment constraints, but the linker may +have to create a small gap between the +.Li .data +and +.Li .bss +sections. +.Pp +That's it! That's a simple and complete linker script. +.Pp +.Ss Simple Linker Script Commands +In this section we describe the simple linker script commands. +.Pp +.Em Setting the Entry Point +.Pp +The first instruction to execute in a program is called the +.Em entry point . +You can use the +.Li ENTRY +linker script command to set the entry point. The argument is a symbol name: +.Bd -literal -offset indent +ENTRY(symbol) +.Ed +.Pp +There are several ways to set the entry point. The linker will set the entry +point by trying each of the following methods in order, and stopping when +one of them succeeds: +.Bl -bullet +.It +the +.Li -e +.Va entry +command-line option; +.It +the +.Li ENTRY( Va symbol) +command in a linker script; +.It +the value of the symbol +.Li start , +if defined; +.It +the address of the first byte of the +.Li .text +section, if present; +.It +The address +.Li 0 . +.El +.Pp +.Em Commands Dealing with Files +.Pp +Several linker script commands deal with files. +.Pp +.Bl -tag -width Ds +.It INCLUDE Va filename +Include the linker script +.Va filename +at this point. The file will be searched for in the current directory, and +in any directory specified with the +.Op -L +option. You can nest calls to +.Li INCLUDE +up to 10 levels deep. +.Pp +.It INPUT( Va file, Va file, ...) +.It INPUT( Va file Va file ...) +The +.Li INPUT +command directs the linker to include the named files in the link, as though +they were named on the command line. +.Pp +For example, if you always want to include +.Pa subr.o +any time you do a link, but you can't be bothered to put it on every link +command line, then you can put +.Li INPUT (subr.o) +in your linker script. +.Pp +In fact, if you like, you can list all of your input files in the linker script, +and then invoke the linker with nothing but a +.Li -T +option. +.Pp +In case a +.Em sysroot prefix +is configured, and the filename starts with the +.Li / +character, and the script being processed was located inside the +.Em sysroot prefix , +the filename will be looked for in the +.Em sysroot prefix . +Otherwise, the linker will try to open the file in the current directory. +If it is not found, the linker will search through the archive library search +path. See the description of +.Li -L +in Options,,Command Line Options. +.Pp +If you use +.Li INPUT (-l Va file) , +.Xr ld +will transform the name to +.Li lib Va file.a , +as with the command line argument +.Li -l . +.Pp +When you use the +.Li INPUT +command in an implicit linker script, the files will be included in the link +at the point at which the linker script file is included. This can affect +archive searching. +.Pp +.It GROUP( Va file, Va file, ...) +.It GROUP( Va file Va file ...) +The +.Li GROUP +command is like +.Li INPUT , +except that the named files should all be archives, and they are searched +repeatedly until no new undefined references are created. See the description +of +.Li -( +in Options,,Command Line Options. +.Pp +.It AS_NEEDED( Va file, Va file, ...) +.It AS_NEEDED( Va file Va file ...) +This construct can appear only inside of the +.Li INPUT +or +.Li GROUP +commands, among other filenames. The files listed will be handled as if they +appear directly in the +.Li INPUT +or +.Li GROUP +commands, with the exception of ELF shared libraries, that will be added only +when they are actually needed. This construct essentially enables +.Op --as-needed +option for all the files listed inside of it and restores previous +.Op --as-needed +resp. +.Op --no-as-needed +setting afterwards. +.Pp +.It OUTPUT( Va filename) +The +.Li OUTPUT +command names the output file. Using +.Li OUTPUT( Va filename) +in the linker script is exactly like using +.Li -o Va filename +on the command line (see Section +.Dq Options ) . +If both are used, the command line option takes precedence. +.Pp +You can use the +.Li OUTPUT +command to define a default name for the output file other than the usual +default of +.Pa a.out . +.Pp +.It SEARCH_DIR( Va path) +The +.Li SEARCH_DIR +command adds +.Va path +to the list of paths where +.Xr ld +looks for archive libraries. Using +.Li SEARCH_DIR( Va path) +is exactly like using +.Li -L Va path +on the command line (see Section +.Dq Options ) . +If both are used, then the linker will search both paths. Paths specified +using the command line option are searched first. +.Pp +.It STARTUP( Va filename) +The +.Li STARTUP +command is just like the +.Li INPUT +command, except that +.Va filename +will become the first input file to be linked, as though it were specified +first on the command line. This may be useful when using a system in which +the entry point is always the start of the first file. +.El +.Pp +.Em Commands Dealing with Object File Formats +.Pp +A couple of linker script commands deal with object file formats. +.Pp +.Bl -tag -width Ds +.It OUTPUT_FORMAT( Va bfdname) +.It OUTPUT_FORMAT( Va default, Va big, Va little) +The +.Li OUTPUT_FORMAT +command names the BFD format to use for the output file (see Section +.Dq BFD ) . +Using +.Li OUTPUT_FORMAT( Va bfdname) +is exactly like using +.Li --oformat Va bfdname +on the command line (see Section +.Dq Options ) . +If both are used, the command line option takes precedence. +.Pp +You can use +.Li OUTPUT_FORMAT +with three arguments to use different formats based on the +.Li -EB +and +.Li -EL +command line options. This permits the linker script to set the output format +based on the desired endianness. +.Pp +If neither +.Li -EB +nor +.Li -EL +are used, then the output format will be the first argument, +.Va default . +If +.Li -EB +is used, the output format will be the second argument, +.Va big . +If +.Li -EL +is used, the output format will be the third argument, +.Va little . +.Pp +For example, the default linker script for the MIPS ELF target uses this command: +.Bd -literal -offset indent +OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips) +.Ed +This says that the default format for the output file is +.Li elf32-bigmips , +but if the user uses the +.Li -EL +command line option, the output file will be created in the +.Li elf32-littlemips +format. +.Pp +.It TARGET( Va bfdname) +The +.Li TARGET +command names the BFD format to use when reading input files. It affects subsequent +.Li INPUT +and +.Li GROUP +commands. This command is like using +.Li -b Va bfdname +on the command line (see Section +.Dq Options ) . +If the +.Li TARGET +command is used but +.Li OUTPUT_FORMAT +is not, then the last +.Li TARGET +command is also used to set the format for the output file.See Section +.Dq BFD . +.El +.Pp +.Em Other Linker Script Commands +.Pp +There are a few other linker scripts commands. +.Pp +.Bl -tag -width Ds +.It ASSERT( Va exp, Va message) +Ensure that +.Va exp +is non-zero. If it is zero, then exit the linker with an error code, and print +.Va message . +.Pp +.It EXTERN( Va symbol Va symbol ...) +Force +.Va symbol +to be entered in the output file as an undefined symbol. Doing this may, for +example, trigger linking of additional modules from standard libraries. You +may list several +.Va symbol +s for each +.Li EXTERN , +and you may use +.Li EXTERN +multiple times. This command has the same effect as the +.Li -u +command-line option. +.Pp +.It FORCE_COMMON_ALLOCATION +This command has the same effect as the +.Li -d +command-line option: to make +.Xr ld +assign space to common symbols even if a relocatable output file is specified +( +.Li -r ) . +.Pp +.It INHIBIT_COMMON_ALLOCATION +This command has the same effect as the +.Li --no-define-common +command-line option: to make +.Li ld +omit the assignment of addresses to common symbols even for a non-relocatable +output file. +.Pp +.It NOCROSSREFS( Va section Va section ...) +This command may be used to tell +.Xr ld +to issue an error about any references among certain output sections. +.Pp +In certain types of programs, particularly on embedded systems when using +overlays, when one section is loaded into memory, another section will not +be. Any direct references between the two sections would be errors. For example, +it would be an error if code in one section called a function defined in the +other section. +.Pp +The +.Li NOCROSSREFS +command takes a list of output section names. If +.Xr ld +detects any cross references between the sections, it reports an error and +returns a non-zero exit status. Note that the +.Li NOCROSSREFS +command uses output section names, not input section names. +.Pp +.It OUTPUT_ARCH( Va bfdarch) +Specify a particular output machine architecture. The argument is one of the +names used by the BFD library (see Section +.Dq BFD ) . +You can see the architecture of an object file by using the +.Li objdump +program with the +.Li -f +option. +.El +.Pp +.Ss Assigning Values to Symbols +You may assign a value to a symbol in a linker script. This will define the +symbol and place it into the symbol table with a global scope. +.Pp +.Em Simple Assignments +.Pp +You may assign to a symbol using any of the C assignment operators: +.Pp +.Bl -tag -width Ds +.It Va symbol = Va expression ; +.It Va symbol += Va expression ; +.It Va symbol -= Va expression ; +.It Va symbol *= Va expression ; +.It Va symbol /= Va expression ; +.It Va symbol <<= Va expression ; +.It Va symbol >>= Va expression ; +.It Va symbol &= Va expression ; +.It Va symbol |= Va expression ; +.El +.Pp +The first case will define +.Va symbol +to the value of +.Va expression . +In the other cases, +.Va symbol +must already be defined, and the value will be adjusted accordingly. +.Pp +The special symbol name +.Li . +indicates the location counter. You may only use this within a +.Li SECTIONS +command.See Section +.Dq Location Counter . +.Pp +The semicolon after +.Va expression +is required. +.Pp +Expressions are defined below; see Expressions. +.Pp +You may write symbol assignments as commands in their own right, or as statements +within a +.Li SECTIONS +command, or as part of an output section description in a +.Li SECTIONS +command. +.Pp +The section of the symbol will be set from the section of the expression; +for more information, see Expression Section. +.Pp +Here is an example showing the three different places that symbol assignments +may be used: +.Pp +.Bd -literal -offset indent +floating_point = 0; +SECTIONS +{ + .text : + { + *(.text) + _etext = .; + } + _bdata = (. + 3) & ~ 3; + .data : { *(.data) } +} +.Ed +In this example, the symbol +.Li floating_point +will be defined as zero. The symbol +.Li _etext +will be defined as the address following the last +.Li .text +input section. The symbol +.Li _bdata +will be defined as the address following the +.Li .text +output section aligned upward to a 4 byte boundary. +.Pp +.Em PROVIDE +.Pp +In some cases, it is desirable for a linker script to define a symbol only +if it is referenced and is not defined by any object included in the link. +For example, traditional linkers defined the symbol +.Li etext . +However, ANSI C requires that the user be able to use +.Li etext +as a function name without encountering an error. The +.Li PROVIDE +keyword may be used to define a symbol, such as +.Li etext , +only if it is referenced but not defined. The syntax is +.Li PROVIDE( Va symbol = Va expression) . +.Pp +Here is an example of using +.Li PROVIDE +to define +.Li etext : +.Bd -literal -offset indent +SECTIONS +{ + .text : + { + *(.text) + _etext = .; + PROVIDE(etext = .); + } +} +.Ed +.Pp +In this example, if the program defines +.Li _etext +(with a leading underscore), the linker will give a multiple definition error. +If, on the other hand, the program defines +.Li etext +(with no leading underscore), the linker will silently use the definition +in the program. If the program references +.Li etext +but does not define it, the linker will use the definition in the linker script. +.Pp +.Em PROVIDE_HIDDEN +.Pp +Similar to +.Li PROVIDE . +For ELF targeted ports, the symbol will be hidden and won't be exported. +.Pp +.Em Source Code Reference +.Pp +Accessing a linker script defined variable from source code is not intuitive. +In particular a linker script symbol is not equivalent to a variable declaration +in a high level language, it is instead a symbol that does not have a value. +.Pp +Before going further, it is important to note that compilers often transform +names in the source code into different names when they are stored in the +symbol table. For example, Fortran compilers commonly prepend or append an +underscore, and C++ performs extensive +.Li name mangling . +Therefore there might be a discrepancy between the name of a variable as it +is used in source code and the name of the same variable as it is defined +in a linker script. For example in C a linker script variable might be referred +to as: +.Pp +.Bd -literal -offset indent + extern int foo; +.Ed +.Pp +But in the linker script it might be defined as: +.Pp +.Bd -literal -offset indent + _foo = 1000; +.Ed +.Pp +In the remaining examples however it is assumed that no name transformation +has taken place. +.Pp +When a symbol is declared in a high level language such as C, two things happen. +The first is that the compiler reserves enough space in the program's memory +to hold the +.Em value +of the symbol. The second is that the compiler creates an entry in the program's +symbol table which holds the symbol's +.Em address . +ie the symbol table contains the address of the block of memory holding the +symbol's value. So for example the following C declaration, at file scope: +.Pp +.Bd -literal -offset indent + int foo = 1000; +.Ed +.Pp +creates a entry called +.Li foo +in the symbol table. This entry holds the address of an +.Li int +sized block of memory where the number 1000 is initially stored. +.Pp +When a program references a symbol the compiler generates code that first +accesses the symbol table to find the address of the symbol's memory block +and then code to read the value from that memory block. So: +.Pp +.Bd -literal -offset indent + foo = 1; +.Ed +.Pp +looks up the symbol +.Li foo +in the symbol table, gets the address associated with this symbol and then +writes the value 1 into that address. Whereas: +.Pp +.Bd -literal -offset indent + int * a = & foo; +.Ed +.Pp +looks up the symbol +.Li foo +in the symbol table, gets it address and then copies this address into the +block of memory associated with the variable +.Li a . +.Pp +Linker scripts symbol declarations, by contrast, create an entry in the symbol +table but do not assign any memory to them. Thus they are an address without +a value. So for example the linker script definition: +.Pp +.Bd -literal -offset indent + foo = 1000; +.Ed +.Pp +creates an entry in the symbol table called +.Li foo +which holds the address of memory location 1000, but nothing special is stored +at address 1000. This means that you cannot access the +.Em value +of a linker script defined symbol - it has no value - all you can do is access +the +.Em address +of a linker script defined symbol. +.Pp +Hence when you are using a linker script defined symbol in source code you +should always take the address of the symbol, and never attempt to use its +value. For example suppose you want to copy the contents of a section of memory +called .ROM into a section called .FLASH and the linker script contains these +declarations: +.Pp +.Bd -literal -offset indent + + start_of_ROM = .ROM; + end_of_ROM = .ROM + sizeof (.ROM) - 1; + start_of_FLASH = .FLASH; + +.Ed +.Pp +Then the C source code to perform the copy would be: +.Pp +.Bd -literal -offset indent + + extern char start_of_ROM, end_of_ROM, start_of_FLASH; + + memcpy (& start_of_FLASH, & start_of_ROM, & end_of_ROM - & start_of_ROM); + +.Ed +.Pp +Note the use of the +.Li & +operators. These are correct. +.Pp +.Ss SECTIONS Command +The +.Li SECTIONS +command tells the linker how to map input sections into output sections, and +how to place the output sections in memory. +.Pp +The format of the +.Li SECTIONS +command is: +.Bd -literal -offset indent +SECTIONS +{ + sections-command + sections-command + ... +} +.Ed +.Pp +Each +.Va sections-command +may of be one of the following: +.Pp +.Bl -bullet +.It +an +.Li ENTRY +command (see Section +.Dq Entry Point ) +.It +a symbol assignment (see Section +.Dq Assignments ) +.It +an output section description +.It +an overlay description +.El +.Pp +The +.Li ENTRY +command and symbol assignments are permitted inside the +.Li SECTIONS +command for convenience in using the location counter in those commands. This +can also make the linker script easier to understand because you can use those +commands at meaningful points in the layout of the output file. +.Pp +Output section descriptions and overlay descriptions are described below. +.Pp +If you do not use a +.Li SECTIONS +command in your linker script, the linker will place each input section into +an identically named output section in the order that the sections are first +encountered in the input files. If all input sections are present in the first +file, for example, the order of sections in the output file will match the +order in the first input file. The first section will be at address zero. +.Pp +.Em Output Section Description +.Pp +The full description of an output section looks like this: +.Bd -literal -offset indent + +section [address] [(type)] : + [AT(lma)] [ALIGN(section_align)] [SUBALIGN(subsection_align)] + { + output-section-command + output-section-command + ... + } [>region] [AT>lma_region] [:phdr :phdr ...] [=fillexp] + +.Ed +.Pp +Most output sections do not use most of the optional section attributes. +.Pp +The whitespace around +.Va section +is required, so that the section name is unambiguous. The colon and the curly +braces are also required. The line breaks and other white space are optional. +.Pp +Each +.Va output-section-command +may be one of the following: +.Pp +.Bl -bullet +.It +a symbol assignment (see Section +.Dq Assignments ) +.It +an input section description (see Section +.Dq Input Section ) +.It +data values to include directly (see Section +.Dq Output Section Data ) +.It +a special output section keyword (see Section +.Dq Output Section Keywords ) +.El +.Pp +.Em Output Section Name +.Pp +The name of the output section is +.Va section . +.Va section +must meet the constraints of your output format. In formats which only support +a limited number of sections, such as +.Li a.out , +the name must be one of the names supported by the format ( +.Li a.out , +for example, allows only +.Li .text , +.Li .data +or +.Li .bss ) . +If the output format supports any number of sections, but with numbers and +not names (as is the case for Oasys), the name should be supplied as a quoted +numeric string. A section name may consist of any sequence of characters, +but a name which contains any unusual characters such as commas must be quoted. +.Pp +The output section name +.Li /DISCARD/ +is special; Output Section Discarding. +.Pp +.Em Output Section Address +.Pp +The +.Va address +is an expression for the VMA (the virtual memory address) of the output section. +If you do not provide +.Va address , +the linker will set it based on +.Va region +if present, or otherwise based on the current value of the location counter. +.Pp +If you provide +.Va address , +the address of the output section will be set to precisely that. If you provide +neither +.Va address +nor +.Va region , +then the address of the output section will be set to the current value of +the location counter aligned to the alignment requirements of the output section. +The alignment requirement of the output section is the strictest alignment +of any input section contained within the output section. +.Pp +For example, +.Bd -literal -offset indent +\&.text . : { *(.text) } +.Ed +and +.Bd -literal -offset indent +\&.text : { *(.text) } +.Ed +are subtly different. The first will set the address of the +.Li .text +output section to the current value of the location counter. The second will +set it to the current value of the location counter aligned to the strictest +alignment of a +.Li .text +input section. +.Pp +The +.Va address +may be an arbitrary expression; Expressions. For example, if you want to align +the section on a 0x10 byte boundary, so that the lowest four bits of the section +address are zero, you could do something like this: +.Bd -literal -offset indent +\&.text ALIGN(0x10) : { *(.text) } +.Ed +This works because +.Li ALIGN +returns the current location counter aligned upward to the specified value. +.Pp +Specifying +.Va address +for a section will change the value of the location counter. +.Pp +.Em Input Section Description +.Pp +The most common output section command is an input section description. +.Pp +The input section description is the most basic linker script operation. You +use output sections to tell the linker how to lay out your program in memory. +You use input section descriptions to tell the linker how to map the input +files into your memory layout. +.Pp +.No Input Section Basics +.Pp +An input section description consists of a file name optionally followed by +a list of section names in parentheses. +.Pp +The file name and the section name may be wildcard patterns, which we describe +further below (see Section +.Dq Input Section Wildcards ) . +.Pp +The most common input section description is to include all input sections +with a particular name in the output section. For example, to include all +input +.Li .text +sections, you would write: +.Bd -literal -offset indent +*(.text) +.Ed +Here the +.Li * +is a wildcard which matches any file name. To exclude a list of files from +matching the file name wildcard, EXCLUDE_FILE may be used to match all files +except the ones specified in the EXCLUDE_FILE list. For example: +.Bd -literal -offset indent +(*(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors)) +.Ed +will cause all .ctors sections from all files except +.Pa crtend.o +and +.Pa otherfile.o +to be included. +.Pp +There are two ways to include more than one section: +.Bd -literal -offset indent +*(.text .rdata) +*(.text) *(.rdata) +.Ed +The difference between these is the order in which the +.Li .text +and +.Li .rdata +input sections will appear in the output section. In the first example, they +will be intermingled, appearing in the same order as they are found in the +linker input. In the second example, all +.Li .text +input sections will appear first, followed by all +.Li .rdata +input sections. +.Pp +You can specify a file name to include sections from a particular file. You +would do this if one or more of your files contain special data that needs +to be at a particular location in memory. For example: +.Bd -literal -offset indent +data.o(.data) +.Ed +.Pp +If you use a file name without a list of sections, then all sections in the +input file will be included in the output section. This is not commonly done, +but it may by useful on occasion. For example: +.Bd -literal -offset indent +data.o +.Ed +.Pp +When you use a file name which does not contain any wild card characters, +the linker will first see if you also specified the file name on the linker +command line or in an +.Li INPUT +command. If you did not, the linker will attempt to open the file as an input +file, as though it appeared on the command line. Note that this differs from +an +.Li INPUT +command, because the linker will not search for the file in the archive search +path. +.Pp +.No Input Section Wildcard Patterns +.Pp +In an input section description, either the file name or the section name +or both may be wildcard patterns. +.Pp +The file name of +.Li * +seen in many examples is a simple wildcard pattern for the file name. +.Pp +The wildcard patterns are like those used by the Unix shell. +.Pp +.Bl -tag -width Ds +.It * +matches any number of characters +.It ? +matches any single character +.It [ Va chars] +matches a single instance of any of the +.Va chars ; +the +.Li - +character may be used to specify a range of characters, as in +.Li [a-z] +to match any lower case letter +.It \e +quotes the following character +.El +.Pp +When a file name is matched with a wildcard, the wildcard characters will +not match a +.Li / +character (used to separate directory names on Unix). A pattern consisting +of a single +.Li * +character is an exception; it will always match any file name, whether it +contains a +.Li / +or not. In a section name, the wildcard characters will match a +.Li / +character. +.Pp +File name wildcard patterns only match files which are explicitly specified +on the command line or in an +.Li INPUT +command. The linker does not search directories to expand wildcards. +.Pp +If a file name matches more than one wildcard pattern, or if a file name appears +explicitly and is also matched by a wildcard pattern, the linker will use +the first match in the linker script. For example, this sequence of input +section descriptions is probably in error, because the +.Pa data.o +rule will not be used: +.Bd -literal -offset indent +\&.data : { *(.data) } +\&.data1 : { data.o(.data) } +.Ed +.Pp +Normally, the linker will place files and sections matched by wildcards in +the order in which they are seen during the link. You can change this by using +the +.Li SORT_BY_NAME +keyword, which appears before a wildcard pattern in parentheses (e.g., +.Li SORT_BY_NAME(.text*) ) . +When the +.Li SORT_BY_NAME +keyword is used, the linker will sort the files or sections into ascending +order by name before placing them in the output file. +.Pp +.Li SORT_BY_ALIGNMENT +is very similar to +.Li SORT_BY_NAME . +The difference is +.Li SORT_BY_ALIGNMENT +will sort sections into ascending order by alignment before placing them in +the output file. +.Pp +.Li SORT +is an alias for +.Li SORT_BY_NAME . +.Pp +When there are nested section sorting commands in linker script, there can +be at most 1 level of nesting for section sorting commands. +.Pp +.Bl -enum +.It +.Li SORT_BY_NAME +( +.Li SORT_BY_ALIGNMENT +(wildcard section pattern)). It will sort the input sections by name first, +then by alignment if 2 sections have the same name. +.It +.Li SORT_BY_ALIGNMENT +( +.Li SORT_BY_NAME +(wildcard section pattern)). It will sort the input sections by alignment +first, then by name if 2 sections have the same alignment. +.It +.Li SORT_BY_NAME +( +.Li SORT_BY_NAME +(wildcard section pattern)) is treated the same as +.Li SORT_BY_NAME +(wildcard section pattern). +.It +.Li SORT_BY_ALIGNMENT +( +.Li SORT_BY_ALIGNMENT +(wildcard section pattern)) is treated the same as +.Li SORT_BY_ALIGNMENT +(wildcard section pattern). +.It +All other nested section sorting commands are invalid. +.El +.Pp +When both command line section sorting option and linker script section sorting +command are used, section sorting command always takes precedence over the +command line option. +.Pp +If the section sorting command in linker script isn't nested, the command +line option will make the section sorting command to be treated as nested +sorting command. +.Pp +.Bl -enum +.It +.Li SORT_BY_NAME +(wildcard section pattern ) with +.Op --sort-sections alignment +is equivalent to +.Li SORT_BY_NAME +( +.Li SORT_BY_ALIGNMENT +(wildcard section pattern)). +.It +.Li SORT_BY_ALIGNMENT +(wildcard section pattern) with +.Op --sort-section name +is equivalent to +.Li SORT_BY_ALIGNMENT +( +.Li SORT_BY_NAME +(wildcard section pattern)). +.El +.Pp +If the section sorting command in linker script is nested, the command line +option will be ignored. +.Pp +If you ever get confused about where input sections are going, use the +.Li -M +linker option to generate a map file. The map file shows precisely how input +sections are mapped to output sections. +.Pp +This example shows how wildcard patterns might be used to partition files. +This linker script directs the linker to place all +.Li .text +sections in +.Li .text +and all +.Li .bss +sections in +.Li .bss . +The linker will place the +.Li .data +section from all files beginning with an upper case character in +.Li .DATA ; +for all other files, the linker will place the +.Li .data +section in +.Li .data . +.Bd -literal -offset indent + +SECTIONS { + .text : { *(.text) } + .DATA : { [A-Z]*(.data) } + .data : { *(.data) } + .bss : { *(.bss) } +} + +.Ed +.Pp +.No Input Section for Common Symbols +.Pp +A special notation is needed for common symbols, because in many object file +formats common symbols do not have a particular input section. The linker +treats common symbols as though they are in an input section named +.Li COMMON . +.Pp +You may use file names with the +.Li COMMON +section just as with any other input sections. You can use this to place common +symbols from a particular input file in one section while common symbols from +other input files are placed in another section. +.Pp +In most cases, common symbols in input files will be placed in the +.Li .bss +section in the output file. For example: +.Bd -literal -offset indent +\&.bss { *(.bss) *(COMMON) } +.Ed +.Pp +Some object file formats have more than one type of common symbol. For example, +the MIPS ELF object file format distinguishes standard common symbols and +small common symbols. In this case, the linker will use a different special +section name for other types of common symbols. In the case of MIPS ELF, the +linker uses +.Li COMMON +for standard common symbols and +.Li .scommon +for small common symbols. This permits you to map the different types of common +symbols into memory at different locations. +.Pp +You will sometimes see +.Li [COMMON] +in old linker scripts. This notation is now considered obsolete. It is equivalent +to +.Li *(COMMON) . +.Pp +.No Input Section and Garbage Collection +.Pp +When link-time garbage collection is in use ( +.Li --gc-sections ) , +it is often useful to mark sections that should not be eliminated. This is +accomplished by surrounding an input section's wildcard entry with +.Li KEEP() , +as in +.Li KEEP(*(.init)) +or +.Li KEEP(SORT_BY_NAME(*)(.ctors)) . +.Pp +.No Input Section Example +.Pp +The following example is a complete linker script. It tells the linker to +read all of the sections from file +.Pa all.o +and place them at the start of output section +.Li outputa +which starts at location +.Li 0x10000 . +All of section +.Li .input1 +from file +.Pa foo.o +follows immediately, in the same output section. All of section +.Li .input2 +from +.Pa foo.o +goes into output section +.Li outputb , +followed by section +.Li .input1 +from +.Pa foo1.o . +All of the remaining +.Li .input1 +and +.Li .input2 +sections from any files are written to output section +.Li outputc . +.Pp +.Bd -literal -offset indent + +SECTIONS { + outputa 0x10000 : + { + all.o + foo.o (.input1) + } + + + outputb : + { + foo.o (.input2) + foo1.o (.input1) + } + + + outputc : + { + *(.input1) + *(.input2) + } +} + +.Ed +.Pp +.Em Output Section Data +.Pp +You can include explicit bytes of data in an output section by using +.Li BYTE , +.Li SHORT , +.Li LONG , +.Li QUAD , +or +.Li SQUAD +as an output section command. Each keyword is followed by an expression in +parentheses providing the value to store (see Section +.Dq Expressions ) . +The value of the expression is stored at the current value of the location +counter. +.Pp +The +.Li BYTE , +.Li SHORT , +.Li LONG , +and +.Li QUAD +commands store one, two, four, and eight bytes (respectively). After storing +the bytes, the location counter is incremented by the number of bytes stored. +.Pp +For example, this will store the byte 1 followed by the four byte value of +the symbol +.Li addr : +.Bd -literal -offset indent +BYTE(1) +LONG(addr) +.Ed +.Pp +When using a 64 bit host or target, +.Li QUAD +and +.Li SQUAD +are the same; they both store an 8 byte, or 64 bit, value. When both host +and target are 32 bits, an expression is computed as 32 bits. In this case +.Li QUAD +stores a 32 bit value zero extended to 64 bits, and +.Li SQUAD +stores a 32 bit value sign extended to 64 bits. +.Pp +If the object file format of the output file has an explicit endianness, which +is the normal case, the value will be stored in that endianness. When the +object file format does not have an explicit endianness, as is true of, for +example, S-records, the value will be stored in the endianness of the first +input object file. +.Pp +Note---these commands only work inside a section description and not between +them, so the following will produce an error from the linker: +.Bd -literal -offset indent +SECTIONS { .text : { *(.text) } LONG(1) .data : { *(.data) } } +.Ed +whereas this will work: +.Bd -literal -offset indent +SECTIONS { .text : { *(.text) ; LONG(1) } .data : { *(.data) } } +.Ed +.Pp +You may use the +.Li FILL +command to set the fill pattern for the current section. It is followed by +an expression in parentheses. Any otherwise unspecified regions of memory +within the section (for example, gaps left due to the required alignment of +input sections) are filled with the value of the expression, repeated as necessary. +A +.Li FILL +statement covers memory locations after the point at which it occurs in the +section definition; by including more than one +.Li FILL +statement, you can have different fill patterns in different parts of an output +section. +.Pp +This example shows how to fill unspecified regions of memory with the value +.Li 0x90 : +.Bd -literal -offset indent +FILL(0x90909090) +.Ed +.Pp +The +.Li FILL +command is similar to the +.Li = Va fillexp +output section attribute, but it only affects the part of the section following +the +.Li FILL +command, rather than the entire section. If both are used, the +.Li FILL +command takes precedence.See Section +.Dq Output Section Fill , +for details on the fill expression. +.Pp +.Em Output Section Keywords +.Pp +There are a couple of keywords which can appear as output section commands. +.Pp +.Bl -tag -width Ds +.It CREATE_OBJECT_SYMBOLS +The command tells the linker to create a symbol for each input file. The name +of each symbol will be the name of the corresponding input file. The section +of each symbol will be the output section in which the +.Li CREATE_OBJECT_SYMBOLS +command appears. +.Pp +This is conventional for the a.out object file format. It is not normally +used for any other object file format. +.Pp +.It CONSTRUCTORS +When linking using the a.out object file format, the linker uses an unusual +set construct to support C++ global constructors and destructors. When linking +object file formats which do not support arbitrary sections, such as ECOFF +and XCOFF, the linker will automatically recognize C++ global constructors +and destructors by name. For these object file formats, the +.Li CONSTRUCTORS +command tells the linker to place constructor information in the output section +where the +.Li CONSTRUCTORS +command appears. The +.Li CONSTRUCTORS +command is ignored for other object file formats. +.Pp +The symbol +.Li __CTOR_LIST__ +marks the start of the global constructors, and the symbol +.Li __CTOR_END__ +marks the end. Similarly, +.Li __DTOR_LIST__ +and +.Li __DTOR_END__ +mark the start and end of the global destructors. The first word in the list +is the number of entries, followed by the address of each constructor or destructor, +followed by a zero word. The compiler must arrange to actually run the code. +For these object file formats GNU C++ normally calls constructors from a subroutine +.Li __main ; +a call to +.Li __main +is automatically inserted into the startup code for +.Li main . +GNU C++ normally runs destructors either by using +.Li atexit , +or directly from the function +.Li exit . +.Pp +For object file formats such as +.Li COFF +or +.Li ELF +which support arbitrary section names, GNU C++ will normally arrange to put +the addresses of global constructors and destructors into the +.Li .ctors +and +.Li .dtors +sections. Placing the following sequence into your linker script will build +the sort of table which the GNU C++ runtime code expects to see. +.Pp +.Bd -literal -offset indent + __CTOR_LIST__ = .; + LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2) + *(.ctors) + LONG(0) + __CTOR_END__ = .; + __DTOR_LIST__ = .; + LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2) + *(.dtors) + LONG(0) + __DTOR_END__ = .; +.Ed +.Pp +If you are using the GNU C++ support for initialization priority, which provides +some control over the order in which global constructors are run, you must +sort the constructors at link time to ensure that they are executed in the +correct order. When using the +.Li CONSTRUCTORS +command, use +.Li SORT_BY_NAME(CONSTRUCTORS) +instead. When using the +.Li .ctors +and +.Li .dtors +sections, use +.Li *(SORT_BY_NAME(.ctors)) +and +.Li *(SORT_BY_NAME(.dtors)) +instead of just +.Li *(.ctors) +and +.Li *(.dtors) . +.Pp +Normally the compiler and linker will handle these issues automatically, and +you will not need to concern yourself with them. However, you may need to +consider this if you are using C++ and writing your own linker scripts. +.Pp +.El +.Em Output Section Discarding +.Pp +The linker will not create output sections with no contents. This is for convenience +when referring to input sections that may or may not be present in any of +the input files. For example: +.Bd -literal -offset indent +\&.foo : { *(.foo) } +.Ed +will only create a +.Li .foo +section in the output file if there is a +.Li .foo +section in at least one input file, and if the input sections are not all +empty. Other link script directives that allocate space in an output section +will also create the output section. +.Pp +The linker will ignore address assignments (see Section +.Dq Output Section Address ) +on discarded output sections, except when the linker script defines symbols +in the output section. In that case the linker will obey the address assignments, +possibly advancing dot even though the section is discarded. +.Pp +The special output section name +.Li /DISCARD/ +may be used to discard input sections. Any input sections which are assigned +to an output section named +.Li /DISCARD/ +are not included in the output file. +.Pp +.Em Output Section Attributes +.Pp +We showed above that the full description of an output section looked like +this: +.Bd -literal -offset indent + +section [address] [(type)] : + [AT(lma)] [ALIGN(section_align)] [SUBALIGN(subsection_align)] + { + output-section-command + output-section-command + ... + } [>region] [AT>lma_region] [:phdr :phdr ...] [=fillexp] + +.Ed +We've already described +.Va section , +.Va address , +and +.Va output-section-command . +In this section we will describe the remaining section attributes. +.Pp +.No Output Section Type +.Pp +Each output section may have a type. The type is a keyword in parentheses. +The following types are defined: +.Pp +.Bl -tag -width Ds +.It NOLOAD +The section should be marked as not loadable, so that it will not be loaded +into memory when the program is run. +.It DSECT +.It COPY +.It INFO +.It OVERLAY +These type names are supported for backward compatibility, and are rarely +used. They all have the same effect: the section should be marked as not allocatable, +so that no memory is allocated for the section when the program is run. +.El +.Pp +The linker normally sets the attributes of an output section based on the +input sections which map into it. You can override this by using the section +type. For example, in the script sample below, the +.Li ROM +section is addressed at memory location +.Li 0 +and does not need to be loaded when the program is run. The contents of the +.Li ROM +section will appear in the linker output file as usual. +.Bd -literal -offset indent + +SECTIONS { + ROM 0 (NOLOAD) : { ... } + ... +} + +.Ed +.Pp +.No Output Section LMA +.Pp +Every section has a virtual address (VMA) and a load address (LMA); see Basic +Script Concepts. The address expression which may appear in an output section +description sets the VMA (see Section +.Dq Output Section Address ) . +.Pp +The expression +.Va lma +that follows the +.Li AT +keyword specifies the load address of the section. +.Pp +Alternatively, with +.Li AT> Va lma_region +expression, you may specify a memory region for the section's load address.See Section +.Dq MEMORY . +Note that if the section has not had a VMA assigned to it then the linker +will use the +.Va lma_region +as the VMA region as well. +.Pp +If neither +.Li AT +nor +.Li AT> +is specified for an allocatable section, the linker will set the LMA such +that the difference between VMA and LMA for the section is the same as the +preceding output section in the same region. If there is no preceding output +section or the section is not allocatable, the linker will set the LMA equal +to the VMA.See Section +.Dq Output Section Region . +.Pp +This feature is designed to make it easy to build a ROM image. For example, +the following linker script creates three output sections: one called +.Li .text , +which starts at +.Li 0x1000 , +one called +.Li .mdata , +which is loaded at the end of the +.Li .text +section even though its VMA is +.Li 0x2000 , +and one called +.Li .bss +to hold uninitialized data at address +.Li 0x3000 . +The symbol +.Li _data +is defined with the value +.Li 0x2000 , +which shows that the location counter holds the VMA value, not the LMA value. +.Pp +.Bd -literal -offset indent + +SECTIONS + { + .text 0x1000 : { *(.text) _etext = . ; } + .mdata 0x2000 : + AT ( ADDR (.text) + SIZEOF (.text) ) + { _data = . ; *(.data); _edata = . ; } + .bss 0x3000 : + { _bstart = . ; *(.bss) *(COMMON) ; _bend = . ;} +} + +.Ed +.Pp +The run-time initialization code for use with a program generated with this +linker script would include something like the following, to copy the initialized +data from the ROM image to its runtime address. Notice how this code takes +advantage of the symbols defined by the linker script. +.Pp +.Bd -literal -offset indent + +extern char _etext, _data, _edata, _bstart, _bend; +char *src = &_etext; +char *dst = &_data; + +/* ROM has data at end of text; copy it. */ +while (dst < &_edata) { + *dst++ = *src++; +} + +/* Zero bss */ +for (dst = &_bstart; dst< &_bend; dst++) + *dst = 0; + +.Ed +.Pp +.No Forced Output Alignment +.Pp +You can increase an output section's alignment by using ALIGN. +.Pp +.No Forced Input Alignment +.Pp +You can force input section alignment within an output section by using SUBALIGN. +The value specified overrides any alignment given by input sections, whether +larger or smaller. +.Pp +.No Output Section Region +.Pp +You can assign a section to a previously defined region of memory by using +.Li > Va region . +See Section.Dq MEMORY . +.Pp +Here is a simple example: +.Bd -literal -offset indent + +MEMORY { rom : ORIGIN = 0x1000, LENGTH = 0x1000 } +SECTIONS { ROM : { *(.text) } >rom } + +.Ed +.Pp +.No Output Section Phdr +.Pp +You can assign a section to a previously defined program segment by using +.Li : Va phdr . +See Section.Dq PHDRS . +If a section is assigned to one or more segments, then all subsequent allocated +sections will be assigned to those segments as well, unless they use an explicitly +.Li : Va phdr +modifier. You can use +.Li :NONE +to tell the linker to not put the section in any segment at all. +.Pp +Here is a simple example: +.Bd -literal -offset indent + +PHDRS { text PT_LOAD ; } +SECTIONS { .text : { *(.text) } :text } + +.Ed +.Pp +.No Output Section Fill +.Pp +You can set the fill pattern for an entire section by using +.Li = Va fillexp . +.Va fillexp +is an expression (see Section +.Dq Expressions ) . +Any otherwise unspecified regions of memory within the output section (for +example, gaps left due to the required alignment of input sections) will be +filled with the value, repeated as necessary. If the fill expression is a +simple hex number, ie. a string of hex digit starting with +.Li 0x +and without a trailing +.Li k +or +.Li M , +then an arbitrarily long sequence of hex digits can be used to specify the +fill pattern; Leading zeros become part of the pattern too. For all other +cases, including extra parentheses or a unary +.Li + , +the fill pattern is the four least significant bytes of the value of the expression. +In all cases, the number is big-endian. +.Pp +You can also change the fill value with a +.Li FILL +command in the output section commands; (see Section +.Dq Output Section Data ) . +.Pp +Here is a simple example: +.Bd -literal -offset indent + +SECTIONS { .text : { *(.text) } =0x90909090 } + +.Ed +.Pp +.Em Overlay Description +.Pp +An overlay description provides an easy way to describe sections which are +to be loaded as part of a single memory image but are to be run at the same +memory address. At run time, some sort of overlay manager will copy the overlaid +sections in and out of the runtime memory address as required, perhaps by +simply manipulating addressing bits. This approach can be useful, for example, +when a certain region of memory is faster than another. +.Pp +Overlays are described using the +.Li OVERLAY +command. The +.Li OVERLAY +command is used within a +.Li SECTIONS +command, like an output section description. The full syntax of the +.Li OVERLAY +command is as follows: +.Bd -literal -offset indent + +OVERLAY [start] : [NOCROSSREFS] [AT ( ldaddr )] + { + secname1 + { + output-section-command + output-section-command + ... + } [:phdr...] [=fill] + secname2 + { + output-section-command + output-section-command + ... + } [:phdr...] [=fill] + ... + } [>region] [:phdr...] [=fill] + +.Ed +.Pp +Everything is optional except +.Li OVERLAY +(a keyword), and each section must have a name ( +.Va secname1 +and +.Va secname2 +above). The section definitions within the +.Li OVERLAY +construct are identical to those within the general +.Li SECTIONS +contruct (see Section +.Dq SECTIONS ) , +except that no addresses and no memory regions may be defined for sections +within an +.Li OVERLAY . +.Pp +The sections are all defined with the same starting address. The load addresses +of the sections are arranged such that they are consecutive in memory starting +at the load address used for the +.Li OVERLAY +as a whole (as with normal section definitions, the load address is optional, +and defaults to the start address; the start address is also optional, and +defaults to the current value of the location counter). +.Pp +If the +.Li NOCROSSREFS +keyword is used, and there any references among the sections, the linker will +report an error. Since the sections all run at the same address, it normally +does not make sense for one section to refer directly to another.See Section +.Dq Miscellaneous Commands . +.Pp +For each section within the +.Li OVERLAY , +the linker automatically provides two symbols. The symbol +.Li __load_start_ Va secname +is defined as the starting load address of the section. The symbol +.Li __load_stop_ Va secname +is defined as the final load address of the section. Any characters within +.Va secname +which are not legal within C identifiers are removed. C (or assembler) code +may use these symbols to move the overlaid sections around as necessary. +.Pp +At the end of the overlay, the value of the location counter is set to the +start address of the overlay plus the size of the largest section. +.Pp +Here is an example. Remember that this would appear inside a +.Li SECTIONS +construct. +.Bd -literal -offset indent + + OVERLAY 0x1000 : AT (0x4000) + { + .text0 { o1/*.o(.text) } + .text1 { o2/*.o(.text) } + } + +.Ed +This will define both +.Li .text0 +and +.Li .text1 +to start at address 0x1000. +.Li .text0 +will be loaded at address 0x4000, and +.Li .text1 +will be loaded immediately after +.Li .text0 . +The following symbols will be defined if referenced: +.Li __load_start_text0 , +.Li __load_stop_text0 , +.Li __load_start_text1 , +.Li __load_stop_text1 . +.Pp +C code to copy overlay +.Li .text1 +into the overlay area might look like the following. +.Pp +.Bd -literal -offset indent + + extern char __load_start_text1, __load_stop_text1; + memcpy ((char *) 0x1000, &__load_start_text1, + &__load_stop_text1 - &__load_start_text1); + +.Ed +.Pp +Note that the +.Li OVERLAY +command is just syntactic sugar, since everything it does can be done using +the more basic commands. The above example could have been written identically +as follows. +.Pp +.Bd -literal -offset indent + + .text0 0x1000 : AT (0x4000) { o1/*.o(.text) } + PROVIDE (__load_start_text0 = LOADADDR (.text0)); + PROVIDE (__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0)); + .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) { o2/*.o(.text) } + PROVIDE (__load_start_text1 = LOADADDR (.text1)); + PROVIDE (__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1)); + . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1)); + +.Ed +.Pp +.Ss MEMORY Command +The linker's default configuration permits allocation of all available memory. +You can override this by using the +.Li MEMORY +command. +.Pp +The +.Li MEMORY +command describes the location and size of blocks of memory in the target. +You can use it to describe which memory regions may be used by the linker, +and which memory regions it must avoid. You can then assign sections to particular +memory regions. The linker will set section addresses based on the memory +regions, and will warn about regions that become too full. The linker will +not shuffle sections around to fit into the available regions. +.Pp +A linker script may contain at most one use of the +.Li MEMORY +command. However, you can define as many blocks of memory within it as you +wish. The syntax is: +.Bd -literal -offset indent + +MEMORY + { + name [(attr)] : ORIGIN = origin, LENGTH = len + ... + } + +.Ed +.Pp +The +.Va name +is a name used in the linker script to refer to the region. The region name +has no meaning outside of the linker script. Region names are stored in a +separate name space, and will not conflict with symbol names, file names, +or section names. Each memory region must have a distinct name. +.Pp +The +.Va attr +string is an optional list of attributes that specify whether to use a particular +memory region for an input section which is not explicitly mapped in the linker +script. As described in SECTIONS, if you do not specify an output section +for some input section, the linker will create an output section with the +same name as the input section. If you define region attributes, the linker +will use them to select the memory region for the output section that it creates. +.Pp +The +.Va attr +string must consist only of the following characters: +.Bl -tag -width Ds +.It R +Read-only section +.It W +Read/write section +.It X +Executable section +.It A +Allocatable section +.It I +Initialized section +.It L +Same as +.Li I +.It ! +Invert the sense of any of the preceding attributes +.El +.Pp +If a unmapped section matches any of the listed attributes other than +.Li ! , +it will be placed in the memory region. The +.Li ! +attribute reverses this test, so that an unmapped section will be placed in +the memory region only if it does not match any of the listed attributes. +.Pp +The +.Va origin +is an numerical expression for the start address of the memory region. The +expression must evaluate to a constant and it cannot involve any symbols. +The keyword +.Li ORIGIN +may be abbreviated to +.Li org +or +.Li o +(but not, for example, +.Li ORG ) . +.Pp +The +.Va len +is an expression for the size in bytes of the memory region. As with the +.Va origin +expression, the expression must be numerical only and must evaluate to a constant. +The keyword +.Li LENGTH +may be abbreviated to +.Li len +or +.Li l . +.Pp +In the following example, we specify that there are two memory regions available +for allocation: one starting at +.Li 0 +for 256 kilobytes, and the other starting at +.Li 0x40000000 +for four megabytes. The linker will place into the +.Li rom +memory region every section which is not explicitly mapped into a memory region, +and is either read-only or executable. The linker will place other sections +which are not explicitly mapped into a memory region into the +.Li ram +memory region. +.Pp +.Bd -literal -offset indent + +MEMORY + { + rom (rx) : ORIGIN = 0, LENGTH = 256K + ram (!rx) : org = 0x40000000, l = 4M + } + +.Ed +.Pp +Once you define a memory region, you can direct the linker to place specific +output sections into that memory region by using the +.Li > Va region +output section attribute. For example, if you have a memory region named +.Li mem , +you would use +.Li >mem +in the output section definition.See Section +.Dq Output Section Region . +If no address was specified for the output section, the linker will set the +address to the next available address within the memory region. If the combined +output sections directed to a memory region are too large for the region, +the linker will issue an error message. +.Pp +It is possible to access the origin and length of a memory in an expression +via the +.Li ORIGIN( Va memory) +and +.Li LENGTH( Va memory) +functions: +.Pp +.Bd -literal -offset indent + + _fstack = ORIGIN(ram) + LENGTH(ram) - 4; + +.Ed +.Pp +.Ss PHDRS Command +The ELF object file format uses +.Em program headers , +also knows as +.Em segments . +The program headers describe how the program should be loaded into memory. +You can print them out by using the +.Li objdump +program with the +.Li -p +option. +.Pp +When you run an ELF program on a native ELF system, the system loader reads +the program headers in order to figure out how to load the program. This will +only work if the program headers are set correctly. This manual does not describe +the details of how the system loader interprets program headers; for more +information, see the ELF ABI. +.Pp +The linker will create reasonable program headers by default. However, in +some cases, you may need to specify the program headers more precisely. You +may use the +.Li PHDRS +command for this purpose. When the linker sees the +.Li PHDRS +command in the linker script, it will not create any program headers other +than the ones specified. +.Pp +The linker only pays attention to the +.Li PHDRS +command when generating an ELF output file. In other cases, the linker will +simply ignore +.Li PHDRS . +.Pp +This is the syntax of the +.Li PHDRS +command. The words +.Li PHDRS , +.Li FILEHDR , +.Li AT , +and +.Li FLAGS +are keywords. +.Pp +.Bd -literal -offset indent + +PHDRS +{ + name type [ FILEHDR ] [ PHDRS ] [ AT ( address ) ] + [ FLAGS ( flags ) ] ; +} + +.Ed +.Pp +The +.Va name +is used only for reference in the +.Li SECTIONS +command of the linker script. It is not put into the output file. Program +header names are stored in a separate name space, and will not conflict with +symbol names, file names, or section names. Each program header must have +a distinct name. +.Pp +Certain program header types describe segments of memory which the system +loader will load from the file. In the linker script, you specify the contents +of these segments by placing allocatable output sections in the segments. +You use the +.Li : Va phdr +output section attribute to place a section in a particular segment.See Section +.Dq Output Section Phdr . +.Pp +It is normal to put certain sections in more than one segment. This merely +implies that one segment of memory contains another. You may repeat +.Li : Va phdr , +using it once for each segment which should contain the section. +.Pp +If you place a section in one or more segments using +.Li : Va phdr , +then the linker will place all subsequent allocatable sections which do not +specify +.Li : Va phdr +in the same segments. This is for convenience, since generally a whole set +of contiguous sections will be placed in a single segment. You can use +.Li :NONE +to override the default segment and tell the linker to not put the section +in any segment at all. +.Pp +You may use the +.Li FILEHDR +and +.Li PHDRS +keywords appear after the program header type to further describe the contents +of the segment. The +.Li FILEHDR +keyword means that the segment should include the ELF file header. The +.Li PHDRS +keyword means that the segment should include the ELF program headers themselves. +.Pp +The +.Va type +may be one of the following. The numbers indicate the value of the keyword. +.Pp +.Bl -tag -width Ds +.It Li PT_NULL (0) +Indicates an unused program header. +.Pp +.It Li PT_LOAD (1) +Indicates that this program header describes a segment to be loaded from the +file. +.Pp +.It Li PT_DYNAMIC (2) +Indicates a segment where dynamic linking information can be found. +.Pp +.It Li PT_INTERP (3) +Indicates a segment where the name of the program interpreter may be found. +.Pp +.It Li PT_NOTE (4) +Indicates a segment holding note information. +.Pp +.It Li PT_SHLIB (5) +A reserved program header type, defined but not specified by the ELF ABI. +.Pp +.It Li PT_PHDR (6) +Indicates a segment where the program headers may be found. +.Pp +.It Va expression +An expression giving the numeric type of the program header. This may be used +for types not defined above. +.El +.Pp +You can specify that a segment should be loaded at a particular address in +memory by using an +.Li AT +expression. This is identical to the +.Li AT +command used as an output section attribute (see Section +.Dq Output Section LMA ) . +The +.Li AT +command for a program header overrides the output section attribute. +.Pp +The linker will normally set the segment flags based on the sections which +comprise the segment. You may use the +.Li FLAGS +keyword to explicitly specify the segment flags. The value of +.Va flags +must be an integer. It is used to set the +.Li p_flags +field of the program header. +.Pp +Here is an example of +.Li PHDRS . +This shows a typical set of program headers used on a native ELF system. +.Pp +.Bd -literal -offset indent + +PHDRS +{ + headers PT_PHDR PHDRS ; + interp PT_INTERP ; + text PT_LOAD FILEHDR PHDRS ; + data PT_LOAD ; + dynamic PT_DYNAMIC ; +} + +SECTIONS +{ + . = SIZEOF_HEADERS; + .interp : { *(.interp) } :text :interp + .text : { *(.text) } :text + .rodata : { *(.rodata) } /* defaults to :text */ + ... + . = . + 0x1000; /* move to a new page in memory */ + .data : { *(.data) } :data + .dynamic : { *(.dynamic) } :data :dynamic + ... +} + +.Ed +.Pp +.Ss VERSION Command +The linker supports symbol versions when using ELF. Symbol versions are only +useful when using shared libraries. The dynamic linker can use symbol versions +to select a specific version of a function when it runs a program that may +have been linked against an earlier version of the shared library. +.Pp +You can include a version script directly in the main linker script, or you +can supply the version script as an implicit linker script. You can also use +the +.Li --version-script +linker option. +.Pp +The syntax of the +.Li VERSION +command is simply +.Bd -literal -offset indent +VERSION { version-script-commands } +.Ed +.Pp +The format of the version script commands is identical to that used by Sun's +linker in Solaris 2.5. The version script defines a tree of version nodes. +You specify the node names and interdependencies in the version script. You +can specify which symbols are bound to which version nodes, and you can reduce +a specified set of symbols to local scope so that they are not globally visible +outside of the shared library. +.Pp +The easiest way to demonstrate the version script language is with a few examples. +.Pp +.Bd -literal -offset indent +VERS_1.1 { + global: + foo1; + local: + old*; + original*; + new*; +}; + +VERS_1.2 { + foo2; +} VERS_1.1; + +VERS_2.0 { + bar1; bar2; + extern "C++" { + ns::*; + "int f(int, double)"; + } +} VERS_1.2; +.Ed +.Pp +This example version script defines three version nodes. The first version +node defined is +.Li VERS_1.1 ; +it has no other dependencies. The script binds the symbol +.Li foo1 +to +.Li VERS_1.1 . +It reduces a number of symbols to local scope so that they are not visible +outside of the shared library; this is done using wildcard patterns, so that +any symbol whose name begins with +.Li old , +.Li original , +or +.Li new +is matched. The wildcard patterns available are the same as those used in +the shell when matching filenames (also known as \(lqglobbing\(rq). However, if you +specify the symbol name inside double quotes, then the name is treated as +literal, rather than as a glob pattern. +.Pp +Next, the version script defines node +.Li VERS_1.2 . +This node depends upon +.Li VERS_1.1 . +The script binds the symbol +.Li foo2 +to the version node +.Li VERS_1.2 . +.Pp +Finally, the version script defines node +.Li VERS_2.0 . +This node depends upon +.Li VERS_1.2 . +The scripts binds the symbols +.Li bar1 +and +.Li bar2 +are bound to the version node +.Li VERS_2.0 . +.Pp +When the linker finds a symbol defined in a library which is not specifically +bound to a version node, it will effectively bind it to an unspecified base +version of the library. You can bind all otherwise unspecified symbols to +a given version node by using +.Li global: *; +somewhere in the version script. +.Pp +The names of the version nodes have no specific meaning other than what they +might suggest to the person reading them. The +.Li 2.0 +version could just as well have appeared in between +.Li 1.1 +and +.Li 1.2 . +However, this would be a confusing way to write a version script. +.Pp +Node name can be omitted, provided it is the only version node in the version +script. Such version script doesn't assign any versions to symbols, only selects +which symbols will be globally visible out and which won't. +.Pp +.Bd -literal -offset indent +{ global: foo; bar; local: *; }; +.Ed +.Pp +When you link an application against a shared library that has versioned symbols, +the application itself knows which version of each symbol it requires, and +it also knows which version nodes it needs from each shared library it is +linked against. Thus at runtime, the dynamic loader can make a quick check +to make sure that the libraries you have linked against do in fact supply +all of the version nodes that the application will need to resolve all of +the dynamic symbols. In this way it is possible for the dynamic linker to +know with certainty that all external symbols that it needs will be resolvable +without having to search for each symbol reference. +.Pp +The symbol versioning is in effect a much more sophisticated way of doing +minor version checking that SunOS does. The fundamental problem that is being +addressed here is that typically references to external functions are bound +on an as-needed basis, and are not all bound when the application starts up. +If a shared library is out of date, a required interface may be missing; when +the application tries to use that interface, it may suddenly and unexpectedly +fail. With symbol versioning, the user will get a warning when they start +their program if the libraries being used with the application are too old. +.Pp +There are several GNU extensions to Sun's versioning approach. The first of +these is the ability to bind a symbol to a version node in the source file +where the symbol is defined instead of in the versioning script. This was +done mainly to reduce the burden on the library maintainer. You can do this +by putting something like: +.Bd -literal -offset indent +__asm__(".symver original_foo,foo@VERS_1.1"); +.Ed +in the C source file. This renames the function +.Li original_foo +to be an alias for +.Li foo +bound to the version node +.Li VERS_1.1 . +The +.Li local: +directive can be used to prevent the symbol +.Li original_foo +from being exported. A +.Li .symver +directive takes precedence over a version script. +.Pp +The second GNU extension is to allow multiple versions of the same function +to appear in a given shared library. In this way you can make an incompatible +change to an interface without increasing the major version number of the +shared library, while still allowing applications linked against the old interface +to continue to function. +.Pp +To do this, you must use multiple +.Li .symver +directives in the source file. Here is an example: +.Pp +.Bd -literal -offset indent +__asm__(".symver original_foo,foo@"); +__asm__(".symver old_foo,foo@VERS_1.1"); +__asm__(".symver old_foo1,foo@VERS_1.2"); +__asm__(".symver new_foo,foo@@VERS_2.0"); +.Ed +.Pp +In this example, +.Li foo@ +represents the symbol +.Li foo +bound to the unspecified base version of the symbol. The source file that +contains this example would define 4 C functions: +.Li original_foo , +.Li old_foo , +.Li old_foo1 , +and +.Li new_foo . +.Pp +When you have multiple definitions of a given symbol, there needs to be some +way to specify a default version to which external references to this symbol +will be bound. You can do this with the +.Li foo@@VERS_2.0 +type of +.Li .symver +directive. You can only declare one version of a symbol as the default in +this manner; otherwise you would effectively have multiple definitions of +the same symbol. +.Pp +If you wish to bind a reference to a specific version of the symbol within +the shared library, you can use the aliases of convenience (i.e., +.Li old_foo ) , +or you can use the +.Li .symver +directive to specifically bind to an external version of the function in question. +.Pp +You can also specify the language in the version script: +.Pp +.Bd -literal -offset indent +VERSION extern "lang" { version-script-commands } +.Ed +.Pp +The supported +.Li lang +s are +.Li C , +.Li C++ , +and +.Li Java . +The linker will iterate over the list of symbols at the link time and demangle +them according to +.Li lang +before matching them to the patterns specified in +.Li version-script-commands . +.Pp +Demangled names may contains spaces and other special characters. As described +above, you can use a glob pattern to match demangled names, or you can use +a double-quoted string to match the string exactly. In the latter case, be +aware that minor differences (such as differing whitespace) between the version +script and the demangler output will cause a mismatch. As the exact string +generated by the demangler might change in the future, even if the mangled +name does not, you should check that all of your version directives are behaving +as you expect when you upgrade. +.Pp +.Ss Expressions in Linker Scripts +The syntax for expressions in the linker script language is identical to that +of C expressions. All expressions are evaluated as integers. All expressions +are evaluated in the same size, which is 32 bits if both the host and target +are 32 bits, and is otherwise 64 bits. +.Pp +You can use and set symbol values in expressions. +.Pp +The linker defines several special purpose builtin functions for use in expressions. +.Pp +.Em Constants +.Pp +All constants are integers. +.Pp +As in C, the linker considers an integer beginning with +.Li 0 +to be octal, and an integer beginning with +.Li 0x +or +.Li 0X +to be hexadecimal. The linker considers other integers to be decimal. +.Pp +In addition, you can use the suffixes +.Li K +and +.Li M +to scale a constant by +.Li 1024 +or +.Li 1024*1024 +respectively. For example, the following all refer to the same quantity: +.Bd -literal -offset indent +_fourk_1 = 4K; +_fourk_2 = 4096; +_fourk_3 = 0x1000; +.Ed +.Pp +.Em Symbol Names +.Pp +Unless quoted, symbol names start with a letter, underscore, or period and +may include letters, digits, underscores, periods, and hyphens. Unquoted symbol +names must not conflict with any keywords. You can specify a symbol which +contains odd characters or has the same name as a keyword by surrounding the +symbol name in double quotes: +.Bd -literal -offset indent +"SECTION" = 9; +"with a space" = "also with a space" + 10; +.Ed +.Pp +Since symbols can contain many non-alphabetic characters, it is safest to +delimit symbols with spaces. For example, +.Li A-B +is one symbol, whereas +.Li A - B +is an expression involving subtraction. +.Pp +.Em Orphan Sections +.Pp +Orphan sections are sections present in the input files which are not explicitly +placed into the output file by the linker script. The linker will still copy +these sections into the output file, but it has to guess as to where they +should be placed. The linker uses a simple heuristic to do this. It attempts +to place orphan sections after non-orphan sections of the same attribute, +such as code vs data, loadable vs non-loadable, etc. If there is not enough +room to do this then it places at the end of the file. +.Pp +For ELF targets, the attribute of the section includes section type as well +as section flag. +.Pp +.Em The Location Counter +.Pp +The special linker variable +.Em dot +.Li . +always contains the current output location counter. Since the +.Li . +always refers to a location in an output section, it may only appear in an +expression within a +.Li SECTIONS +command. The +.Li . +symbol may appear anywhere that an ordinary symbol is allowed in an expression. +.Pp +Assigning a value to +.Li . +will cause the location counter to be moved. This may be used to create holes +in the output section. The location counter may not be moved backwards inside +an output section, and may not be moved backwards outside of an output section +if so doing creates areas with overlapping LMAs. +.Pp +.Bd -literal -offset indent +SECTIONS +{ + output : + { + file1(.text) + . = . + 1000; + file2(.text) + . += 1000; + file3(.text) + } = 0x12345678; +} +.Ed +In the previous example, the +.Li .text +section from +.Pa file1 +is located at the beginning of the output section +.Li output . +It is followed by a 1000 byte gap. Then the +.Li .text +section from +.Pa file2 +appears, also with a 1000 byte gap following before the +.Li .text +section from +.Pa file3 . +The notation +.Li = 0x12345678 +specifies what data to write in the gaps (see Section +.Dq Output Section Fill ) . +.Pp +Note: +.Li . +actually refers to the byte offset from the start of the current containing +object. Normally this is the +.Li SECTIONS +statement, whose start address is 0, hence +.Li . +can be used as an absolute address. If +.Li . +is used inside a section description however, it refers to the byte offset +from the start of that section, not an absolute address. Thus in a script +like this: +.Pp +.Bd -literal -offset indent +SECTIONS +{ + . = 0x100 + .text: { + *(.text) + . = 0x200 + } + . = 0x500 + .data: { + *(.data) + . += 0x600 + } +} +.Ed +.Pp +The +.Li .text +section will be assigned a starting address of 0x100 and a size of exactly +0x200 bytes, even if there is not enough data in the +.Li .text +input sections to fill this area. (If there is too much data, an error will +be produced because this would be an attempt to move +.Li . +backwards). The +.Li .data +section will start at 0x500 and it will have an extra 0x600 bytes worth of +space after the end of the values from the +.Li .data +input sections and before the end of the +.Li .data +output section itself. +.Pp +Setting symbols to the value of the location counter outside of an output +section statement can result in unexpected values if the linker needs to place +orphan sections. For example, given the following: +.Pp +.Bd -literal -offset indent +SECTIONS +{ + start_of_text = . ; + .text: { *(.text) } + end_of_text = . ; + + start_of_data = . ; + .data: { *(.data) } + end_of_data = . ; +} +.Ed +.Pp +If the linker needs to place some input section, e.g. +.Li .rodata , +not mentioned in the script, it might choose to place that section between +.Li .text +and +.Li .data . +You might think the linker should place +.Li .rodata +on the blank line in the above script, but blank lines are of no particular +significance to the linker. As well, the linker doesn't associate the above +symbol names with their sections. Instead, it assumes that all assignments +or other statements belong to the previous output section, except for the +special case of an assignment to +.Li . . +I.e., the linker will place the orphan +.Li .rodata +section as if the script was written as follows: +.Pp +.Bd -literal -offset indent +SECTIONS +{ + start_of_text = . ; + .text: { *(.text) } + end_of_text = . ; + + start_of_data = . ; + .rodata: { *(.rodata) } + .data: { *(.data) } + end_of_data = . ; +} +.Ed +.Pp +This may or may not be the script author's intention for the value of +.Li start_of_data . +One way to influence the orphan section placement is to assign the location +counter to itself, as the linker assumes that an assignment to +.Li . +is setting the start address of a following output section and thus should +be grouped with that section. So you could write: +.Pp +.Bd -literal -offset indent +SECTIONS +{ + start_of_text = . ; + .text: { *(.text) } + end_of_text = . ; + + . = . ; + start_of_data = . ; + .data: { *(.data) } + end_of_data = . ; +} +.Ed +.Pp +Now, the orphan +.Li .rodata +section will be placed between +.Li end_of_text +and +.Li start_of_data . +.Pp +.Em Operators +.Pp +The linker recognizes the standard C set of arithmetic operators, with the +standard bindings and precedence levels: +.Bd -literal -offset indent +precedence associativity Operators Notes +(highest) +1 left ! - ~ (1) +2 left * / % +3 left + - +4 left >> << +5 left == != > < <= >= +6 left & +7 left | +8 left && +9 left || +10 right ? : +11 right &= += -= *= /= (2) +(lowest) +.Ed +Notes: (1) Prefix operators (2)See Section +.Dq Assignments . +.Pp +.Em Evaluation +.Pp +The linker evaluates expressions lazily. It only computes the value of an +expression when absolutely necessary. +.Pp +The linker needs some information, such as the value of the start address +of the first section, and the origins and lengths of memory regions, in order +to do any linking at all. These values are computed as soon as possible when +the linker reads in the linker script. +.Pp +However, other values (such as symbol values) are not known or needed until +after storage allocation. Such values are evaluated later, when other information +(such as the sizes of output sections) is available for use in the symbol +assignment expression. +.Pp +The sizes of sections cannot be known until after allocation, so assignments +dependent upon these are not performed until after allocation. +.Pp +Some expressions, such as those depending upon the location counter +.Li . , +must be evaluated during section allocation. +.Pp +If the result of an expression is required, but the value is not available, +then an error results. For example, a script like the following +.Bd -literal -offset indent + +SECTIONS + { + .text 9+this_isnt_constant : + { *(.text) } + } + +.Ed +will cause the error message +.Li non constant expression for initial address . +.Pp +.Em The Section of an Expression +.Pp +When the linker evaluates an expression, the result is either absolute or +relative to some section. A relative expression is expressed as a fixed offset +from the base of a section. +.Pp +The position of the expression within the linker script determines whether +it is absolute or relative. An expression which appears within an output section +definition is relative to the base of the output section. An expression which +appears elsewhere will be absolute. +.Pp +A symbol set to a relative expression will be relocatable if you request relocatable +output using the +.Li -r +option. That means that a further link operation may change the value of the +symbol. The symbol's section will be the section of the relative expression. +.Pp +A symbol set to an absolute expression will retain the same value through +any further link operation. The symbol will be absolute, and will not have +any particular associated section. +.Pp +You can use the builtin function +.Li ABSOLUTE +to force an expression to be absolute when it would otherwise be relative. +For example, to create an absolute symbol set to the address of the end of +the output section +.Li .data : +.Bd -literal -offset indent +SECTIONS + { + .data : { *(.data) _edata = ABSOLUTE(.); } + } +.Ed +If +.Li ABSOLUTE +were not used, +.Li _edata +would be relative to the +.Li .data +section. +.Pp +.Em Builtin Functions +.Pp +The linker script language includes a number of builtin functions for use +in linker script expressions. +.Pp +.Bl -tag -width Ds +.It ABSOLUTE( Va exp) +Return the absolute (non-relocatable, as opposed to non-negative) value of +the expression +.Va exp . +Primarily useful to assign an absolute value to a symbol within a section +definition, where symbol values are normally section relative.See Section +.Dq Expression Section . +.Pp +.It ADDR( Va section) +Return the absolute address (the VMA) of the named +.Va section . +Your script must previously have defined the location of that section. In +the following example, +.Li symbol_1 +and +.Li symbol_2 +are assigned identical values: +.Bd -literal -offset indent + +SECTIONS { ... + .output1 : + { + start_of_output_1 = ABSOLUTE(.); + ... + } + .output : + { + symbol_1 = ADDR(.output1); + symbol_2 = start_of_output_1; + } +\&... } + +.Ed +.Pp +.It ALIGN( Va align) +.It ALIGN( Va exp, Va align) +Return the location counter ( +.Li . ) +or arbitrary expression aligned to the next +.Va align +boundary. The single operand +.Li ALIGN +doesn't change the value of the location counter---it just does arithmetic +on it. The two operand +.Li ALIGN +allows an arbitrary expression to be aligned upwards ( +.Li ALIGN( Va align) +is equivalent to +.Li ALIGN(., Va align) ) . +.Pp +Here is an example which aligns the output +.Li .data +section to the next +.Li 0x2000 +byte boundary after the preceding section and sets a variable within the section +to the next +.Li 0x8000 +boundary after the input sections: +.Bd -literal -offset indent + +SECTIONS { ... + .data ALIGN(0x2000): { + *(.data) + variable = ALIGN(0x8000); + } +\&... } + +.Ed +The first use of +.Li ALIGN +in this example specifies the location of a section because it is used as +the optional +.Va address +attribute of a section definition (see Section +.Dq Output Section Address ) . +The second use of +.Li ALIGN +is used to defines the value of a symbol. +.Pp +The builtin function +.Li NEXT +is closely related to +.Li ALIGN . +.Pp +.It ALIGNOF( Va section) +Return the alignment in bytes of the named +.Va section , +if that section has been allocated. If the section has not been allocated +when this is evaluated, the linker will report an error. In the following +example, the alignment of the +.Li .output +section is stored as the first value in that section. +.Bd -literal -offset indent + +SECTIONS{ ... + .output { + LONG (ALIGNOF (.output)) + ... + } +\&... } + +.Ed +.Pp +.It BLOCK( Va exp) +This is a synonym for +.Li ALIGN , +for compatibility with older linker scripts. It is most often seen when setting +the address of an output section. +.Pp +.It DATA_SEGMENT_ALIGN( Va maxpagesize, Va commonpagesize) +This is equivalent to either +.Bd -literal -offset indent +(ALIGN(maxpagesize) + (. & (maxpagesize - 1))) +.Ed +or +.Bd -literal -offset indent +(ALIGN(maxpagesize) + (. & (maxpagesize - commonpagesize))) +.Ed +depending on whether the latter uses fewer +.Va commonpagesize +sized pages for the data segment (area between the result of this expression +and +.Li DATA_SEGMENT_END ) +than the former or not. If the latter form is used, it means +.Va commonpagesize +bytes of runtime memory will be saved at the expense of up to +.Va commonpagesize +wasted bytes in the on-disk file. +.Pp +This expression can only be used directly in +.Li SECTIONS +commands, not in any output section descriptions and only once in the linker +script. +.Va commonpagesize +should be less or equal to +.Va maxpagesize +and should be the system page size the object wants to be optimized for (while +still working on system page sizes up to +.Va maxpagesize ) . +.Pp +Example: +.Bd -literal -offset indent + . = DATA_SEGMENT_ALIGN(0x10000, 0x2000); +.Ed +.Pp +.It DATA_SEGMENT_END( Va exp) +This defines the end of data segment for +.Li DATA_SEGMENT_ALIGN +evaluation purposes. +.Pp +.Bd -literal -offset indent + . = DATA_SEGMENT_END(.); +.Ed +.Pp +.It DATA_SEGMENT_RELRO_END( Va offset, Va exp) +This defines the end of the +.Li PT_GNU_RELRO +segment when +.Li -z relro +option is used. Second argument is returned. When +.Li -z relro +option is not present, +.Li DATA_SEGMENT_RELRO_END +does nothing, otherwise +.Li DATA_SEGMENT_ALIGN +is padded so that +.Va exp ++ +.Va offset +is aligned to the most commonly used page boundary for particular target. +If present in the linker script, it must always come in between +.Li DATA_SEGMENT_ALIGN +and +.Li DATA_SEGMENT_END . +.Pp +.Bd -literal -offset indent + . = DATA_SEGMENT_RELRO_END(24, .); +.Ed +.Pp +.It DEFINED( Va symbol) +Return 1 if +.Va symbol +is in the linker global symbol table and is defined before the statement using +DEFINED in the script, otherwise return 0. You can use this function to provide +default values for symbols. For example, the following script fragment shows +how to set a global symbol +.Li begin +to the first location in the +.Li .text +section---but if a symbol called +.Li begin +already existed, its value is preserved: +.Pp +.Bd -literal -offset indent + +SECTIONS { ... + .text : { + begin = DEFINED(begin) ? begin : . ; + ... + } + ... +} + +.Ed +.Pp +.It LENGTH( Va memory) +Return the length of the memory region named +.Va memory . +.Pp +.It LOADADDR( Va section) +Return the absolute LMA of the named +.Va section . +This is normally the same as +.Li ADDR , +but it may be different if the +.Li AT +attribute is used in the output section definition (see Section +.Dq Output Section LMA ) . +.Pp +.It MAX( Va exp1, Va exp2) +Returns the maximum of +.Va exp1 +and +.Va exp2 . +.Pp +.It MIN( Va exp1, Va exp2) +Returns the minimum of +.Va exp1 +and +.Va exp2 . +.Pp +.It NEXT( Va exp) +Return the next unallocated address that is a multiple of +.Va exp . +This function is closely related to +.Li ALIGN( Va exp) ; +unless you use the +.Li MEMORY +command to define discontinuous memory for the output file, the two functions +are equivalent. +.Pp +.It ORIGIN( Va memory) +Return the origin of the memory region named +.Va memory . +.Pp +.It SEGMENT_START( Va segment, Va default) +Return the base address of the named +.Va segment . +If an explicit value has been given for this segment (with a command-line +.Li -T +option) that value will be returned; otherwise the value will be +.Va default . +At present, the +.Li -T +command-line option can only be used to set the base address for the \(lqtext\(rq, +\(lqdata\(rq, and \(lqbss\(rq sections, but you use +.Li SEGMENT_START +with any segment name. +.Pp +.It SIZEOF( Va section) +Return the size in bytes of the named +.Va section , +if that section has been allocated. If the section has not been allocated +when this is evaluated, the linker will report an error. In the following +example, +.Li symbol_1 +and +.Li symbol_2 +are assigned identical values: +.Bd -literal -offset indent + +SECTIONS{ ... + .output { + .start = . ; + ... + .end = . ; + } + symbol_1 = .end - .start ; + symbol_2 = SIZEOF(.output); +\&... } + +.Ed +.Pp +.It SIZEOF_HEADERS +.It sizeof_headers +Return the size in bytes of the output file's headers. This is information +which appears at the start of the output file. You can use this number when +setting the start address of the first section, if you choose, to facilitate +paging. +.Pp +When producing an ELF output file, if the linker script uses the +.Li SIZEOF_HEADERS +builtin function, the linker must compute the number of program headers before +it has determined all the section addresses and sizes. If the linker later +discovers that it needs additional program headers, it will report an error +.Li not enough room for program headers . +To avoid this error, you must avoid using the +.Li SIZEOF_HEADERS +function, or you must rework your linker script to avoid forcing the linker +to use additional program headers, or you must define the program headers +yourself using the +.Li PHDRS +command (see Section +.Dq PHDRS ) . +.El +.Pp +.Ss Implicit Linker Scripts +If you specify a linker input file which the linker can not recognize as an +object file or an archive file, it will try to read the file as a linker script. +If the file can not be parsed as a linker script, the linker will report an +error. +.Pp +An implicit linker script will not replace the default linker script. +.Pp +Typically an implicit linker script would contain only symbol assignments, +or the +.Li INPUT , +.Li GROUP , +or +.Li VERSION +commands. +.Pp +Any input files read because of an implicit linker script will be read at +the position in the command line where the implicit linker script was read. +This can affect archive searching. +.Pp +.Sh Machine Dependent Features +.Xr ld +has additional features on some platforms; the following sections describe +them. Machines where +.Xr ld +has no additional functionality are not listed. +.Pp +.Ss Xr ld and the H8/300 +For the H8/300, +.Xr ld +can perform these global optimizations when you specify the +.Li --relax +command-line option. +.Pp +.Bl -tag -width Ds +.It relaxing address modes +.Xr ld +finds all +.Li jsr +and +.Li jmp +instructions whose targets are within eight bits, and turns them into eight-bit +program-counter relative +.Li bsr +and +.Li bra +instructions, respectively. +.Pp +.It synthesizing instructions +.Xr ld +finds all +.Li mov.b +instructions which use the sixteen-bit absolute address form, but refer to +the top page of memory, and changes them to use the eight-bit address form. +(That is: the linker turns +.Li mov.b Li @ Va aa:16 +into +.Li mov.b Li @ Va aa:8 +whenever the address +.Va aa +is in the top page of memory). +.Pp +.It bit manipulation instructions +.Xr ld +finds all bit manipulation instructions like +.Li band, bclr, biand, bild, bior, bist, bixor, bld, bnot, bor, bset, bst, btst, bxor +which use 32 bit and 16 bit absolute address form, but refer to the top page +of memory, and changes them to use the 8 bit address form. (That is: the linker +turns +.Li bset #xx:3, Li @ Va aa:32 +into +.Li bset #xx:3, Li @ Va aa:8 +whenever the address +.Va aa +is in the top page of memory). +.Pp +.It system control instructions +.Xr ld +finds all +.Li ldc.w, stc.w +instructions which use the 32 bit absolute address form, but refer to the +top page of memory, and changes them to use 16 bit address form. (That is: +the linker turns +.Li ldc.w Li @ Va aa:32,ccr +into +.Li ldc.w Li @ Va aa:16,ccr +whenever the address +.Va aa +is in the top page of memory). +.El +.Pp +.Ss Xr ld and the Intel 960 Family +You can use the +.Li -A Va architecture +command line option to specify one of the two-letter names identifying members +of the 960 family; the option specifies the desired output target, and warns +of any incompatible instructions in the input files. It also modifies the +linker's search strategy for archive libraries, to support the use of libraries +specific to each particular architecture, by including in the search loop +names suffixed with the string identifying the architecture. +.Pp +For example, if your +.Xr ld +command line included +.Li -ACA +as well as +.Li -ltry +, the linker would look (in its built-in search paths, and in any paths you +specify with +.Li -L ) +for a library with the names +.Pp +.Bd -literal -offset indent + +try +libtry.a +tryca +libtryca.a + +.Ed +.Pp +The first two possibilities would be considered in any event; the last two +are due to the use of +.Li -ACA +\&. +.Pp +You can meaningfully use +.Li -A +more than once on a command line, since the 960 architecture family allows +combination of target architectures; each use will add another pair of name +variants to search for when +.Li -l +specifies a library. +.Pp +.Xr ld +supports the +.Li --relax +option for the i960 family. If you specify +.Li --relax , +.Xr ld +finds all +.Li balx +and +.Li calx +instructions whose targets are within 24 bits, and turns them into 24-bit +program-counter relative +.Li bal +and +.Li cal +instructions, respectively. +.Xr ld +also turns +.Li cal +instructions into +.Li bal +instructions when it determines that the target subroutine is a leaf routine +(that is, the target subroutine does not itself call any subroutines). +.Pp +.Ss Xr ld and the Motorola 68HC11 and 68HC12 families +.Em Linker Relaxation +.Pp +For the Motorola 68HC11, +.Xr ld +can perform these global optimizations when you specify the +.Li --relax +command-line option. +.Pp +.Bl -tag -width Ds +.It relaxing address modes +.Xr ld +finds all +.Li jsr +and +.Li jmp +instructions whose targets are within eight bits, and turns them into eight-bit +program-counter relative +.Li bsr +and +.Li bra +instructions, respectively. +.Pp +.Xr ld +also looks at all 16-bit extended addressing modes and transforms them in +a direct addressing mode when the address is in page 0 (between 0 and 0x0ff). +.Pp +.It relaxing gcc instruction group +When +.Xr gcc +is called with +.Op -mrelax , +it can emit group of instructions that the linker can optimize to use a 68HC11 +direct addressing mode. These instructions consists of +.Li bclr +or +.Li bset +instructions. +.Pp +.El +.Em Trampoline Generation +.Pp +For 68HC11 and 68HC12, +.Xr ld +can generate trampoline code to call a far function using a normal +.Li jsr +instruction. The linker will also change the relocation to some far function +to use the trampoline address instead of the function address. This is typically +the case when a pointer to a function is taken. The pointer will in fact point +to the function trampoline. +.Pp +The +.Li --pic-veneer +switch makes the linker use PIC sequences for ARM/Thumb interworking veneers, +even if the rest of the binary is not PIC. This avoids problems on uClinux +targets where +.Li --emit-relocs +is used to generate relocatable binaries. +.Pp +.Ss Xr ld and the ARM family +For the ARM, +.Xr ld +will generate code stubs to allow functions calls between ARM and Thumb code. +These stubs only work with code that has been compiled and assembled with +the +.Li -mthumb-interwork +command line option. If it is necessary to link with old ARM object files +or libraries, which have not been compiled with the -mthumb-interwork option +then the +.Li --support-old-code +command line switch should be given to the linker. This will make it generate +larger stub functions which will work with non-interworking aware ARM code. +Note, however, the linker does not support generating stubs for function calls +to non-interworking aware Thumb code. +.Pp +The +.Li --thumb-entry +switch is a duplicate of the generic +.Li --entry +switch, in that it sets the program's starting address. But it also sets the +bottom bit of the address, so that it can be branched to using a BX instruction, +and the program will start executing in Thumb mode straight away. +.Pp +The +.Li --be8 +switch instructs +.Xr ld +to generate BE8 format executables. This option is only valid when linking +big-endian objects. The resulting image will contain big-endian data and little-endian +code. +.Pp +The +.Li R_ARM_TARGET1 +relocation is typically used for entries in the +.Li .init_array +section. It is interpreted as either +.Li R_ARM_REL32 +or +.Li R_ARM_ABS32 , +depending on the target. The +.Li --target1-rel +and +.Li --target1-abs +switches override the default. +.Pp +The +.Li --target2=type +switch overrides the default definition of the +.Li R_ARM_TARGET2 +relocation. Valid values for +.Li type , +their meanings, and target defaults are as follows: +.Bl -tag -width Ds +.It rel +.Li R_ARM_REL32 +(arm*-*-elf, arm*-*-eabi) +.It abs +.Li R_ARM_ABS32 +(arm*-*-symbianelf) +.It got-rel +.Li R_ARM_GOT_PREL +(arm*-*-linux, arm*-*-*bsd) +.El +.Pp +The +.Li R_ARM_V4BX +relocation (defined by the ARM AAELF specification) enables objects compiled +for the ARMv4 architecture to be interworking-safe when linked with other +objects compiled for ARMv4t, but also allows pure ARMv4 binaries to be built +from the same ARMv4 objects. +.Pp +In the latter case, the switch +.Op --fix-v4bx +must be passed to the linker, which causes v4t +.Li BX rM +instructions to be rewritten as +.Li MOV PC,rM , +since v4 processors do not have a +.Li BX +instruction. +.Pp +In the former case, the switch should not be used, and +.Li R_ARM_V4BX +relocations are ignored. +.Pp +The +.Li --use-blx +switch enables the linker to use ARM/Thumb BLX instructions (available on +ARMv5t and above) in various situations. Currently it is used to perform calls +via the PLT from Thumb code using BLX rather than using BX and a mode-switching +stub before each PLT entry. This should lead to such calls executing slightly +faster. +.Pp +This option is enabled implicitly for SymbianOS, so there is no need to specify +it if you are using that target. +.Pp +The +.Li --vfp11-denorm-fix +switch enables a link-time workaround for a bug in certain VFP11 coprocessor +hardware, which sometimes allows instructions with denorm operands (which +must be handled by support code) to have those operands overwritten by subsequent +instructions before the support code can read the intended values. +.Pp +The bug may be avoided in scalar mode if you allow at least one intervening +instruction between a VFP11 instruction which uses a register and another +instruction which writes to the same register, or at least two intervening +instructions if vector mode is in use. The bug only affects full-compliance +floating-point mode: you do not need this workaround if you are using "runfast" +mode. Please contact ARM for further details. +.Pp +If you know you are using buggy VFP11 hardware, you can enable this workaround +by specifying the linker option +.Li --vfp-denorm-fix=scalar +if you are using the VFP11 scalar mode only, or +.Li --vfp-denorm-fix=vector +if you are using vector mode (the latter also works for scalar code). The +default is +.Li --vfp-denorm-fix=none . +.Pp +If the workaround is enabled, instructions are scanned for potentially-troublesome +sequences, and a veneer is created for each such sequence which may trigger +the erratum. The veneer consists of the first instruction of the sequence +and a branch back to the subsequent instruction. The original instruction +is then replaced with a branch to the veneer. The extra cycles required to +call and return from the veneer are sufficient to avoid the erratum in both +the scalar and vector cases. +.Pp +The +.Li --no-enum-size-warning +switch prevents the linker from warning when linking object files that specify +incompatible EABI enumeration size attributes. For example, with this switch +enabled, linking of an object file using 32-bit enumeration values with another +using enumeration values fitted into the smallest possible space will not +be diagnosed. +.Pp +.Ss Xr ld and HPPA 32-bit ELF Support +When generating a shared library, +.Xr ld +will by default generate import stubs suitable for use with a single sub-space +application. The +.Li --multi-subspace +switch causes +.Xr ld +to generate export stubs, and different (larger) import stubs suitable for +use with multiple sub-spaces. +.Pp +Long branch stubs and import/export stubs are placed by +.Xr ld +in stub sections located between groups of input sections. +.Li --stub-group-size +specifies the maximum size of a group of input sections handled by one stub +section. Since branch offsets are signed, a stub section may serve two groups +of input sections, one group before the stub section, and one group after +it. However, when using conditional branches that require stubs, it may be +better (for branch prediction) that stub sections only serve one group of +input sections. A negative value for +.Li N +chooses this scheme, ensuring that branches to stubs always use a negative +offset. Two special values of +.Li N +are recognized, +.Li 1 +and +.Li -1 . +These both instruct +.Xr ld +to automatically size input section groups for the branch types detected, +with the same behaviour regarding stub placement as other positive or negative +values of +.Li N +respectively. +.Pp +Note that +.Li --stub-group-size +does not split input sections. A single input section larger than the group +size specified will of course create a larger group (of one section). If input +sections are too large, it may not be possible for a branch to reach its stub. +.Pp +.Ss Li ld and MMIX +For MMIX, there is a choice of generating +.Li ELF +object files or +.Li mmo +object files when linking. The simulator +.Li mmix +understands the +.Li mmo +format. The binutils +.Li objcopy +utility can translate between the two formats. +.Pp +There is one special section, the +.Li .MMIX.reg_contents +section. Contents in this section is assumed to correspond to that of global +registers, and symbols referring to it are translated to special symbols, +equal to registers. In a final link, the start address of the +.Li .MMIX.reg_contents +section corresponds to the first allocated global register multiplied by 8. +Register +.Li $255 +is not included in this section; it is always set to the program entry, which +is at the symbol +.Li Main +for +.Li mmo +files. +.Pp +Symbols with the prefix +.Li __.MMIX.start. , +for example +.Li __.MMIX.start..text +and +.Li __.MMIX.start..data +are special; there must be only one each, even if they are local. The default +linker script uses these to set the default start address of a section. +.Pp +Initial and trailing multiples of zero-valued 32-bit words in a section, are +left out from an mmo file. +.Pp +.Ss Li ld and MSP430 +For the MSP430 it is possible to select the MPU architecture. The flag +.Li -m [mpu type] +will select an appropriate linker script for selected MPU type. (To get a +list of known MPUs just pass +.Li -m help +option to the linker). +.Pp +The linker will recognize some extra sections which are MSP430 specific: +.Pp +.Bl -tag -width Ds +.It Li .vectors +Defines a portion of ROM where interrupt vectors located. +.Pp +.It Li .bootloader +Defines the bootloader portion of the ROM (if applicable). Any code in this +section will be uploaded to the MPU. +.Pp +.It Li .infomem +Defines an information memory section (if applicable). Any code in this section +will be uploaded to the MPU. +.Pp +.It Li .infomemnobits +This is the same as the +.Li .infomem +section except that any code in this section will not be uploaded to the MPU. +.Pp +.It Li .noinit +Denotes a portion of RAM located above +.Li .bss +section. +.Pp +The last two sections are used by gcc. +.El +.Pp +.Ss Xr ld and PowerPC 32-bit ELF Support +Branches on PowerPC processors are limited to a signed 26-bit displacement, +which may result in +.Xr ld +giving +.Li relocation truncated to fit +errors with very large programs. +.Li --relax +enables the generation of trampolines that can access the entire 32-bit address +space. These trampolines are inserted at section boundaries, so may not themselves +be reachable if an input section exceeds 33M in size. +.Pp +.Bl -tag -width Ds +.It --bss-plt +Current PowerPC GCC accepts a +.Li -msecure-plt +option that generates code capable of using a newer PLT and GOT layout that +has the security advantage of no executable section ever needing to be writable +and no writable section ever being executable. PowerPC +.Xr ld +will generate this layout, including stubs to access the PLT, if all input +files (including startup and static libraries) were compiled with +.Li -msecure-plt . +.Li --bss-plt +forces the old BSS PLT (and GOT layout) which can give slightly better performance. +.Pp +.It --secure-plt +.Xr ld +will use the new PLT and GOT layout if it is linking new +.Li -fpic +or +.Li -fPIC +code, but does not do so automatically when linking non-PIC code. This option +requests the new PLT and GOT layout. A warning will be given if some object +file requires the old style BSS PLT. +.Pp +.It --sdata-got +The new secure PLT and GOT are placed differently relative to other sections +compared to older BSS PLT and GOT placement. The location of +.Li .plt +must change because the new secure PLT is an initialized section while the +old PLT is uninitialized. The reason for the +.Li .got +change is more subtle: The new placement allows +.Li .got +to be read-only in applications linked with +.Li -z relro -z now . +However, this placement means that +.Li .sdata +cannot always be used in shared libraries, because the PowerPC ABI accesses +.Li .sdata +in shared libraries from the GOT pointer. +.Li --sdata-got +forces the old GOT placement. PowerPC GCC doesn't use +.Li .sdata +in shared libraries, so this option is really only useful for other compilers +that may do so. +.Pp +.It --emit-stub-syms +This option causes +.Xr ld +to label linker stubs with a local symbol that encodes the stub type and destination. +.Pp +.It --no-tls-optimize +PowerPC +.Xr ld +normally performs some optimization of code sequences used to access Thread-Local +Storage. Use this option to disable the optimization. +.El +.Pp +.Ss Xr ld and PowerPC64 64-bit ELF Support +.Bl -tag -width Ds +.It --stub-group-size +Long branch stubs, PLT call stubs and TOC adjusting stubs are placed by +.Xr ld +in stub sections located between groups of input sections. +.Li --stub-group-size +specifies the maximum size of a group of input sections handled by one stub +section. Since branch offsets are signed, a stub section may serve two groups +of input sections, one group before the stub section, and one group after +it. However, when using conditional branches that require stubs, it may be +better (for branch prediction) that stub sections only serve one group of +input sections. A negative value for +.Li N +chooses this scheme, ensuring that branches to stubs always use a negative +offset. Two special values of +.Li N +are recognized, +.Li 1 +and +.Li -1 . +These both instruct +.Xr ld +to automatically size input section groups for the branch types detected, +with the same behaviour regarding stub placement as other positive or negative +values of +.Li N +respectively. +.Pp +Note that +.Li --stub-group-size +does not split input sections. A single input section larger than the group +size specified will of course create a larger group (of one section). If input +sections are too large, it may not be possible for a branch to reach its stub. +.Pp +.It --emit-stub-syms +This option causes +.Xr ld +to label linker stubs with a local symbol that encodes the stub type and destination. +.Pp +.It --dotsyms, --no-dotsyms +These two options control how +.Xr ld +interprets version patterns in a version script. Older PowerPC64 compilers +emitted both a function descriptor symbol with the same name as the function, +and a code entry symbol with the name prefixed by a dot ( +.Li . ) . +To properly version a function +.Li foo , +the version script thus needs to control both +.Li foo +and +.Li .foo . +The option +.Li --dotsyms , +on by default, automatically adds the required dot-prefixed patterns. Use +.Li --no-dotsyms +to disable this feature. +.Pp +.It --no-tls-optimize +PowerPC64 +.Xr ld +normally performs some optimization of code sequences used to access Thread-Local +Storage. Use this option to disable the optimization. +.Pp +.It --no-opd-optimize +PowerPC64 +.Xr ld +normally removes +.Li .opd +section entries corresponding to deleted link-once functions, or functions +removed by the action of +.Li --gc-sections +or linker scrip +.Li /DISCARD/ . +Use this option to disable +.Li .opd +optimization. +.Pp +.It --non-overlapping-opd +Some PowerPC64 compilers have an option to generate compressed +.Li .opd +entries spaced 16 bytes apart, overlapping the third word, the static chain +pointer (unused in C) with the first word of the next entry. This option expands +such entries to the full 24 bytes. +.Pp +.It --no-toc-optimize +PowerPC64 +.Xr ld +normally removes unused +.Li .toc +section entries. Such entries are detected by examining relocations that reference +the TOC in code sections. A reloc in a deleted code section marks a TOC word +as unneeded, while a reloc in a kept code section marks a TOC word as needed. +Since the TOC may reference itself, TOC relocs are also examined. TOC words +marked as both needed and unneeded will of course be kept. TOC words without +any referencing reloc are assumed to be part of a multi-word entry, and are +kept or discarded as per the nearest marked preceding word. This works reliably +for compiler generated code, but may be incorrect if assembly code is used +to insert TOC entries. Use this option to disable the optimization. +.Pp +.It --no-multi-toc +By default, PowerPC64 GCC generates code for a TOC model where TOC entries +are accessed with a 16-bit offset from r2. This limits the total TOC size +to 64K. PowerPC64 +.Xr ld +extends this limit by grouping code sections such that each group uses less +than 64K for its TOC entries, then inserts r2 adjusting stubs between inter-group +calls. +.Xr ld +does not split apart input sections, so cannot help if a single input file +has a +.Li .toc +section that exceeds 64K, most likely from linking multiple files with +.Xr ld -r . +Use this option to turn off this feature. +.El +.Pp +.Ss Xr ld and SPU ELF Support +.Bl -tag -width Ds +.It --plugin +This option marks an executable as a PIC plugin module. +.Pp +.It --no-overlays +Normally, +.Xr ld +recognizes calls to functions within overlay regions, and redirects such calls +to an overlay manager via a stub. +.Xr ld +also provides a built-in overlay manager. This option turns off all this special +overlay handling. +.Pp +.It --emit-stub-syms +This option causes +.Xr ld +to label overlay stubs with a local symbol that encodes the stub type and +destination. +.Pp +.It --extra-overlay-stubs +This option causes +.Xr ld +to add overlay call stubs on all function calls out of overlay regions. Normally +stubs are not added on calls to non-overlay regions. +.Pp +.It --local-store=lo:hi +.Xr ld +usually checks that a final executable for SPU fits in the address range 0 +to 256k. This option may be used to change the range. Disable the check entirely +with +.Op --local-store=0:0 . +.Pp +.It --stack-analysis +SPU local store space is limited. Over-allocation of stack space unnecessarily +limits space available for code and data, while under-allocation results in +runtime failures. If given this option, +.Xr ld +will provide an estimate of maximum stack usage. +.Xr ld +does this by examining symbols in code sections to determine the extents of +functions, and looking at function prologues for stack adjusting instructions. +A call-graph is created by looking for relocations on branch instructions. +The graph is then searched for the maximum stack usage path. Note that this +analysis does not find calls made via function pointers, and does not handle +recursion and other cycles in the call graph. Stack usage may be under-estimated +if your code makes such calls. Also, stack usage for dynamic allocation, e.g. +alloca, will not be detected. If a link map is requested, detailed information +about each function's stack usage and calls will be given. +.Pp +.It --emit-stack-syms +This option, if given along with +.Op --stack-analysis +will result in +.Xr ld +emitting stack sizing symbols for each function. These take the form +.Li __stack_<function_name> +for global functions, and +.Li __stack_<number>_<function_name> +for static functions. +.Li <number> +is the section id in hex. The value of such symbols is the stack requirement +for the corresponding function. The symbol size will be zero, type +.Li STT_NOTYPE , +binding +.Li STB_LOCAL , +and section +.Li SHN_ABS . +.El +.Pp +.Ss Xr ld's Support for Various TI COFF Versions +The +.Li --format +switch allows selection of one of the various TI COFF versions. The latest +of this writing is 2; versions 0 and 1 are also supported. The TI COFF versions +also vary in header byte-order format; +.Xr ld +will read any version or byte order, but the output header format depends +on the default specified by the specific target. +.Pp +.Ss Xr ld and WIN32 (cygwin/mingw) +This section describes some of the win32 specific +.Xr ld +issues. See Options,,Command Line Options for detailed description of the +command line options mentioned here. +.Pp +.Bl -tag -width Ds +.It import libraries +The standard Windows linker creates and uses so-called import libraries, which +contains information for linking to dll's. They are regular static archives +and are handled as any other static archive. The cygwin and mingw ports of +.Xr ld +have specific support for creating such libraries provided with the +.Li --out-implib +command line option. +.Pp +.It exporting DLL symbols +The cygwin/mingw +.Xr ld +has several ways to export symbols for dll's. +.Pp +.Bl -tag -width Ds +.It using auto-export functionality +By default +.Xr ld +exports symbols with the auto-export functionality, which is controlled by +the following command line options: +.Pp +.Bl -bullet +.It +--export-all-symbols [This is the default] +.It +--exclude-symbols +.It +--exclude-libs +.El +.Pp +If, however, +.Li --export-all-symbols +is not given explicitly on the command line, then the default auto-export +behavior will be +.Em disabled +if either of the following are true: +.Pp +.Bl -bullet +.It +A DEF file is used. +.It +Any symbol in any object file was marked with the __declspec(dllexport) attribute. +.El +.Pp +.It using a DEF file +Another way of exporting symbols is using a DEF file. A DEF file is an ASCII +file containing definitions of symbols which should be exported when a dll +is created. Usually it is named +.Li <dll name>.def +and is added as any other object file to the linker's command line. The file's +name must end in +.Li .def +or +.Li .DEF . +.Pp +.Bd -literal -offset indent +gcc -o <output> <objectfiles> <dll name>.def +.Ed +.Pp +Using a DEF file turns off the normal auto-export behavior, unless the +.Li --export-all-symbols +option is also used. +.Pp +Here is an example of a DEF file for a shared library called +.Li xyz.dll : +.Pp +.Bd -literal -offset indent +LIBRARY "xyz.dll" BASE=0x20000000 + +EXPORTS +foo +bar +_bar = bar +another_foo = abc.dll.afoo +var1 DATA +.Ed +.Pp +This example defines a DLL with a non-default base address and five symbols +in the export table. The third exported symbol +.Li _bar +is an alias for the second. The fourth symbol, +.Li another_foo +is resolved by "forwarding" to another module and treating it as an alias +for +.Li afoo +exported from the DLL +.Li abc.dll . +The final symbol +.Li var1 +is declared to be a data object. +.Pp +The optional +.Li LIBRARY <name> +command indicates the +.Em internal +name of the output DLL. If +.Li <name> +does not include a suffix, the default library suffix, +.Li .DLL +is appended. +.Pp +When the .DEF file is used to build an application, rather than a library, +the +.Li NAME <name> +command should be used instead of +.Li LIBRARY . +If +.Li <name> +does not include a suffix, the default executable suffix, +.Li .EXE +is appended. +.Pp +With either +.Li LIBRARY <name> +or +.Li NAME <name> +the optional specification +.Li BASE = <number> +may be used to specify a non-default base address for the image. +.Pp +If neither +.Li LIBRARY <name> +nor +.Li NAME <name> +is specified, or they specify an empty string, the internal name is the same +as the filename specified on the command line. +.Pp +The complete specification of an export symbol is: +.Pp +.Bd -literal -offset indent +EXPORTS + ( ( ( <name1> [ = <name2> ] ) + | ( <name1> = <module-name> . <external-name>)) + [ @ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] ) * +.Ed +.Pp +Declares +.Li <name1> +as an exported symbol from the DLL, or declares +.Li <name1> +as an exported alias for +.Li <name2> ; +or declares +.Li <name1> +as a "forward" alias for the symbol +.Li <external-name> +in the DLL +.Li <module-name> . +Optionally, the symbol may be exported by the specified ordinal +.Li <integer> +alias. +.Pp +The optional keywords that follow the declaration indicate: +.Pp +.Li NONAME : +Do not put the symbol name in the DLL's export table. It will still be exported +by its ordinal alias (either the value specified by the .def specification +or, otherwise, the value assigned by the linker). The symbol name, however, +does remain visible in the import library (if any), unless +.Li PRIVATE +is also specified. +.Pp +.Li DATA : +The symbol is a variable or object, rather than a function. The import lib +will export only an indirect reference to +.Li foo +as the symbol +.Li _imp__foo +(ie, +.Li foo +must be resolved as +.Li *_imp__foo ) . +.Pp +.Li CONSTANT : +Like +.Li DATA , +but put the undecorated +.Li foo +as well as +.Li _imp__foo +into the import library. Both refer to the read-only import address table's +pointer to the variable, not to the variable itself. This can be dangerous. +If the user code fails to add the +.Li dllimport +attribute and also fails to explicitly add the extra indirection that the +use of the attribute enforces, the application will behave unexpectedly. +.Pp +.Li PRIVATE : +Put the symbol in the DLL's export table, but do not put it into the static +import library used to resolve imports at link time. The symbol can still +be imported using the +.Li LoadLibrary/GetProcAddress +API at runtime or by by using the GNU ld extension of linking directly to +the DLL without an import library. See ld/deffilep.y in the binutils sources +for the full specification of other DEF file statements +.Pp +While linking a shared dll, +.Xr ld +is able to create a DEF file with the +.Li --output-def <file> +command line option. +.Pp +.It Using decorations +Another way of marking symbols for export is to modify the source code itself, +so that when building the DLL each symbol to be exported is declared as: +.Pp +.Bd -literal -offset indent +__declspec(dllexport) int a_variable +__declspec(dllexport) void a_function(int with_args) +.Ed +.Pp +All such symbols will be exported from the DLL. If, however, any of the object +files in the DLL contain symbols decorated in this way, then the normal auto-export +behavior is disabled, unless the +.Li --export-all-symbols +option is also used. +.Pp +Note that object files that wish to access these symbols must +.Em not +decorate them with dllexport. Instead, they should use dllimport, instead: +.Pp +.Bd -literal -offset indent +__declspec(dllimport) int a_variable +__declspec(dllimport) void a_function(int with_args) +.Ed +.Pp +This complicates the structure of library header files, because when included +by the library itself the header must declare the variables and functions +as dllexport, but when included by client code the header must declare them +as dllimport. There are a number of idioms that are typically used to do this; +often client code can omit the __declspec() declaration completely. See +.Li --enable-auto-import +and +.Li automatic data imports +for more information. +.El +.Pp +.It automatic data imports +The standard Windows dll format supports data imports from dlls only by adding +special decorations (dllimport/dllexport), which let the compiler produce +specific assembler instructions to deal with this issue. This increases the +effort necessary to port existing Un*x code to these platforms, especially +for large c++ libraries and applications. The auto-import feature, which was +initially provided by Paul Sokolovsky, allows one to omit the decorations +to achieve a behavior that conforms to that on POSIX/Un*x platforms. This +feature is enabled with the +.Li --enable-auto-import +command-line option, although it is enabled by default on cygwin/mingw. The +.Li --enable-auto-import +option itself now serves mainly to suppress any warnings that are ordinarily +emitted when linked objects trigger the feature's use. +.Pp +auto-import of variables does not always work flawlessly without additional +assistance. Sometimes, you will see this message +.Pp +"variable '<var>' can't be auto-imported. Please read the documentation for +ld's +.Li --enable-auto-import +for details." +.Pp +The +.Li --enable-auto-import +documentation explains why this error occurs, and several methods that can +be used to overcome this difficulty. One of these methods is the +.Em runtime pseudo-relocs +feature, described below. +.Pp +For complex variables imported from DLLs (such as structs or classes), object +files typically contain a base address for the variable and an offset ( +.Em addend ) +within the variable--to specify a particular field or public member, for instance. +Unfortunately, the runtime loader used in win32 environments is incapable +of fixing these references at runtime without the additional information supplied +by dllimport/dllexport decorations. The standard auto-import feature described +above is unable to resolve these references. +.Pp +The +.Li --enable-runtime-pseudo-relocs +switch allows these references to be resolved without error, while leaving +the task of adjusting the references themselves (with their non-zero addends) +to specialized code provided by the runtime environment. Recent versions of +the cygwin and mingw environments and compilers provide this runtime support; +older versions do not. However, the support is only necessary on the developer's +platform; the compiled result will run without error on an older system. +.Pp +.Li --enable-runtime-pseudo-relocs +is not the default; it must be explicitly enabled as needed. +.Pp +.It direct linking to a dll +The cygwin/mingw ports of +.Xr ld +support the direct linking, including data symbols, to a dll without the usage +of any import libraries. This is much faster and uses much less memory than +does the traditional import library method, especially when linking large +libraries or applications. When +.Xr ld +creates an import lib, each function or variable exported from the dll is +stored in its own bfd, even though a single bfd could contain many exports. +The overhead involved in storing, loading, and processing so many bfd's is +quite large, and explains the tremendous time, memory, and storage needed +to link against particularly large or complex libraries when using import +libs. +.Pp +Linking directly to a dll uses no extra command-line switches other than +.Li -L +and +.Li -l , +because +.Xr ld +already searches for a number of names to match each library. All that is +needed from the developer's perspective is an understanding of this search, +in order to force ld to select the dll instead of an import library. +.Pp +For instance, when ld is called with the argument +.Li -lxxx +it will attempt to find, in the first directory of its search path, +.Pp +.Bd -literal -offset indent +libxxx.dll.a +xxx.dll.a +libxxx.a +xxx.lib +cygxxx.dll (*) +libxxx.dll +xxx.dll +.Ed +.Pp +before moving on to the next directory in the search path. +.Pp +(*) Actually, this is not +.Li cygxxx.dll +but in fact is +.Li <prefix>xxx.dll , +where +.Li <prefix> +is set by the +.Xr ld +option +.Li --dll-search-prefix=<prefix> . +In the case of cygwin, the standard gcc spec file includes +.Li --dll-search-prefix=cyg , +so in effect we actually search for +.Li cygxxx.dll . +.Pp +Other win32-based unix environments, such as mingw or pw32, may use other +.Li <prefix> +es, although at present only cygwin makes use of this feature. It was originally +intended to help avoid name conflicts among dll's built for the various win32/un*x +environments, so that (for example) two versions of a zlib dll could coexist +on the same machine. +.Pp +The generic cygwin/mingw path layout uses a +.Li bin +directory for applications and dll's and a +.Li lib +directory for the import libraries (using cygwin nomenclature): +.Pp +.Bd -literal -offset indent +bin/ + cygxxx.dll +lib/ + libxxx.dll.a (in case of dll's) + libxxx.a (in case of static archive) +.Ed +.Pp +Linking directly to a dll without using the import library can be done two +ways: +.Pp +1. Use the dll directly by adding the +.Li bin +path to the link line +.Bd -literal -offset indent +gcc -Wl,-verbose -o a.exe -L../bin/ -lxxx +.Ed +.Pp +However, as the dll's often have version numbers appended to their names ( +.Li cygncurses-5.dll ) +this will often fail, unless one specifies +.Li -L../bin -lncurses-5 +to include the version. Import libs are generally not versioned, and do not +have this difficulty. +.Pp +2. Create a symbolic link from the dll to a file in the +.Li lib +directory according to the above mentioned search pattern. This should be +used to avoid unwanted changes in the tools needed for making the app/dll. +.Pp +.Bd -literal -offset indent +ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a] +.Ed +.Pp +Then you can link without any make environment changes. +.Pp +.Bd -literal -offset indent +gcc -Wl,-verbose -o a.exe -L../lib/ -lxxx +.Ed +.Pp +This technique also avoids the version number problems, because the following +is perfectly legal +.Pp +.Bd -literal -offset indent +bin/ + cygxxx-5.dll +lib/ + libxxx.dll.a -> ../bin/cygxxx-5.dll +.Ed +.Pp +Linking directly to a dll without using an import lib will work even when +auto-import features are exercised, and even when +.Li --enable-runtime-pseudo-relocs +is used. +.Pp +Given the improvements in speed and memory usage, one might justifiably wonder +why import libraries are used at all. There are three reasons: +.Pp +1. Until recently, the link-directly-to-dll functionality did +.Em not +work with auto-imported data. +.Pp +2. Sometimes it is necessary to include pure static objects within the import +library (which otherwise contains only bfd's for indirection symbols that +point to the exports of a dll). Again, the import lib for the cygwin kernel +makes use of this ability, and it is not possible to do this without an import +lib. +.Pp +3. Symbol aliases can only be resolved using an import lib. This is critical +when linking against OS-supplied dll's (eg, the win32 API) in which symbols +are usually exported as undecorated aliases of their stdcall-decorated assembly +names. +.Pp +So, import libs are not going away. But the ability to replace true import +libs with a simple symbolic link to (or a copy of) a dll, in many cases, is +a useful addition to the suite of tools binutils makes available to the win32 +developer. Given the massive improvements in memory requirements during linking, +storage requirements, and linking speed, we expect that many developers will +soon begin to use this feature whenever possible. +.Pp +.It symbol aliasing +.Bl -tag -width Ds +.It adding additional names +Sometimes, it is useful to export symbols with additional names. A symbol +.Li foo +will be exported as +.Li foo , +but it can also be exported as +.Li _foo +by using special directives in the DEF file when creating the dll. This will +affect also the optional created import library. Consider the following DEF +file: +.Pp +.Bd -literal -offset indent +LIBRARY "xyz.dll" BASE=0x61000000 + +EXPORTS +foo +_foo = foo +.Ed +.Pp +The line +.Li _foo = foo +maps the symbol +.Li foo +to +.Li _foo . +.Pp +Another method for creating a symbol alias is to create it in the source code +using the "weak" attribute: +.Pp +.Bd -literal -offset indent +void foo () { /* Do something. */; } +void _foo () __attribute__ ((weak, alias ("foo"))); +.Ed +.Pp +See the gcc manual for more information about attributes and weak symbols. +.Pp +.It renaming symbols +Sometimes it is useful to rename exports. For instance, the cygwin kernel +does this regularly. A symbol +.Li _foo +can be exported as +.Li foo +but not as +.Li _foo +by using special directives in the DEF file. (This will also affect the import +library, if it is created). In the following example: +.Pp +.Bd -literal -offset indent +LIBRARY "xyz.dll" BASE=0x61000000 + +EXPORTS +_foo = foo +.Ed +.Pp +The line +.Li _foo = foo +maps the exported symbol +.Li foo +to +.Li _foo . +.El +.Pp +Note: using a DEF file disables the default auto-export behavior, unless the +.Li --export-all-symbols +command line option is used. If, however, you are trying to rename symbols, +then you should list +.Em all +desired exports in the DEF file, including the symbols that are not being +renamed, and do +.Em not +use the +.Li --export-all-symbols +option. If you list only the renamed symbols in the DEF file, and use +.Li --export-all-symbols +to handle the other symbols, then the both the new names +.Em and +the original names for the renamed symbols will be exported. In effect, you'd +be aliasing those symbols, not renaming them, which is probably not what you +wanted. +.Pp +.It weak externals +The Windows object format, PE, specifies a form of weak symbols called weak +externals. When a weak symbol is linked and the symbol is not defined, the +weak symbol becomes an alias for some other symbol. There are three variants +of weak externals: +.Bl -bullet +.It +Definition is searched for in objects and libraries, historically +called lazy externals. +.It +Definition is searched for only in other objects, not in libraries. +This form is not presently implemented. +.It +No search; the symbol is an alias. This form is not presently +implemented. +.El +As a GNU extension, weak symbols that do not specify an alternate symbol are +supported. If the symbol is undefined when linking, the symbol uses a default +value. +.El +.Pp +.Ss Li ld and Xtensa Processors +The default +.Xr ld +behavior for Xtensa processors is to interpret +.Li SECTIONS +commands so that lists of explicitly named sections in a specification with +a wildcard file will be interleaved when necessary to keep literal pools within +the range of PC-relative load offsets. For example, with the command: +.Pp +.Bd -literal -offset indent +SECTIONS +{ + .text : { + *(.literal .text) + } +} +.Ed +.Pp +.Xr ld +may interleave some of the +.Li .literal +and +.Li .text +sections from different object files to ensure that the literal pools are +within the range of PC-relative load offsets. A valid interleaving might place +the +.Li .literal +sections from an initial group of files followed by the +.Li .text +sections of that group of files. Then, the +.Li .literal +sections from the rest of the files and the +.Li .text +sections from the rest of the files would follow. +.Pp +Relaxation is enabled by default for the Xtensa version of +.Xr ld +and provides two important link-time optimizations. The first optimization +is to combine identical literal values to reduce code size. A redundant literal +will be removed and all the +.Li L32R +instructions that use it will be changed to reference an identical literal, +as long as the location of the replacement literal is within the offset range +of all the +.Li L32R +instructions. The second optimization is to remove unnecessary overhead from +assembler-generated \(lqlongcall\(rq sequences of +.Li L32R +/ +.Li CALLX Va n +when the target functions are within range of direct +.Li CALL Va n +instructions. +.Pp +For each of these cases where an indirect call sequence can be optimized to +a direct call, the linker will change the +.Li CALLX Va n +instruction to a +.Li CALL Va n +instruction, remove the +.Li L32R +instruction, and remove the literal referenced by the +.Li L32R +instruction if it is not used for anything else. Removing the +.Li L32R +instruction always reduces code size but can potentially hurt performance +by changing the alignment of subsequent branch targets. By default, the linker +will always preserve alignments, either by switching some instructions between +24-bit encodings and the equivalent density instructions or by inserting a +no-op in place of the +.Li L32R +instruction that was removed. If code size is more important than performance, +the +.Op --size-opt +option can be used to prevent the linker from widening density instructions +or inserting no-ops, except in a few cases where no-ops are required for correctness. +.Pp +The following Xtensa-specific command-line options can be used to control +the linker: +.Pp +.Bl -tag -width Ds +.It --no-relax +Since the Xtensa version of +.Li ld +enables the +.Op --relax +option by default, the +.Op --no-relax +option is provided to disable relaxation. +.Pp +.It --size-opt +When optimizing indirect calls to direct calls, optimize for code size more +than performance. With this option, the linker will not insert no-ops or widen +density instructions to preserve branch target alignment. There may still +be some cases where no-ops are required to preserve the correctness of the +code. +.El +.Pp +.Sh BFD +The linker accesses object and archive files using the BFD libraries. These +libraries allow the linker to use the same routines to operate on object files +whatever the object file format. A different object file format can be supported +simply by creating a new BFD back end and adding it to the library. To conserve +runtime memory, however, the linker and associated tools are usually configured +to support only a subset of the object file formats available. You can use +.Li objdump -i +(see Section +.Dq objdump ) +to list all the formats available for your configuration. +.Pp +As with most implementations, BFD is a compromise between several conflicting +requirements. The major factor influencing BFD design was efficiency: any +time used converting between formats is time which would not have been spent +had BFD not been involved. This is partly offset by abstraction payback; since +BFD simplifies applications and back ends, more time and care may be spent +optimizing algorithms for a greater speed. +.Pp +One minor artifact of the BFD solution which you should bear in mind is the +potential for information loss. There are two places where useful information +can be lost using the BFD mechanism: during conversion and during output.See Section +.Dq BFD information loss . +.Pp +.Ss How It Works: An Outline of BFD +When an object file is opened, BFD subroutines automatically determine the +format of the input object file. They then build a descriptor in memory with +pointers to routines that will be used to access elements of the object file's +data structures. +.Pp +As different information from the object files is required, BFD reads from +different sections of the file and processes them. For example, a very common +operation for the linker is processing symbol tables. Each BFD back end provides +a routine for converting between the object file's representation of symbols +and an internal canonical format. When the linker asks for the symbol table +of an object file, it calls through a memory pointer to the routine from the +relevant BFD back end which reads and converts the table into a canonical +form. The linker then operates upon the canonical form. When the link is finished +and the linker writes the output file's symbol table, another BFD back end +routine is called to take the newly created symbol table and convert it into +the chosen output format. +.Pp +.Em Information Loss +.Pp +.Em Information can be lost during output. +The output formats supported by BFD do not provide identical facilities, and +information which can be described in one form has nowhere to go in another +format. One example of this is alignment information in +.Li b.out . +There is nowhere in an +.Li a.out +format file to store alignment information on the contained data, so when +a file is linked from +.Li b.out +and an +.Li a.out +image is produced, alignment information will not propagate to the output +file. (The linker will still use the alignment information internally, so +the link is performed correctly). +.Pp +Another example is COFF section names. COFF files may contain an unlimited +number of sections, each one with a textual section name. If the target of +the link is a format which does not have many sections (e.g., +.Li a.out ) +or has sections without names (e.g., the Oasys format), the link cannot be +done simply. You can circumvent this problem by describing the desired input-to-output +section mapping with the linker command language. +.Pp +.Em Information can be lost during canonicalization. +The BFD internal canonical form of the external formats is not exhaustive; +there are structures in input formats for which there is no direct representation +internally. This means that the BFD back ends cannot maintain all possible +data richness through the transformation between external to internal and +back to external formats. +.Pp +This limitation is only a problem when an application reads one format and +writes another. Each BFD back end is responsible for maintaining as much data +as possible, and the internal BFD canonical form has structures which are +opaque to the BFD core, and exported only to the back ends. When a file is +read in one format, the canonical form is generated for BFD and the application. +At the same time, the back end saves away any information which may otherwise +be lost. If the data is then written back in the same format, the back end +routine will be able to use the canonical form provided by the BFD core as +well as the information it prepared earlier. Since there is a great deal of +commonality between back ends, there is no information lost when linking or +copying big endian COFF to little endian COFF, or +.Li a.out +to +.Li b.out . +When a mixture of formats is linked, the information is only lost from the +files whose format differs from the destination. +.Pp +.Em The BFD canonical object-file format +.Pp +The greatest potential for loss of information occurs when there is the least +overlap between the information provided by the source format, that stored +by the canonical format, and that needed by the destination format. A brief +description of the canonical form may help you understand which kinds of data +you can count on preserving across conversions. +.Pp +.Bl -tag -width Ds +.It files +Information stored on a per-file basis includes target machine architecture, +particular implementation format type, a demand pageable bit, and a write +protected bit. Information like Unix magic numbers is not stored here---only +the magic numbers' meaning, so a +.Li ZMAGIC +file would have both the demand pageable bit and the write protected text +bit set. The byte order of the target is stored on a per-file basis, so that +big- and little-endian object files may be used with one another. +.Pp +.It sections +Each section in the input file contains the name of the section, the section's +original address in the object file, size and alignment information, various +flags, and pointers into other BFD data structures. +.Pp +.It symbols +Each symbol contains a pointer to the information for the object file which +originally defined it, its name, its value, and various flag bits. When a +BFD back end reads in a symbol table, it relocates all symbols to make them +relative to the base of the section where they were defined. Doing this ensures +that each symbol points to its containing section. Each symbol also has a +varying amount of hidden private data for the BFD back end. Since the symbol +points to the original file, the private data format for that symbol is accessible. +.Li ld +can operate on a collection of symbols of wildly different formats without +problems. +.Pp +Normal global and simple local symbols are maintained on output, so an output +file (no matter its format) will retain symbols pointing to functions and +to global, static, and common variables. Some symbol information is not worth +retaining; in +.Li a.out , +type information is stored in the symbol table as long symbol names. This +information would be useless to most COFF debuggers; the linker has command +line switches to allow users to throw it away. +.Pp +There is one word of type information within the symbol, so if the format +supports symbol type information within symbols (for example, COFF, IEEE, +Oasys) and the type is simple enough to fit within one word (nearly everything +but aggregates), the information will be preserved. +.Pp +.It relocation level +Each canonical BFD relocation record contains a pointer to the symbol to relocate +to, the offset of the data to relocate, the section the data is in, and a +pointer to a relocation type descriptor. Relocation is performed by passing +messages through the relocation type descriptor and the symbol pointer. Therefore, +relocations can be performed on output data using a relocation method that +is only available in one of the input formats. For instance, Oasys provides +a byte relocation format. A relocation record requesting this relocation type +would point indirectly to a routine to perform this, so the relocation may +be performed on a byte being written to a 68k COFF file, even though 68k COFF +has no such relocation type. +.Pp +.It line numbers +Object formats can contain, for debugging purposes, some form of mapping between +symbols, source line numbers, and addresses in the output file. These addresses +have to be relocated along with the symbol information. Each symbol with an +associated list of line number records points to the first record of the list. +The head of a line number list consists of a pointer to the symbol, which +allows finding out the address of the function whose line number is being +described. The rest of the list is made up of pairs: offsets into the section +and line numbers. Any format which can simply derive this information can +pass it successfully between formats (COFF, IEEE and Oasys). +.El +.Pp +.Sh Reporting Bugs +Your bug reports play an essential role in making +.Xr ld +reliable. +.Pp +Reporting a bug may help you by bringing a solution to your problem, or it +may not. But in any case the principal function of a bug report is to help +the entire community by making the next version of +.Xr ld +work better. Bug reports are your contribution to the maintenance of +.Xr ld . +.Pp +In order for a bug report to serve its purpose, you must include the information +that enables us to fix the bug. +.Pp +.Ss Have You Found a Bug? +If you are not sure whether you have found a bug, here are some guidelines: +.Pp +.Bl -bullet +.It +If the linker gets a fatal signal, for any input whatever, that is a +.Xr ld +bug. Reliable linkers never crash. +.Pp +.It +If +.Xr ld +produces an error message for valid input, that is a bug. +.Pp +.It +If +.Xr ld +does not produce an error message for invalid input, that may be a bug. In +the general case, the linker can not verify that object files are correct. +.Pp +.It +If you are an experienced user of linkers, your suggestions for improvement +of +.Xr ld +are welcome in any case. +.El +.Pp +.Ss How to Report Bugs +A number of companies and individuals offer support for GNU products. If you +obtained +.Xr ld +from a support organization, we recommend you contact that organization first. +.Pp +You can find contact information for many support companies and individuals +in the file +.Pa etc/SERVICE +in the GNU Emacs distribution. +.Pp +The fundamental principle of reporting bugs usefully is this: +.Sy report all the facts . +If you are not sure whether to state a fact or leave it out, state it! +.Pp +Often people omit facts because they think they know what causes the problem +and assume that some details do not matter. Thus, you might assume that the +name of a symbol you use in an example does not matter. Well, probably it +does not, but one cannot be sure. Perhaps the bug is a stray memory reference +which happens to fetch from the location where that name is stored in memory; +perhaps, if the name were different, the contents of that location would fool +the linker into doing the right thing despite the bug. Play it safe and give +a specific, complete example. That is the easiest thing for you to do, and +the most helpful. +.Pp +Keep in mind that the purpose of a bug report is to enable us to fix the bug +if it is new to us. Therefore, always write your bug reports on the assumption +that the bug has not been reported previously. +.Pp +Sometimes people give a few sketchy facts and ask, \(lqDoes this ring a bell?\(rq +This cannot help us fix a bug, so it is basically useless. We respond by asking +for enough details to enable us to investigate. You might as well expedite +matters by sending them to begin with. +.Pp +To enable us to fix the bug, you should include all these things: +.Pp +.Bl -bullet +.It +The version of +.Xr ld . +.Xr ld +announces it if you start it with the +.Li --version +argument. +.Pp +Without this, we will not know whether there is any point in looking for the +bug in the current version of +.Xr ld . +.Pp +.It +Any patches you may have applied to the +.Xr ld +source, including any patches made to the +.Li BFD +library. +.Pp +.It +The type of machine you are using, and the operating system name and version +number. +.Pp +.It +What compiler (and its version) was used to compile +.Xr ld +---e.g. \(lq +.Li gcc-2.7 +\(rq\&. +.Pp +.It +The command arguments you gave the linker to link your example and observe +the bug. To guarantee you will not omit something important, list them all. +A copy of the Makefile (or the output from make) is sufficient. +.Pp +If we were to try to guess the arguments, we would probably guess wrong and +then we might not encounter the bug. +.Pp +.It +A complete input file, or set of input files, that will reproduce the bug. +It is generally most helpful to send the actual object files provided that +they are reasonably small. Say no more than 10K. For bigger files you can +either make them available by FTP or HTTP or else state that you are willing +to send the object file(s) to whomever requests them. (Note - your email will +be going to a mailing list, so we do not want to clog it up with large attachments). +But small attachments are best. +.Pp +If the source files were assembled using +.Li gas +or compiled using +.Li gcc , +then it may be OK to send the source files rather than the object files. In +this case, be sure to say exactly what version of +.Li gas +or +.Li gcc +was used to produce the object files. Also say how +.Li gas +or +.Li gcc +were configured. +.Pp +.It +A description of what behavior you observe that you believe is incorrect. +For example, \(lqIt gets a fatal signal.\(rq +.Pp +Of course, if the bug is that +.Xr ld +gets a fatal signal, then we will certainly notice it. But if the bug is incorrect +output, we might not notice unless it is glaringly wrong. You might as well +not give us a chance to make a mistake. +.Pp +Even if the problem you experience is a fatal signal, you should still say +so explicitly. Suppose something strange is going on, such as, your copy of +.Xr ld +is out of sync, or you have encountered a bug in the C library on your system. +(This has happened!) Your copy might crash and ours would not. If you told +us to expect a crash, then when ours fails to crash, we would know that the +bug was not happening for us. If you had not told us to expect a crash, then +we would not be able to draw any conclusion from our observations. +.Pp +.It +If you wish to suggest changes to the +.Xr ld +source, send us context diffs, as generated by +.Li diff +with the +.Li -u , +.Li -c , +or +.Li -p +option. Always send diffs from the old file to the new file. If you even discuss +something in the +.Xr ld +source, refer to it by context, not by line number. +.Pp +The line numbers in our development sources will not match those in your sources. +Your line numbers would convey no useful information to us. +.El +.Pp +Here are some things that are not necessary: +.Pp +.Bl -bullet +.It +A description of the envelope of the bug. +.Pp +Often people who encounter a bug spend a lot of time investigating which changes +to the input file will make the bug go away and which changes will not affect +it. +.Pp +This is often time consuming and not very useful, because the way we will +find the bug is by running a single example under the debugger with breakpoints, +not by pure deduction from a series of examples. We recommend that you save +your time for something else. +.Pp +Of course, if you can find a simpler example to report +.Em instead +of the original one, that is a convenience for us. Errors in the output will +be easier to spot, running under the debugger will take less time, and so +on. +.Pp +However, simplification is not vital; if you do not want to do this, report +the bug anyway and send us the entire test case you used. +.Pp +.It +A patch for the bug. +.Pp +A patch for the bug does help us if it is a good one. But do not omit the +necessary information, such as the test case, on the assumption that a patch +is all we need. We might see problems with your patch and decide to fix the +problem another way, or we might not understand it at all. +.Pp +Sometimes with a program as complicated as +.Xr ld +it is very hard to construct an example that will make the program follow +a certain path through the code. If you do not send us the example, we will +not be able to construct one, so we will not be able to verify that the bug +is fixed. +.Pp +And if we cannot understand what bug you are trying to fix, or why your patch +should be an improvement, we will not install it. A test case will help us +to understand. +.Pp +.It +A guess about what the bug is or what it depends on. +.Pp +Such guesses are usually wrong. Even we cannot guess right about such things +without first using the debugger to find the facts. +.El +.Pp +.Sh MRI Compatible Script Files +To aid users making the transition to GNU +.Xr ld +from the MRI linker, +.Xr ld +can use MRI compatible linker scripts as an alternative to the more general-purpose +linker scripting language described in Scripts. MRI compatible linker scripts +have a much simpler command set than the scripting language otherwise used +with +.Xr ld . +GNU +.Xr ld +supports the most commonly used MRI linker commands; these commands are described +here. +.Pp +In general, MRI scripts aren't of much use with the +.Li a.out +object file format, since it only has three sections and MRI scripts lack +some features to make use of them. +.Pp +You can specify a file containing an MRI-compatible script using the +.Li -c +command-line option. +.Pp +Each command in an MRI-compatible script occupies its own line; each command +line starts with the keyword that identifies the command (though blank lines +are also allowed for punctuation). If a line of an MRI-compatible script begins +with an unrecognized keyword, +.Xr ld +issues a warning message, but continues processing the script. +.Pp +Lines beginning with +.Li * +are comments. +.Pp +You can write these commands using all upper-case letters, or all lower case; +for example, +.Li chip +is the same as +.Li CHIP . +The following list shows only the upper-case form of each command. +.Pp +.Bl -tag -width Ds +.It ABSOLUTE Va secname +.It ABSOLUTE Va secname, Va secname, ... Va secname +Normally, +.Xr ld +includes in the output file all sections from all the input files. However, +in an MRI-compatible script, you can use the +.Li ABSOLUTE +command to restrict the sections that will be present in your output program. +If the +.Li ABSOLUTE +command is used at all in a script, then only the sections named explicitly +in +.Li ABSOLUTE +commands will appear in the linker output. You can still use other input sections +(whatever you select on the command line, or using +.Li LOAD ) +to resolve addresses in the output file. +.Pp +.It ALIAS Va out-secname, Va in-secname +Use this command to place the data from input section +.Va in-secname +in a section called +.Va out-secname +in the linker output file. +.Pp +.Va in-secname +may be an integer. +.Pp +.It ALIGN Va secname = Va expression +Align the section called +.Va secname +to +.Va expression . +The +.Va expression +should be a power of two. +.Pp +.It BASE Va expression +Use the value of +.Va expression +as the lowest address (other than absolute addresses) in the output file. +.Pp +.It CHIP Va expression +.It CHIP Va expression, Va expression +This command does nothing; it is accepted only for compatibility. +.Pp +.It END +This command does nothing whatever; it's only accepted for compatibility. +.Pp +.It FORMAT Va output-format +Similar to the +.Li OUTPUT_FORMAT +command in the more general linker language, but restricted to one of these +output formats: +.Pp +.Bl -enum +.It +S-records, if +.Va output-format +is +.Li S +.Pp +.It +IEEE, if +.Va output-format +is +.Li IEEE +.Pp +.It +COFF (the +.Li coff-m68k +variant in BFD), if +.Va output-format +is +.Li COFF +.El +.Pp +.It LIST Va anything... +Print (to the standard output file) a link map, as produced by the +.Xr ld +command-line option +.Li -M . +.Pp +The keyword +.Li LIST +may be followed by anything on the same line, with no change in its effect. +.Pp +.It LOAD Va filename +.It LOAD Va filename, Va filename, ... Va filename +Include one or more object file +.Va filename +in the link; this has the same effect as specifying +.Va filename +directly on the +.Xr ld +command line. +.Pp +.It NAME Va output-name +.Va output-name +is the name for the program produced by +.Xr ld ; +the MRI-compatible command +.Li NAME +is equivalent to the command-line option +.Li -o +or the general script language command +.Li OUTPUT . +.Pp +.It ORDER Va secname, Va secname, ... Va secname +.It ORDER Va secname Va secname Va secname +Normally, +.Xr ld +orders the sections in its output file in the order in which they first appear +in the input files. In an MRI-compatible script, you can override this ordering +with the +.Li ORDER +command. The sections you list with +.Li ORDER +will appear first in your output file, in the order specified. +.Pp +.It PUBLIC Va name= Va expression +.It PUBLIC Va name, Va expression +.It PUBLIC Va name Va expression +Supply a value ( +.Va expression ) +for external symbol +.Va name +used in the linker input files. +.Pp +.It SECT Va secname, Va expression +.It SECT Va secname= Va expression +.It SECT Va secname Va expression +You can use any of these three forms of the +.Li SECT +command to specify the start address ( +.Va expression ) +for section +.Va secname . +If you have more than one +.Li SECT +statement for the same +.Va secname , +only the +.Em first +sets the start address. +.El +.Pp +.Sh GNU Free Documentation License +.Bd -filled -offset indent +Copyright (C) 2000, 2003 Free Software Foundation, Inc. 51 Franklin Street, +Fifth Floor, Boston, MA 02110-1301 USA +.Pp +Everyone is permitted to copy and distribute verbatim copies of this license +document, but changing it is not allowed. +.Ed +.Pp +.Bl -enum +.It +PREAMBLE +.Pp +The purpose of this License is to make a manual, textbook, or other written +document \(lqfree\(rq in the sense of freedom: to assure everyone the effective freedom +to copy and redistribute it, with or without modifying it, either commercially +or noncommercially. Secondarily, this License preserves for the author and +publisher a way to get credit for their work, while not being considered responsible +for modifications made by others. +.Pp +This License is a kind of \(lqcopyleft\(rq, which means that derivative works of the +document must themselves be free in the same sense. It complements the GNU +General Public License, which is a copyleft license designed for free software. +.Pp +We have designed this License in order to use it for manuals for free software, +because free software needs free documentation: a free program should come +with manuals providing the same freedoms that the software does. But this +License is not limited to software manuals; it can be used for any textual +work, regardless of subject matter or whether it is published as a printed +book. We recommend this License principally for works whose purpose is instruction +or reference. +.Pp +.It +APPLICABILITY AND DEFINITIONS +.Pp +This License applies to any manual or other work that contains a notice placed +by the copyright holder saying it can be distributed under the terms of this +License. The \(lqDocument\(rq, below, refers to any such manual or work. Any member +of the public is a licensee, and is addressed as \(lqyou.\(rq +.Pp +A \(lqModified Version\(rq of the Document means any work containing the Document +or a portion of it, either copied verbatim, or with modifications and/or translated +into another language. +.Pp +A \(lqSecondary Section\(rq is a named appendix or a front-matter section of the Document +that deals exclusively with the relationship of the publishers or authors +of the Document to the Document's overall subject (or to related matters) +and contains nothing that could fall directly within that overall subject. +(For example, if the Document is in part a textbook of mathematics, a Secondary +Section may not explain any mathematics.) The relationship could be a matter +of historical connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding them. +.Pp +The \(lqInvariant Sections\(rq are certain Secondary Sections whose titles are designated, +as being those of Invariant Sections, in the notice that says that the Document +is released under this License. +.Pp +The \(lqCover Texts\(rq are certain short passages of text that are listed, as Front-Cover +Texts or Back-Cover Texts, in the notice that says that the Document is released +under this License. +.Pp +A \(lqTransparent\(rq copy of the Document means a machine-readable copy, represented +in a format whose specification is available to the general public, whose +contents can be viewed and edited directly and straightforwardly with generic +text editors or (for images composed of pixels) generic paint programs or +(for drawings) some widely available drawing editor, and that is suitable +for input to text formatters or for automatic translation to a variety of +formats suitable for input to text formatters. A copy made in an otherwise +Transparent file format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is not +\(lqTransparent\(rq is called \(lqOpaque.\(rq +.Pp +Examples of suitable formats for Transparent copies include plain ASCII without +markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly +available DTD, and standard-conforming simple HTML designed for human modification. +Opaque formats include PostScript, PDF, proprietary formats that can be read +and edited only by proprietary word processors, SGML or XML for which the +DTD and/or processing tools are not generally available, and the machine-generated +HTML produced by some word processors for output purposes only. +.Pp +The \(lqTitle Page\(rq means, for a printed book, the title page itself, plus such +following pages as are needed to hold, legibly, the material this License +requires to appear in the title page. For works in formats which do not have +any title page as such, \(lqTitle Page\(rq means the text near the most prominent +appearance of the work's title, preceding the beginning of the body of the +text. +.Pp +.It +VERBATIM COPYING +.Pp +You may copy and distribute the Document in any medium, either commercially +or noncommercially, provided that this License, the copyright notices, and +the license notice saying this License applies to the Document are reproduced +in all copies, and that you add no other conditions whatsoever to those of +this License. You may not use technical measures to obstruct or control the +reading or further copying of the copies you make or distribute. However, +you may accept compensation in exchange for copies. If you distribute a large +enough number of copies you must also follow the conditions in section 3. +.Pp +You may also lend copies, under the same conditions stated above, and you +may publicly display copies. +.Pp +.It +COPYING IN QUANTITY +.Pp +If you publish printed copies of the Document numbering more than 100, and +the Document's license notice requires Cover Texts, you must enclose the copies +in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover +Texts on the front cover, and Back-Cover Texts on the back cover. Both covers +must also clearly and legibly identify you as the publisher of these copies. +The front cover must present the full title with all words of the title equally +prominent and visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve the title +of the Document and satisfy these conditions, can be treated as verbatim copying +in other respects. +.Pp +If the required texts for either cover are too voluminous to fit legibly, +you should put the first ones listed (as many as fit reasonably) on the actual +cover, and continue the rest onto adjacent pages. +.Pp +If you publish or distribute Opaque copies of the Document numbering more +than 100, you must either include a machine-readable Transparent copy along +with each Opaque copy, or state in or with each Opaque copy a publicly-accessible +computer-network location containing a complete Transparent copy of the Document, +free of added material, which the general network-using public has access +to download anonymously at no charge using public-standard network protocols. +If you use the latter option, you must take reasonably prudent steps, when +you begin distribution of Opaque copies in quantity, to ensure that this Transparent +copy will remain thus accessible at the stated location until at least one +year after the last time you distribute an Opaque copy (directly or through +your agents or retailers) of that edition to the public. +.Pp +It is requested, but not required, that you contact the authors of the Document +well before redistributing any large number of copies, to give them a chance +to provide you with an updated version of the Document. +.Pp +.It +MODIFICATIONS +.Pp +You may copy and distribute a Modified Version of the Document under the conditions +of sections 2 and 3 above, provided that you release the Modified Version +under precisely this License, with the Modified Version filling the role of +the Document, thus licensing distribution and modification of the Modified +Version to whoever possesses a copy of it. In addition, you must do these +things in the Modified Version: +.Pp +A. Use in the Title Page (and on the covers, if any) a title distinct from +that of the Document, and from those of previous versions (which should, if +there were any, be listed in the History section of the Document). You may +use the same title as a previous version if the original publisher of that +version gives permission. B. List on the Title Page, as authors, one or more +persons or entities responsible for authorship of the modifications in the +Modified Version, together with at least five of the principal authors of +the Document (all of its principal authors, if it has less than five). C. +State on the Title page the name of the publisher of the Modified Version, +as the publisher. D. Preserve all the copyright notices of the Document. +E. Add an appropriate copyright notice for your modifications adjacent to +the other copyright notices. F. Include, immediately after the copyright +notices, a license notice giving the public permission to use the Modified +Version under the terms of this License, in the form shown in the Addendum +below. G. Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. H. Include +an unaltered copy of this License. I. Preserve the section entitled \(lqHistory\(rq, +and its title, and add to it an item stating at least the title, year, new +authors, and publisher of the Modified Version as given on the Title Page. +If there is no section entitled \(lqHistory\(rq in the Document, create one stating +the title, year, authors, and publisher of the Document as given on its Title +Page, then add an item describing the Modified Version as stated in the previous +sentence. J. Preserve the network location, if any, given in the Document +for public access to a Transparent copy of the Document, and likewise the +network locations given in the Document for previous versions it was based +on. These may be placed in the \(lqHistory\(rq section. You may omit a network location +for a work that was published at least four years before the Document itself, +or if the original publisher of the version it refers to gives permission. +K. In any section entitled \(lqAcknowledgements\(rq or \(lqDedications\(rq, preserve the section's +title, and preserve in the section all the substance and tone of each of the +contributor acknowledgements and/or dedications given therein. L. Preserve +all the Invariant Sections of the Document, unaltered in their text and in +their titles. Section numbers or the equivalent are not considered part of +the section titles. M. Delete any section entitled \(lqEndorsements.\(rq Such a section +may not be included in the Modified Version. N. Do not retitle any existing +section as \(lqEndorsements\(rq or to conflict in title with any Invariant Section. +.Pp +If the Modified Version includes new front-matter sections or appendices that +qualify as Secondary Sections and contain no material copied from the Document, +you may at your option designate some or all of these sections as invariant. +To do this, add their titles to the list of Invariant Sections in the Modified +Version's license notice. These titles must be distinct from any other section +titles. +.Pp +You may add a section entitled \(lqEndorsements\(rq, provided it contains nothing +but endorsements of your Modified Version by various parties--for example, +statements of peer review or that the text has been approved by an organization +as the authoritative definition of a standard. +.Pp +You may add a passage of up to five words as a Front-Cover Text, and a passage +of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts +in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover +Text may be added by (or through arrangements made by) any one entity. If +the Document already includes a cover text for the same cover, previously +added by you or by arrangement made by the same entity you are acting on behalf +of, you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. +.Pp +The author(s) and publisher(s) of the Document do not by this License give +permission to use their names for publicity for or to assert or imply endorsement +of any Modified Version. +.Pp +.It +COMBINING DOCUMENTS +.Pp +You may combine the Document with other documents released under this License, +under the terms defined in section 4 above for modified versions, provided +that you include in the combination all of the Invariant Sections of all of +the original documents, unmodified, and list them all as Invariant Sections +of your combined work in its license notice. +.Pp +The combined work need only contain one copy of this License, and multiple +identical Invariant Sections may be replaced with a single copy. If there +are multiple Invariant Sections with the same name but different contents, +make the title of each such section unique by adding at the end of it, in +parentheses, the name of the original author or publisher of that section +if known, or else a unique number. Make the same adjustment to the section +titles in the list of Invariant Sections in the license notice of the combined +work. +.Pp +In the combination, you must combine any sections entitled \(lqHistory\(rq in the +various original documents, forming one section entitled \(lqHistory\(rq; likewise +combine any sections entitled \(lqAcknowledgements\(rq, and any sections entitled +\(lqDedications.\(rq You must delete all sections entitled \(lqEndorsements.\(rq +.Pp +.It +COLLECTIONS OF DOCUMENTS +.Pp +You may make a collection consisting of the Document and other documents released +under this License, and replace the individual copies of this License in the +various documents with a single copy that is included in the collection, provided +that you follow the rules of this License for verbatim copying of each of +the documents in all other respects. +.Pp +You may extract a single document from such a collection, and distribute it +individually under this License, provided you insert a copy of this License +into the extracted document, and follow this License in all other respects +regarding verbatim copying of that document. +.Pp +.It +AGGREGATION WITH INDEPENDENT WORKS +.Pp +A compilation of the Document or its derivatives with other separate and independent +documents or works, in or on a volume of a storage or distribution medium, +does not as a whole count as a Modified Version of the Document, provided +no compilation copyright is claimed for the compilation. Such a compilation +is called an \(lqaggregate\(rq, and this License does not apply to the other self-contained +works thus compiled with the Document, on account of their being thus compiled, +if they are not themselves derivative works of the Document. +.Pp +If the Cover Text requirement of section 3 is applicable to these copies of +the Document, then if the Document is less than one quarter of the entire +aggregate, the Document's Cover Texts may be placed on covers that surround +only the Document within the aggregate. Otherwise they must appear on covers +around the whole aggregate. +.Pp +.It +TRANSLATION +.Pp +Translation is considered a kind of modification, so you may distribute translations +of the Document under the terms of section 4. Replacing Invariant Sections +with translations requires special permission from their copyright holders, +but you may include translations of some or all Invariant Sections in addition +to the original versions of these Invariant Sections. You may include a translation +of this License provided that you also include the original English version +of this License. In case of a disagreement between the translation and the +original English version of this License, the original English version will +prevail. +.Pp +.It +TERMINATION +.Pp +You may not copy, modify, sublicense, or distribute the Document except as +expressly provided for under this License. Any other attempt to copy, modify, +sublicense or distribute the Document is void, and will automatically terminate +your rights under this License. However, parties who have received copies, +or rights, from you under this License will not have their licenses terminated +so long as such parties remain in full compliance. +.Pp +.It +FUTURE REVISIONS OF THIS LICENSE +.Pp +The Free Software Foundation may publish new, revised versions of the GNU +Free Documentation License from time to time. Such new versions will be similar +in spirit to the present version, but may differ in detail to address new +problems or concerns. See http://www.gnu.org/copyleft/. +.Pp +Each version of the License is given a distinguishing version number. If the +Document specifies that a particular numbered version of this License \(lqor any +later version\(rq applies to it, you have the option of following the terms and +conditions either of that specified version or of any later version that has +been published (not as a draft) by the Free Software Foundation. If the Document +does not specify a version number of this License, you may choose any version +ever published (not as a draft) by the Free Software Foundation. +.Pp +.El +.Ss ADDENDUM: How to use this License for your documents +To use this License in a document you have written, include a copy of the +License in the document and put the following copyright and license notices +just after the title page: +.Pp +.Bd -literal -offset indent + +Copyright (C) year your name. +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 +or any later version published by the Free Software Foundation; +with the Invariant Sections being list their titles, with the +Front-Cover Texts being list, and with the Back-Cover Texts being list. +A copy of the license is included in the section entitled "GNU +Free Documentation License." + +.Ed +.Pp +If you have no Invariant Sections, write \(lqwith no Invariant Sections\(rq instead +of saying which ones are invariant. If you have no Front-Cover Texts, write +\(lqno Front-Cover Texts\(rq instead of \(lqFront-Cover Texts being +.Va list +\(rq; likewise for Back-Cover Texts. +.Pp +If your document contains nontrivial examples of program code, we recommend +releasing these examples in parallel under your choice of free software license, +such as the GNU General Public License, to permit their use in free software. +.Pp +.Sh LD Index diff --git a/contrib/binutils/ld/ld.txt b/contrib/binutils/ld/ld.txt deleted file mode 100644 index e4aa1f17d050..000000000000 --- a/contrib/binutils/ld/ld.txt +++ /dev/null @@ -1,6564 +0,0 @@ -START-INFO-DIR-ENTRY -* Ld: (ld). The GNU linker. -END-INFO-DIR-ENTRY - -LD -1 Overview -2 Invocation - 2.1 Command Line Options - 2.1.1 Options Specific to i386 PE Targets - 2.1.2 Options specific to Motorola 68HC11 and 68HC12 targets - 2.2 Environment Variables -3 Linker Scripts - 3.1 Basic Linker Script Concepts - 3.2 Linker Script Format - 3.3 Simple Linker Script Example - 3.4 Simple Linker Script Commands - 3.4.1 Setting the Entry Point - 3.4.2 Commands Dealing with Files - 3.4.3 Commands Dealing with Object File Formats - 3.4.4 Other Linker Script Commands - 3.5 Assigning Values to Symbols - 3.5.1 Simple Assignments - 3.5.2 PROVIDE - 3.5.3 PROVIDE_HIDDEN - 3.5.4 Source Code Reference - 3.6 SECTIONS Command - 3.6.1 Output Section Description - 3.6.2 Output Section Name - 3.6.3 Output Section Address - 3.6.4 Input Section Description - 3.6.4.1 Input Section Basics - 3.6.4.2 Input Section Wildcard Patterns - 3.6.4.3 Input Section for Common Symbols - 3.6.4.4 Input Section and Garbage Collection - 3.6.4.5 Input Section Example - 3.6.5 Output Section Data - 3.6.6 Output Section Keywords - 3.6.7 Output Section Discarding - 3.6.8 Output Section Attributes - 3.6.8.1 Output Section Type - 3.6.8.2 Output Section LMA - 3.6.8.3 Forced Output Alignment - 3.6.8.4 Forced Input Alignment - 3.6.8.5 Output Section Region - 3.6.8.6 Output Section Phdr - 3.6.8.7 Output Section Fill - 3.6.9 Overlay Description - 3.7 MEMORY Command - 3.8 PHDRS Command - 3.9 VERSION Command - 3.10 Expressions in Linker Scripts - 3.10.1 Constants - 3.10.2 Symbol Names - 3.10.3 Orphan Sections - 3.10.4 The Location Counter - 3.10.5 Operators - 3.10.6 Evaluation - 3.10.7 The Section of an Expression - 3.10.8 Builtin Functions - 3.11 Implicit Linker Scripts -4 Machine Dependent Features - 4.1 'ld' and the H8/300 - 4.2 'ld' and the Intel 960 Family - 4.3 'ld' and the Motorola 68HC11 and 68HC12 families - 4.3.1 Linker Relaxation - 4.3.2 Trampoline Generation - 4.4 'ld' and the ARM family - 4.5 'ld' and HPPA 32-bit ELF Support - 4.6 'ld' and MMIX - 4.7 'ld' and MSP430 - 4.8 'ld' and PowerPC 32-bit ELF Support - 4.9 'ld' and PowerPC64 64-bit ELF Support - 4.10 'ld' and SPU ELF Support - 4.11 'ld''s Support for Various TI COFF Versions - 4.12 'ld' and WIN32 (cygwin/mingw) - 4.13 'ld' and Xtensa Processors -5 BFD - 5.1 How It Works: An Outline of BFD - 5.1.1 Information Loss - 5.1.2 The BFD canonical object-file format -6 Reporting Bugs - 6.1 Have You Found a Bug? - 6.2 How to Report Bugs -Appendix A MRI Compatible Script Files -Appendix B GNU Free Documentation License - ADDENDUM: How to use this License for your documents -LD Index -LD -** - -This file documents the GNU linker ld version "2.17.50 [FreeBSD] -2007-07-03". - - 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". - -1 Overview -********** - -'ld' combines a number of object and archive files, relocates their data -and ties up symbol references. Usually the last step in compiling a -program is to run 'ld'. - - 'ld' accepts Linker Command Language files written in a superset of -AT&T's Link Editor Command Language syntax, to provide explicit and -total control over the linking process. - - This version of 'ld' uses the general purpose BFD libraries to -operate on object files. This allows 'ld' to read, combine, and write -object files in many different formats--for example, COFF or 'a.out'. -Different formats may be linked together to produce any available kind -of object file. *Note BFD::, for more information. - - Aside from its flexibility, the GNU linker is more helpful than other -linkers in providing diagnostic information. Many linkers abandon -execution immediately upon encountering an error; whenever possible, -'ld' continues executing, allowing you to identify other errors (or, in -some cases, to get an output file in spite of the error). - -2 Invocation -************ - -The GNU linker 'ld' is meant to cover a broad range of situations, and -to be as compatible as possible with other linkers. As a result, you -have many choices to control its behavior. - -2.1 Command Line Options -======================== - -The linker supports a plethora of command-line options, but in actual -practice few of them are used in any particular context. For instance, -a frequent use of 'ld' is to link standard Unix object files on a -standard, supported Unix system. On such a system, to link a file -'hello.o': - - ld -o OUTPUT /lib/crt0.o hello.o -lc - - This tells 'ld' to produce a file called OUTPUT as the result of -linking the file '/lib/crt0.o' with 'hello.o' and the library 'libc.a', -which will come from the standard search directories. (See the -discussion of the '-l' option below.) - - Some of the command-line options to 'ld' may be specified at any -point in the command line. However, options which refer to files, such -as '-l' or '-T', cause the file to be read at the point at which the -option appears in the command line, relative to the object files and -other file options. Repeating non-file options with a different -argument will either have no further effect, or override prior -occurrences (those further to the left on the command line) of that -option. Options which may be meaningfully specified more than once are -noted in the descriptions below. - - Non-option arguments are object files or archives which are to be -linked together. They may follow, precede, or be mixed in with -command-line options, except that an object file argument may not be -placed between an option and its argument. - - Usually the linker is invoked with at least one object file, but you -can specify other forms of binary input files using '-l', '-R', and the -script command language. If _no_ binary input files at all are -specified, the linker does not produce any output, and issues the -message 'No input files'. - - If the linker cannot recognize the format of an object file, it will -assume that it is a linker script. A script specified in this way -augments the main linker script used for the link (either the default -linker script or the one specified by using '-T'). This feature permits -the linker to link against a file which appears to be an object or an -archive, but actually merely defines some symbol values, or uses 'INPUT' -or 'GROUP' to load other objects. Note that specifying a script in this -way merely augments the main linker script; use the '-T' option to -replace the default linker script entirely. *Note Scripts::. - - For options whose names are a single letter, option arguments must -either follow the option letter without intervening whitespace, or be -given as separate arguments immediately following the option that -requires them. - - For options whose names are multiple letters, either one dash or two -can precede the option name; for example, '-trace-symbol' and -'--trace-symbol' are equivalent. Note--there is one exception to this -rule. Multiple letter options that start with a lower case 'o' can only -be preceded by two dashes. This is to reduce confusion with the '-o' -option. So for example '-omagic' sets the output file name to 'magic' -whereas '--omagic' sets the NMAGIC flag on the output. - - Arguments to multiple-letter options must either be separated from -the option name by an equals sign, or be given as separate arguments -immediately following the option that requires them. For example, -'--trace-symbol foo' and '--trace-symbol=foo' are equivalent. Unique -abbreviations of the names of multiple-letter options are accepted. - - Note--if the linker is being invoked indirectly, via a compiler -driver (e.g. 'gcc') then all the linker command line options should be -prefixed by '-Wl,' (or whatever is appropriate for the particular -compiler driver) like this: - - gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup - - This is important, because otherwise the compiler driver program may -silently drop the linker options, resulting in a bad link. - - Here is a table of the generic command line switches accepted by the -GNU linker: - -'@FILE' - Read command-line options from FILE. The options read are inserted - in place of the original @FILE option. If FILE does not exist, or - cannot be read, then the option will be treated literally, and not - removed. - - Options in 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 FILE may itself contain additional - @FILE options; any such options will be processed recursively. - -'-aKEYWORD' - This option is supported for HP/UX compatibility. The KEYWORD - argument must be one of the strings 'archive', 'shared', or - 'default'. '-aarchive' is functionally equivalent to '-Bstatic', - and the other two keywords are functionally equivalent to - '-Bdynamic'. This option may be used any number of times. - -'-AARCHITECTURE' -'--architecture=ARCHITECTURE' - In the current release of 'ld', this option is useful only for the - Intel 960 family of architectures. In that 'ld' configuration, the - ARCHITECTURE argument identifies the particular architecture in the - 960 family, enabling some safeguards and modifying the - archive-library search path. *Note 'ld' and the Intel 960 family: - i960, for details. - - Future releases of 'ld' may support similar functionality for other - architecture families. - -'-b INPUT-FORMAT' -'--format=INPUT-FORMAT' - 'ld' may be configured to support more than one kind of object - file. If your 'ld' is configured this way, you can use the '-b' - option to specify the binary format for input object files that - follow this option on the command line. Even when 'ld' is - configured to support alternative object formats, you don't usually - need to specify this, as 'ld' should be configured to expect as a - default input format the most usual format on each machine. - INPUT-FORMAT is a text string, the name of a particular format - supported by the BFD libraries. (You can list the available binary - formats with 'objdump -i'.) *Note BFD::. - - You may want to use this option if you are linking files with an - unusual binary format. You can also use '-b' to switch formats - explicitly (when linking object files of different formats), by - including '-b INPUT-FORMAT' before each group of object files in a - particular format. - - The default format is taken from the environment variable - 'GNUTARGET'. *Note Environment::. You can also define the input - format from a script, using the command 'TARGET'; see *note Format - Commands::. - -'-c MRI-COMMANDFILE' -'--mri-script=MRI-COMMANDFILE' - For compatibility with linkers produced by MRI, 'ld' accepts script - files written in an alternate, restricted command language, - described in *note MRI Compatible Script Files: MRI. Introduce MRI - script files with the option '-c'; use the '-T' option to run - linker scripts written in the general-purpose 'ld' scripting - language. If MRI-CMDFILE does not exist, 'ld' looks for it in the - directories specified by any '-L' options. - -'-d' -'-dc' -'-dp' - These three options are equivalent; multiple forms are supported - for compatibility with other linkers. They assign space to common - symbols even if a relocatable output file is specified (with '-r'). - The script command 'FORCE_COMMON_ALLOCATION' has the same effect. - *Note Miscellaneous Commands::. - -'-e ENTRY' -'--entry=ENTRY' - Use ENTRY as the explicit symbol for beginning execution of your - program, rather than the default entry point. If there is no - symbol named ENTRY, the linker will try to parse ENTRY as a number, - and use that as the entry address (the number will be interpreted - in base 10; you may use a leading '0x' for base 16, or a leading - '0' for base 8). *Note Entry Point::, for a discussion of defaults - and other ways of specifying the entry point. - -'--exclude-libs LIB,LIB,...' - Specifies a list of archive libraries from which symbols should not - be automatically exported. The library names may be delimited by - commas or colons. Specifying '--exclude-libs ALL' excludes symbols - in all archive libraries from automatic export. This option is - available only for the i386 PE targeted port of the linker and for - ELF targeted ports. For i386 PE, symbols explicitly listed in a - .def file are still exported, regardless of this option. For ELF - targeted ports, symbols affected by this option will be treated as - hidden. - -'-E' -'--export-dynamic' - When creating a dynamically linked executable, add all symbols to - the dynamic symbol table. The dynamic symbol table is the set of - symbols which are visible from dynamic objects at run time. - - If you do not use this option, the dynamic symbol table will - normally contain only those symbols which are referenced by some - dynamic object mentioned in the link. - - If you use 'dlopen' to load a dynamic object which needs to refer - back to the symbols defined by the program, rather than some other - dynamic object, then you will probably need to use this option when - linking the program itself. - - You can also use the dynamic list to control what symbols should be - added to the dynamic symbol table if the output format supports it. - See the description of '--dynamic-list'. - -'-EB' - Link big-endian objects. This affects the default output format. - -'-EL' - Link little-endian objects. This affects the default output - format. - -'-f' -'--auxiliary NAME' - When creating an ELF shared object, set the internal DT_AUXILIARY - field to the specified name. This tells the dynamic linker that - the symbol table of the shared object should be used as an - auxiliary filter on the symbol table of the shared object NAME. - - If you later link a program against this filter object, then, when - you run the program, the dynamic linker will see the DT_AUXILIARY - field. If the dynamic linker resolves any symbols from the filter - object, it will first check whether there is a definition in the - shared object NAME. If there is one, it will be used instead of - the definition in the filter object. The shared object NAME need - not exist. Thus the shared object NAME may be used to provide an - alternative implementation of certain functions, perhaps for - debugging or for machine specific performance. - - This option may be specified more than once. The DT_AUXILIARY - entries will be created in the order in which they appear on the - command line. - -'-F NAME' -'--filter NAME' - When creating an ELF shared object, set the internal DT_FILTER - field to the specified name. This tells the dynamic linker that - the symbol table of the shared object which is being created should - be used as a filter on the symbol table of the shared object NAME. - - If you later link a program against this filter object, then, when - you run the program, the dynamic linker will see the DT_FILTER - field. The dynamic linker will resolve symbols according to the - symbol table of the filter object as usual, but it will actually - link to the definitions found in the shared object NAME. Thus the - filter object can be used to select a subset of the symbols - provided by the object NAME. - - Some older linkers used the '-F' option throughout a compilation - toolchain for specifying object-file format for both input and - output object files. The GNU linker uses other mechanisms for this - purpose: the '-b', '--format', '--oformat' options, the 'TARGET' - command in linker scripts, and the 'GNUTARGET' environment - variable. The GNU linker will ignore the '-F' option when not - creating an ELF shared object. - -'-fini NAME' - When creating an ELF executable or shared object, call NAME when - the executable or shared object is unloaded, by setting DT_FINI to - the address of the function. By default, the linker uses '_fini' - as the function to call. - -'-g' - Ignored. Provided for compatibility with other tools. - -'-GVALUE' -'--gpsize=VALUE' - Set the maximum size of objects to be optimized using the GP - register to SIZE. This is only meaningful for object file formats - such as MIPS ECOFF which supports putting large and small objects - into different sections. This is ignored for other object file - formats. - -'-hNAME' -'-soname=NAME' - When creating an ELF shared object, set the internal DT_SONAME - field to the specified name. When an executable is linked with a - shared object which has a DT_SONAME field, then when the executable - is run the dynamic linker will attempt to load the shared object - specified by the DT_SONAME field rather than the using the file - name given to the linker. - -'-i' - Perform an incremental link (same as option '-r'). - -'-init NAME' - When creating an ELF executable or shared object, call NAME when - the executable or shared object is loaded, by setting DT_INIT to - the address of the function. By default, the linker uses '_init' - as the function to call. - -'-lNAMESPEC' -'--library=NAMESPEC' - Add the archive or object file specified by NAMESPEC to the list of - files to link. This option may be used any number of times. If - NAMESPEC is of the form ':FILENAME', 'ld' will search the library - path for a file called FILENAME, otherise it will search the - library path for a file called 'libNAMESPEC.a'. - - On systems which support shared libraries, 'ld' may also search for - files other than 'libNAMESPEC.a'. Specifically, on ELF and SunOS - systems, 'ld' will search a directory for a library called - 'libNAMESPEC.so' before searching for one called 'libNAMESPEC.a'. - (By convention, a '.so' extension indicates a shared library.) - Note that this behavior does not apply to ':FILENAME', which always - specifies a file called FILENAME. - - The linker will search an archive only once, at the location where - it is specified on the command line. If the archive defines a - symbol which was undefined in some object which appeared before the - archive on the command line, the linker will include the - appropriate file(s) from the archive. However, an undefined symbol - in an object appearing later on the command line will not cause the - linker to search the archive again. - - See the '-(' option for a way to force the linker to search - archives multiple times. - - You may list the same archive multiple times on the command line. - - This type of archive searching is standard for Unix linkers. - However, if you are using 'ld' on AIX, note that it is different - from the behaviour of the AIX linker. - -'-LSEARCHDIR' -'--library-path=SEARCHDIR' - Add path SEARCHDIR to the list of paths that 'ld' will search for - archive libraries and 'ld' control scripts. You may use this - option any number of times. The directories are searched in the - order in which they are specified on the command line. Directories - specified on the command line are searched before the default - directories. All '-L' options apply to all '-l' options, - regardless of the order in which the options appear. - - If SEARCHDIR begins with '=', then the '=' will be replaced by the - "sysroot prefix", a path specified when the linker is configured. - - The default set of paths searched (without being specified with - '-L') depends on which emulation mode 'ld' is using, and in some - cases also on how it was configured. *Note Environment::. - - The paths can also be specified in a link script with the - 'SEARCH_DIR' command. Directories specified this way are searched - at the point in which the linker script appears in the command - line. - -'-mEMULATION' - Emulate the EMULATION linker. You can list the available - emulations with the '--verbose' or '-V' options. - - If the '-m' option is not used, the emulation is taken from the - 'LDEMULATION' environment variable, if that is defined. - - Otherwise, the default emulation depends upon how the linker was - configured. - -'-M' -'--print-map' - Print a link map to the standard output. A link map provides - information about the link, including the following: - - * Where object files are mapped into memory. - * How common symbols are allocated. - * All archive members included in the link, with a mention of - the symbol which caused the archive member to be brought in. - * The values assigned to symbols. - - Note - symbols whose values are computed by an expression - which involves a reference to a previous value of the same - symbol may not have correct result displayed in the link map. - This is because the linker discards intermediate results and - only retains the final value of an expression. Under such - circumstances the linker will display the final value enclosed - by square brackets. Thus for example a linker script - containing: - - foo = 1 - foo = foo * 4 - foo = foo + 8 - - will produce the following output in the link map if the '-M' - option is used: - - 0x00000001 foo = 0x1 - [0x0000000c] foo = (foo * 0x4) - [0x0000000c] foo = (foo + 0x8) - - See *note Expressions:: for more information about expressions - in linker scripts. - -'-n' -'--nmagic' - Turn off page alignment of sections, and mark the output as - 'NMAGIC' if possible. - -'-N' -'--omagic' - Set the text and data sections to be readable and writable. Also, - do not page-align the data segment, and disable linking against - shared libraries. If the output format supports Unix style magic - numbers, mark the output as 'OMAGIC'. Note: Although a writable - text section is allowed for PE-COFF targets, it does not conform to - the format specification published by Microsoft. - -'--no-omagic' - This option negates most of the effects of the '-N' option. It - sets the text section to be read-only, and forces the data segment - to be page-aligned. Note - this option does not enable linking - against shared libraries. Use '-Bdynamic' for this. - -'-o OUTPUT' -'--output=OUTPUT' - Use OUTPUT as the name for the program produced by 'ld'; if this - option is not specified, the name 'a.out' is used by default. The - script command 'OUTPUT' can also specify the output file name. - -'-O LEVEL' - If LEVEL is a numeric values greater than zero 'ld' optimizes the - output. This might take significantly longer and therefore - probably should only be enabled for the final binary. - -'-q' -'--emit-relocs' - Leave relocation sections and contents in fully linked executables. - Post link analysis and optimization tools may need this information - in order to perform correct modifications of executables. This - results in larger executables. - - This option is currently only supported on ELF platforms. - -'--force-dynamic' - Force the output file to have dynamic sections. This option is - specific to VxWorks targets. - -'-r' -'--relocatable' - Generate relocatable output--i.e., generate an output file that can - in turn serve as input to 'ld'. This is often called "partial - linking". As a side effect, in environments that support standard - Unix magic numbers, this option also sets the output file's magic - number to 'OMAGIC'. If this option is not specified, an absolute - file is produced. When linking C++ programs, this option _will - not_ resolve references to constructors; to do that, use '-Ur'. - - When an input file does not have the same format as the output - file, partial linking is only supported if that input file does not - contain any relocations. Different output formats can have further - restrictions; for example some 'a.out'-based formats do not support - partial linking with input files in other formats at all. - - This option does the same thing as '-i'. - -'-R FILENAME' -'--just-symbols=FILENAME' - Read symbol names and their addresses from FILENAME, but do not - relocate it or include it in the output. This allows your output - file to refer symbolically to absolute locations of memory defined - in other programs. You may use this option more than once. - - For compatibility with other ELF linkers, if the '-R' option is - followed by a directory name, rather than a file name, it is - treated as the '-rpath' option. - -'-s' -'--strip-all' - Omit all symbol information from the output file. - -'-S' -'--strip-debug' - Omit debugger symbol information (but not all symbols) from the - output file. - -'-t' -'--trace' - Print the names of the input files as 'ld' processes them. - -'-T SCRIPTFILE' -'--script=SCRIPTFILE' - Use SCRIPTFILE as the linker script. This script replaces 'ld''s - default linker script (rather than adding to it), so COMMANDFILE - must specify everything necessary to describe the output file. - *Note Scripts::. If SCRIPTFILE does not exist in the current - directory, 'ld' looks for it in the directories specified by any - preceding '-L' options. Multiple '-T' options accumulate. - -'-dT SCRIPTFILE' -'--default-script=SCRIPTFILE' - Use SCRIPTFILE as the default linker script. *Note Scripts::. - - This option is similar to the '--script' option except that - processing of the script is delayed until after the rest of the - command line has been processed. This allows options placed after - the '--default-script' option on the command line to affect the - behaviour of the linker script, which can be important when the - linker command line cannot be directly controlled by the user. (eg - because the command line is being constructed by another tool, such - as 'gcc'). - -'-u SYMBOL' -'--undefined=SYMBOL' - Force SYMBOL to be entered in the output file as an undefined - symbol. Doing this may, for example, trigger linking of additional - modules from standard libraries. '-u' may be repeated with - different option arguments to enter additional undefined symbols. - This option is equivalent to the 'EXTERN' linker script command. - -'-Ur' - For anything other than C++ programs, this option is equivalent to - '-r': it generates relocatable output--i.e., an output file that - can in turn serve as input to 'ld'. When linking C++ programs, - '-Ur' _does_ resolve references to constructors, unlike '-r'. It - does not work to use '-Ur' on files that were themselves linked - with '-Ur'; once the constructor table has been built, it cannot be - added to. Use '-Ur' only for the last partial link, and '-r' for - the others. - -'--unique[=SECTION]' - Creates a separate output section for every input section matching - SECTION, or if the optional wildcard SECTION argument is missing, - for every orphan input section. An orphan section is one not - specifically mentioned in a linker script. You may use this option - multiple times on the command line; It prevents the normal merging - of input sections with the same name, overriding output section - assignments in a linker script. - -'-v' -'--version' -'-V' - Display the version number for 'ld'. The '-V' option also lists - the supported emulations. - -'-x' -'--discard-all' - Delete all local symbols. - -'-X' -'--discard-locals' - Delete all temporary local symbols. (These symbols start with - system-specific local label prefixes, typically '.L' for ELF - systems or 'L' for traditional a.out systems.) - -'-y SYMBOL' -'--trace-symbol=SYMBOL' - Print the name of each linked file in which SYMBOL appears. This - option may be given any number of times. On many systems it is - necessary to prepend an underscore. - - This option is useful when you have an undefined symbol in your - link but don't know where the reference is coming from. - -'-Y PATH' - Add PATH to the default library search path. This option exists - for Solaris compatibility. - -'-z KEYWORD' - The recognized keywords are: - - 'combreloc' - Combines multiple reloc sections and sorts them to make - dynamic symbol lookup caching possible. - - 'defs' - Disallows undefined symbols in object files. Undefined - symbols in shared libraries are still allowed. - - 'execstack' - Marks the object as requiring executable stack. - - 'initfirst' - This option is only meaningful when building a shared object. - It marks the object so that its runtime initialization will - occur before the runtime initialization of any other objects - brought into the process at the same time. Similarly the - runtime finalization of the object will occur after the - runtime finalization of any other objects. - - 'interpose' - Marks the object that its symbol table interposes before all - symbols but the primary executable. - - 'lazy' - When generating an executable or shared library, mark it to - tell the dynamic linker to defer function call resolution to - the point when the function is called (lazy binding), rather - than at load time. Lazy binding is the default. - - 'loadfltr' - Marks the object that its filters be processed immediately at - runtime. - - 'muldefs' - Allows multiple definitions. - - 'nocombreloc' - Disables multiple reloc sections combining. - - 'nocopyreloc' - Disables production of copy relocs. - - 'nodefaultlib' - Marks the object that the search for dependencies of this - object will ignore any default library search paths. - - 'nodelete' - Marks the object shouldn't be unloaded at runtime. - - 'nodlopen' - Marks the object not available to 'dlopen'. - - 'nodump' - Marks the object can not be dumped by 'dldump'. - - 'noexecstack' - Marks the object as not requiring executable stack. - - 'norelro' - Don't create an ELF 'PT_GNU_RELRO' segment header in the - object. - - 'now' - When generating an executable or shared library, mark it to - tell the dynamic linker to resolve all symbols when the - program is started, or when the shared library is linked to - using dlopen, instead of deferring function call resolution to - the point when the function is first called. - - 'origin' - Marks the object may contain $ORIGIN. - - 'relro' - Create an ELF 'PT_GNU_RELRO' segment header in the object. - - 'max-page-size=VALUE' - Set the emulation maximum page size to VALUE. - - 'common-page-size=VALUE' - Set the emulation common page size to VALUE. - - Other keywords are ignored for Solaris compatibility. - -'-( ARCHIVES -)' -'--start-group ARCHIVES --end-group' - The ARCHIVES should be a list of archive files. They may be either - explicit file names, or '-l' options. - - The specified archives are searched repeatedly until no new - undefined references are created. Normally, an archive is searched - only once in the order that it is specified on the command line. - If a symbol in that archive is needed to resolve an undefined - symbol referred to by an object in an archive that appears later on - the command line, the linker would not be able to resolve that - reference. By grouping the archives, they all be searched - repeatedly until all possible references are resolved. - - Using this option has a significant performance cost. It is best - to use it only when there are unavoidable circular references - between two or more archives. - -'--accept-unknown-input-arch' -'--no-accept-unknown-input-arch' - Tells the linker to accept input files whose architecture cannot be - recognised. The assumption is that the user knows what they are - doing and deliberately wants to link in these unknown input files. - This was the default behaviour of the linker, before release 2.14. - The default behaviour from release 2.14 onwards is to reject such - input files, and so the '--accept-unknown-input-arch' option has - been added to restore the old behaviour. - -'--as-needed' -'--no-as-needed' - This option affects ELF DT_NEEDED tags for dynamic libraries - mentioned on the command line after the '--as-needed' option. - Normally, the linker will add a DT_NEEDED tag for each dynamic - library mentioned on the command line, regardless of whether the - library is actually needed. '--as-needed' causes DT_NEEDED tags to - only be emitted for libraries that satisfy some symbol reference - from regular objects which is undefined at the point that the - library was linked. '--no-as-needed' restores the default - behaviour. - -'--add-needed' -'--no-add-needed' - This option affects the treatment of dynamic libraries from ELF - DT_NEEDED tags in dynamic libraries mentioned on the command line - after the '--no-add-needed' option. Normally, the linker will add - a DT_NEEDED tag for each dynamic library from DT_NEEDED tags. - '--no-add-needed' causes DT_NEEDED tags will never be emitted for - those libraries from DT_NEEDED tags. '--add-needed' restores the - default behaviour. - -'-assert KEYWORD' - This option is ignored for SunOS compatibility. - -'-Bdynamic' -'-dy' -'-call_shared' - Link against dynamic libraries. This is only meaningful on - platforms for which shared libraries are supported. This option is - normally the default on such platforms. The different variants of - this option are for compatibility with various systems. You may - use this option multiple times on the command line: it affects - library searching for '-l' options which follow it. - -'-Bgroup' - Set the 'DF_1_GROUP' flag in the 'DT_FLAGS_1' entry in the dynamic - section. This causes the runtime linker to handle lookups in this - object and its dependencies to be performed only inside the group. - '--unresolved-symbols=report-all' is implied. This option is only - meaningful on ELF platforms which support shared libraries. - -'-Bstatic' -'-dn' -'-non_shared' -'-static' - Do not link against shared libraries. This is only meaningful on - platforms for which shared libraries are supported. The different - variants of this option are for compatibility with various systems. - You may use this option multiple times on the command line: it - affects library searching for '-l' options which follow it. This - option also implies '--unresolved-symbols=report-all'. This option - can be used with '-shared'. Doing so means that a shared library - is being created but that all of the library's external references - must be resolved by pulling in entries from static libraries. - -'-Bsymbolic' - When creating a shared library, bind references to global symbols - to the definition within the shared library, if any. Normally, it - is possible for a program linked against a shared library to - override the definition within the shared library. This option is - only meaningful on ELF platforms which support shared libraries. - -'-Bsymbolic-functions' - When creating a shared library, bind references to global function - symbols to the definition within the shared library, if any. This - option is only meaningful on ELF platforms which support shared - libraries. - -'--dynamic-list=DYNAMIC-LIST-FILE' - Specify the name of a dynamic list file to the linker. This is - typically used when creating shared libraries to specify a list of - global symbols whose references shouldn't be bound to the - definition within the shared library, or creating dynamically - linked executables to specify a list of symbols which should be - added to the symbol table in the executable. This option is only - meaningful on ELF platforms which support shared libraries. - - The format of the dynamic list is the same as the version node - without scope and node name. See *note VERSION:: for more - information. - -'--dynamic-list-data' - Include all global data symbols to the dynamic list. - -'--dynamic-list-cpp-new' - Provide the builtin dynamic list for C++ operator new and delete. - It is mainly useful for building shared libstdc++. - -'--dynamic-list-cpp-typeinfo' - Provide the builtin dynamic list for C++ runtime type - identification. - -'--check-sections' -'--no-check-sections' - Asks the linker _not_ to check section addresses after they have - been assigned to see if there are any overlaps. Normally the - linker will perform this check, and if it finds any overlaps it - will produce suitable error messages. The linker does know about, - and does make allowances for sections in overlays. The default - behaviour can be restored by using the command line switch - '--check-sections'. - -'--cref' - Output a cross reference table. If a linker map file is being - generated, the cross reference table is printed to the map file. - Otherwise, it is printed on the standard output. - - The format of the table is intentionally simple, so that it may be - easily processed by a script if necessary. The symbols are printed - out, sorted by name. For each symbol, a list of file names is - given. If the symbol is defined, the first file listed is the - location of the definition. The remaining files contain references - to the symbol. - -'--no-define-common' - This option inhibits the assignment of addresses to common symbols. - The script command 'INHIBIT_COMMON_ALLOCATION' has the same effect. - *Note Miscellaneous Commands::. - - The '--no-define-common' option allows decoupling the decision to - assign addresses to Common symbols from the choice of the output - file type; otherwise a non-Relocatable output type forces assigning - addresses to Common symbols. Using '--no-define-common' allows - Common symbols that are referenced from a shared library to be - assigned addresses only in the main program. This eliminates the - unused duplicate space in the shared library, and also prevents any - possible confusion over resolving to the wrong duplicate when there - are many dynamic modules with specialized search paths for runtime - symbol resolution. - -'--defsym SYMBOL=EXPRESSION' - Create a global symbol in the output file, containing the absolute - address given by EXPRESSION. You may use this option as many times - as necessary to define multiple symbols in the command line. A - limited form of arithmetic is supported for the EXPRESSION in this - context: you may give a hexadecimal constant or the name of an - existing symbol, or use '+' and '-' to add or subtract hexadecimal - constants or symbols. If you need more elaborate expressions, - consider using the linker command language from a script (*note - Assignment: Symbol Definitions: Assignments.). _Note:_ there - should be no white space between SYMBOL, the equals sign ("<=>"), - and EXPRESSION. - -'--demangle[=STYLE]' -'--no-demangle' - These options control whether to demangle symbol names in error - messages and other output. When the linker is told to demangle, it - tries to present symbol names in a readable fashion: it strips - leading underscores if they are used by the object file format, and - converts C++ mangled symbol names into user readable names. - Different compilers have different mangling styles. The optional - demangling style argument can be used to choose an appropriate - demangling style for your compiler. The linker will demangle by - default unless the environment variable 'COLLECT_NO_DEMANGLE' is - set. These options may be used to override the default. - -'--dynamic-linker FILE' - Set the name of the dynamic linker. This is only meaningful when - generating dynamically linked ELF executables. The default dynamic - linker is normally correct; don't use this unless you know what you - are doing. - -'--fatal-warnings' - Treat all warnings as errors. - -'--force-exe-suffix' - Make sure that an output file has a .exe suffix. - - If a successfully built fully linked output file does not have a - '.exe' or '.dll' suffix, this option forces the linker to copy the - output file to one of the same name with a '.exe' suffix. This - option is useful when using unmodified Unix makefiles on a - Microsoft Windows host, since some versions of Windows won't run an - image unless it ends in a '.exe' suffix. - -'--gc-sections' -'--no-gc-sections' - Enable garbage collection of unused input sections. It is ignored - on targets that do not support this option. This option is not - compatible with '-r' or '--emit-relocs'. The default behaviour (of - not performing this garbage collection) can be restored by - specifying '--no-gc-sections' on the command line. - -'--print-gc-sections' -'--no-print-gc-sections' - List all sections removed by garbage collection. The listing is - printed on stderr. This option is only effective if garbage - collection has been enabled via the '--gc-sections') option. The - default behaviour (of not listing the sections that are removed) - can be restored by specifying '--no-print-gc-sections' on the - command line. - -'--help' - Print a summary of the command-line options on the standard output - and exit. - -'--target-help' - Print a summary of all target specific options on the standard - output and exit. - -'-Map MAPFILE' - Print a link map to the file MAPFILE. See the description of the - '-M' option, above. - -'--no-keep-memory' - 'ld' normally optimizes for speed over memory usage by caching the - symbol tables of input files in memory. This option tells 'ld' to - instead optimize for memory usage, by rereading the symbol tables - as necessary. This may be required if 'ld' runs out of memory - space while linking a large executable. - -'--no-undefined' -'-z defs' - Report unresolved symbol references from regular object files. - This is done even if the linker is creating a non-symbolic shared - library. The switch '--[no-]allow-shlib-undefined' controls the - behaviour for reporting unresolved references found in shared - libraries being linked in. - -'--allow-multiple-definition' -'-z muldefs' - Normally when a symbol is defined multiple times, the linker will - report a fatal error. These options allow multiple definitions and - the first definition will be used. - -'--allow-shlib-undefined' -'--no-allow-shlib-undefined' - Allows (the default) or disallows undefined symbols in shared - libraries. This switch is similar to '--no-undefined' except that - it determines the behaviour when the undefined symbols are in a - shared library rather than a regular object file. It does not - affect how undefined symbols in regular object files are handled. - - The reason that '--allow-shlib-undefined' is the default is that - the shared library being specified at link time may not be the same - as the one that is available at load time, so the symbols might - actually be resolvable at load time. Plus there are some systems, - (eg BeOS) where undefined symbols in shared libraries is normal. - (The kernel patches them at load time to select which function is - most appropriate for the current architecture. This is used for - example to dynamically select an appropriate memset function). - Apparently it is also normal for HPPA shared libraries to have - undefined symbols. - -'--no-undefined-version' - Normally when a symbol has an undefined version, the linker will - ignore it. This option disallows symbols with undefined version - and a fatal error will be issued instead. - -'--default-symver' - Create and use a default symbol version (the soname) for - unversioned exported symbols. - -'--default-imported-symver' - Create and use a default symbol version (the soname) for - unversioned imported symbols. - -'--no-warn-mismatch' - Normally 'ld' will give an error if you try to link together input - files that are mismatched for some reason, perhaps because they - have been compiled for different processors or for different - endiannesses. This option tells 'ld' that it should silently - permit such possible errors. This option should only be used with - care, in cases when you have taken some special action that ensures - that the linker errors are inappropriate. - -'--no-warn-search-mismatch' - Normally 'ld' will give a warning if it finds an incompatible - library during a library search. This option silences the warning. - -'--no-whole-archive' - Turn off the effect of the '--whole-archive' option for subsequent - archive files. - -'--noinhibit-exec' - Retain the executable output file whenever it is still usable. - Normally, the linker will not produce an output file if it - encounters errors during the link process; it exits without writing - an output file when it issues any error whatsoever. - -'-nostdlib' - Only search library directories explicitly specified on the command - line. Library directories specified in linker scripts (including - linker scripts specified on the command line) are ignored. - -'--oformat OUTPUT-FORMAT' - 'ld' may be configured to support more than one kind of object - file. If your 'ld' is configured this way, you can use the - '--oformat' option to specify the binary format for the output - object file. Even when 'ld' is configured to support alternative - object formats, you don't usually need to specify this, as 'ld' - should be configured to produce as a default output format the most - usual format on each machine. OUTPUT-FORMAT is a text string, the - name of a particular format supported by the BFD libraries. (You - can list the available binary formats with 'objdump -i'.) The - script command 'OUTPUT_FORMAT' can also specify the output format, - but this option overrides it. *Note BFD::. - -'-pie' -'--pic-executable' - Create a position independent executable. This is currently only - supported on ELF platforms. Position independent executables are - similar to shared libraries in that they are relocated by the - dynamic linker to the virtual address the OS chooses for them - (which can vary between invocations). Like normal dynamically - linked executables they can be executed and symbols defined in the - executable cannot be overridden by shared libraries. - -'-qmagic' - This option is ignored for Linux compatibility. - -'-Qy' - This option is ignored for SVR4 compatibility. - -'--relax' - An option with machine dependent effects. This option is only - supported on a few targets. *Note 'ld' and the H8/300: H8/300. - *Note 'ld' and the Intel 960 family: i960. *Note 'ld' and Xtensa - Processors: Xtensa. *Note 'ld' and the 68HC11 and 68HC12: - M68HC11/68HC12. *Note 'ld' and PowerPC 32-bit ELF Support: PowerPC - ELF32. - - On some platforms, the '--relax' option performs global - optimizations that become possible when the linker resolves - addressing in the program, such as relaxing address modes and - synthesizing new instructions in the output object file. - - On some platforms these link time global optimizations may make - symbolic debugging of the resulting executable impossible. This is - known to be the case for the Matsushita MN10200 and MN10300 family - of processors. - - On platforms where this is not supported, '--relax' is accepted, - but ignored. - -'--retain-symbols-file FILENAME' - Retain _only_ the symbols listed in the file FILENAME, discarding - all others. FILENAME is simply a flat file, with one symbol name - per line. This option is especially useful in environments (such - as VxWorks) where a large global symbol table is accumulated - gradually, to conserve run-time memory. - - '--retain-symbols-file' does _not_ discard undefined symbols, or - symbols needed for relocations. - - You may only specify '--retain-symbols-file' once in the command - line. It overrides '-s' and '-S'. - -'-rpath DIR' - Add a directory to the runtime library search path. This is used - when linking an ELF executable with shared objects. All '-rpath' - arguments are concatenated and passed to the runtime linker, which - uses them to locate shared objects at runtime. The '-rpath' option - is also used when locating shared objects which are needed by - shared objects explicitly included in the link; see the description - of the '-rpath-link' option. If '-rpath' is not used when linking - an ELF executable, the contents of the environment variable - 'LD_RUN_PATH' will be used if it is defined. - - The '-rpath' option may also be used on SunOS. By default, on - SunOS, the linker will form a runtime search patch out of all the - '-L' options it is given. If a '-rpath' option is used, the - runtime search path will be formed exclusively using the '-rpath' - options, ignoring the '-L' options. This can be useful when using - gcc, which adds many '-L' options which may be on NFS mounted file - systems. - - For compatibility with other ELF linkers, if the '-R' option is - followed by a directory name, rather than a file name, it is - treated as the '-rpath' option. - -'-rpath-link DIR' - When using ELF or SunOS, one shared library may require another. - This happens when an 'ld -shared' link includes a shared library as - one of the input files. - - When the linker encounters such a dependency when doing a - non-shared, non-relocatable link, it will automatically try to - locate the required shared library and include it in the link, if - it is not included explicitly. In such a case, the '-rpath-link' - option specifies the first set of directories to search. The - '-rpath-link' option may specify a sequence of directory names - either by specifying a list of names separated by colons, or by - appearing multiple times. - - This option should be used with caution as it overrides the search - path that may have been hard compiled into a shared library. In - such a case it is possible to use unintentionally a different - search path than the runtime linker would do. - - The linker uses the following search paths to locate required - shared libraries: - 1. Any directories specified by '-rpath-link' options. - 2. Any directories specified by '-rpath' options. The difference - between '-rpath' and '-rpath-link' is that directories - specified by '-rpath' options are included in the executable - and used at runtime, whereas the '-rpath-link' option is only - effective at link time. Searching '-rpath' in this way is - only supported by native linkers and cross linkers which have - been configured with the '--with-sysroot' option. - 3. On an ELF system, if the '-rpath' and 'rpath-link' options - were not used, search the contents of the environment variable - 'LD_RUN_PATH'. It is for the native linker only. - 4. On SunOS, if the '-rpath' option was not used, search any - directories specified using '-L' options. - 5. For a native linker, the contents of the environment variable - 'LD_LIBRARY_PATH'. - 6. For a native ELF linker, the directories in 'DT_RUNPATH' or - 'DT_RPATH' of a shared library are searched for shared - libraries needed by it. The 'DT_RPATH' entries are ignored if - 'DT_RUNPATH' entries exist. - 7. The default directories, normally '/lib' and '/usr/lib'. - 8. For a native linker on an ELF system, if the file - '/etc/ld.so.conf' exists, the list of directories found in - that file. - - If the required shared library is not found, the linker will issue - a warning and continue with the link. - -'-shared' -'-Bshareable' - Create a shared library. This is currently only supported on ELF, - XCOFF and SunOS platforms. On SunOS, the linker will automatically - create a shared library if the '-e' option is not used and there - are undefined symbols in the link. - -'--sort-common' - This option tells 'ld' to sort the common symbols by size when it - places them in the appropriate output sections. First come all the - one byte symbols, then all the two byte, then all the four byte, - and then everything else. This is to prevent gaps between symbols - due to alignment constraints. - -'--sort-section name' - This option will apply 'SORT_BY_NAME' to all wildcard section - patterns in the linker script. - -'--sort-section alignment' - This option will apply 'SORT_BY_ALIGNMENT' to all wildcard section - patterns in the linker script. - -'--split-by-file [SIZE]' - Similar to '--split-by-reloc' but creates a new output section for - each input file when SIZE is reached. SIZE defaults to a size of 1 - if not given. - -'--split-by-reloc [COUNT]' - Tries to creates extra sections in the output file so that no - single output section in the file contains more than COUNT - relocations. This is useful when generating huge relocatable files - for downloading into certain real time kernels with the COFF object - file format; since COFF cannot represent more than 65535 - relocations in a single section. Note that this will fail to work - with object file formats which do not support arbitrary sections. - The linker will not split up individual input sections for - redistribution, so if a single input section contains more than - COUNT relocations one output section will contain that many - relocations. COUNT defaults to a value of 32768. - -'--stats' - Compute and display statistics about the operation of the linker, - such as execution time and memory usage. - -'--sysroot=DIRECTORY' - Use DIRECTORY as the location of the sysroot, overriding the - configure-time default. This option is only supported by linkers - that were configured using '--with-sysroot'. - -'--traditional-format' - For some targets, the output of 'ld' is different in some ways from - the output of some existing linker. This switch requests 'ld' to - use the traditional format instead. - - For example, on SunOS, 'ld' combines duplicate entries in the - symbol string table. This can reduce the size of an output file - with full debugging information by over 30 percent. Unfortunately, - the SunOS 'dbx' program can not read the resulting program ('gdb' - has no trouble). The '--traditional-format' switch tells 'ld' to - not combine duplicate entries. - -'--section-start SECTIONNAME=ORG' - Locate a section in the output file at the absolute address given - by ORG. You may use this option as many times as necessary to - locate multiple sections in the command line. ORG must be a single - hexadecimal integer; for compatibility with other linkers, you may - omit the leading '0x' usually associated with hexadecimal values. - _Note:_ there should be no white space between SECTIONNAME, the - equals sign ("<=>"), and ORG. - -'-Tbss ORG' -'-Tdata ORG' -'-Ttext ORG' - Same as -section-start, with '.bss', '.data' or '.text' as the - SECTIONNAME. - -'--unresolved-symbols=METHOD' - Determine how to handle unresolved symbols. There are four - possible values for 'method': - - 'ignore-all' - Do not report any unresolved symbols. - - 'report-all' - Report all unresolved symbols. This is the default. - - 'ignore-in-object-files' - Report unresolved symbols that are contained in shared - libraries, but ignore them if they come from regular object - files. - - 'ignore-in-shared-libs' - Report unresolved symbols that come from regular object files, - but ignore them if they come from shared libraries. This can - be useful when creating a dynamic binary and it is known that - all the shared libraries that it should be referencing are - included on the linker's command line. - - The behaviour for shared libraries on their own can also be - controlled by the '--[no-]allow-shlib-undefined' option. - - Normally the linker will generate an error message for each - reported unresolved symbol but the option - '--warn-unresolved-symbols' can change this to a warning. - -'--dll-verbose' -'--verbose' - Display the version number for 'ld' and list the linker emulations - supported. Display which input files can and cannot be opened. - Display the linker script being used by the linker. - -'--version-script=VERSION-SCRIPTFILE' - Specify the name of a version script to the linker. This is - typically used when creating shared libraries to specify additional - information about the version hierarchy for the library being - created. This option is only meaningful on ELF platforms which - support shared libraries. *Note VERSION::. - -'--warn-common' - Warn when a common symbol is combined with another common symbol or - with a symbol definition. Unix linkers allow this somewhat sloppy - practise, but linkers on some other operating systems do not. This - option allows you to find potential problems from combining global - symbols. Unfortunately, some C libraries use this practise, so you - may get some warnings about symbols in the libraries as well as in - your programs. - - There are three kinds of global symbols, illustrated here by C - examples: - - 'int i = 1;' - A definition, which goes in the initialized data section of - the output file. - - 'extern int i;' - An undefined reference, which does not allocate space. There - must be either a definition or a common symbol for the - variable somewhere. - - 'int i;' - A common symbol. If there are only (one or more) common - symbols for a variable, it goes in the uninitialized data area - of the output file. The linker merges multiple common symbols - for the same variable into a single symbol. If they are of - different sizes, it picks the largest size. The linker turns - a common symbol into a declaration, if there is a definition - of the same variable. - - The '--warn-common' option can produce five kinds of warnings. - Each warning consists of a pair of lines: the first describes the - symbol just encountered, and the second describes the previous - symbol encountered with the same name. One or both of the two - symbols will be a common symbol. - - 1. Turning a common symbol into a reference, because there is - already a definition for the symbol. - FILE(SECTION): warning: common of `SYMBOL' - overridden by definition - FILE(SECTION): warning: defined here - - 2. Turning a common symbol into a reference, because a later - definition for the symbol is encountered. This is the same as - the previous case, except that the symbols are encountered in - a different order. - FILE(SECTION): warning: definition of `SYMBOL' - overriding common - FILE(SECTION): warning: common is here - - 3. Merging a common symbol with a previous same-sized common - symbol. - FILE(SECTION): warning: multiple common - of `SYMBOL' - FILE(SECTION): warning: previous common is here - - 4. Merging a common symbol with a previous larger common symbol. - FILE(SECTION): warning: common of `SYMBOL' - overridden by larger common - FILE(SECTION): warning: larger common is here - - 5. Merging a common symbol with a previous smaller common symbol. - This is the same as the previous case, except that the symbols - are encountered in a different order. - FILE(SECTION): warning: common of `SYMBOL' - overriding smaller common - FILE(SECTION): warning: smaller common is here - -'--warn-constructors' - Warn if any global constructors are used. This is only useful for - a few object file formats. For formats like COFF or ELF, the - linker can not detect the use of global constructors. - -'--warn-multiple-gp' - Warn if multiple global pointer values are required in the output - file. This is only meaningful for certain processors, such as the - Alpha. Specifically, some processors put large-valued constants in - a special section. A special register (the global pointer) points - into the middle of this section, so that constants can be loaded - efficiently via a base-register relative addressing mode. Since - the offset in base-register relative mode is fixed and relatively - small (e.g., 16 bits), this limits the maximum size of the constant - pool. Thus, in large programs, it is often necessary to use - multiple global pointer values in order to be able to address all - possible constants. This option causes a warning to be issued - whenever this case occurs. - -'--warn-once' - Only warn once for each undefined symbol, rather than once per - module which refers to it. - -'--warn-section-align' - Warn if the address of an output section is changed because of - alignment. Typically, the alignment will be set by an input - section. The address will only be changed if it not explicitly - specified; that is, if the 'SECTIONS' command does not specify a - start address for the section (*note SECTIONS::). - -'--warn-shared-textrel' - Warn if the linker adds a DT_TEXTREL to a shared object. - -'--warn-unresolved-symbols' - If the linker is going to report an unresolved symbol (see the - option '--unresolved-symbols') it will normally generate an error. - This option makes it generate a warning instead. - -'--error-unresolved-symbols' - This restores the linker's default behaviour of generating errors - when it is reporting unresolved symbols. - -'--whole-archive' - For each archive mentioned on the command line after the - '--whole-archive' option, include every object file in the archive - in the link, rather than searching the archive for the required - object files. This is normally used to turn an archive file into a - shared library, forcing every object to be included in the - resulting shared library. This option may be used more than once. - - Two notes when using this option from gcc: First, gcc doesn't know - about this option, so you have to use '-Wl,-whole-archive'. - Second, don't forget to use '-Wl,-no-whole-archive' after your list - of archives, because gcc will add its own list of archives to your - link and you may not want this flag to affect those as well. - -'--wrap SYMBOL' - Use a wrapper function for SYMBOL. Any undefined reference to - SYMBOL will be resolved to '__wrap_SYMBOL'. Any undefined - reference to '__real_SYMBOL' will be resolved to SYMBOL. - - This can be used to provide a wrapper for a system function. The - wrapper function should be called '__wrap_SYMBOL'. If it wishes to - call the system function, it should call '__real_SYMBOL'. - - Here is a trivial example: - - void * - __wrap_malloc (size_t c) - { - printf ("malloc called with %zu\n", c); - return __real_malloc (c); - } - - If you link other code with this file using '--wrap malloc', then - all calls to 'malloc' will call the function '__wrap_malloc' - instead. The call to '__real_malloc' in '__wrap_malloc' will call - the real 'malloc' function. - - You may wish to provide a '__real_malloc' function as well, so that - links without the '--wrap' option will succeed. If you do this, - you should not put the definition of '__real_malloc' in the same - file as '__wrap_malloc'; if you do, the assembler may resolve the - call before the linker has a chance to wrap it to 'malloc'. - -'--eh-frame-hdr' - Request creation of '.eh_frame_hdr' section and ELF - 'PT_GNU_EH_FRAME' segment header. - -'--enable-new-dtags' -'--disable-new-dtags' - This linker can create the new dynamic tags in ELF. But the older - ELF systems may not understand them. If you specify - '--enable-new-dtags', the dynamic tags will be created as needed. - If you specify '--disable-new-dtags', no new dynamic tags will be - created. By default, the new dynamic tags are not created. Note - that those options are only available for ELF systems. - -'--hash-size=NUMBER' - Set the default size of the linker's hash tables to a prime number - close to NUMBER. Increasing this value can reduce the length of - time it takes the linker to perform its tasks, at the expense of - increasing the linker's memory requirements. Similarly reducing - this value can reduce the memory requirements at the expense of - speed. - -'--hash-style=STYLE' - Set the type of linker's hash table(s). STYLE can be either 'sysv' - for classic ELF '.hash' section, 'gnu' for new style GNU - '.gnu.hash' section or 'both' for both the classic ELF '.hash' and - new style GNU '.gnu.hash' hash tables. The default is 'sysv'. - -'--reduce-memory-overheads' - This option reduces memory requirements at ld runtime, at the - expense of linking speed. This was introduced to select the old - O(n^2) algorithm for link map file generation, rather than the new - O(n) algorithm which uses about 40% more memory for symbol storage. - - Another effect of the switch is to set the default hash table size - to 1021, which again saves memory at the cost of lengthening the - linker's run time. This is not done however if the '--hash-size' - switch has been used. - - The '--reduce-memory-overheads' switch may be also be used to - enable other tradeoffs in future versions of the linker. - -2.1.1 Options Specific to i386 PE Targets ------------------------------------------ - -The i386 PE linker supports the '-shared' option, which causes the -output to be a dynamically linked library (DLL) instead of a normal -executable. You should name the output '*.dll' when you use this -option. In addition, the linker fully supports the standard '*.def' -files, which may be specified on the linker command line like an object -file (in fact, it should precede archives it exports symbols from, to -ensure that they get linked in, just like a normal object file). - - In addition to the options common to all targets, the i386 PE linker -support additional command line options that are specific to the i386 PE -target. Options that take values may be separated from their values by -either a space or an equals sign. - -'--add-stdcall-alias' - If given, symbols with a stdcall suffix (@NN) will be exported - as-is and also with the suffix stripped. [This option is specific - to the i386 PE targeted port of the linker] - -'--base-file FILE' - Use FILE as the name of a file in which to save the base addresses - of all the relocations needed for generating DLLs with 'dlltool'. - [This is an i386 PE specific option] - -'--dll' - Create a DLL instead of a regular executable. You may also use - '-shared' or specify a 'LIBRARY' in a given '.def' file. [This - option is specific to the i386 PE targeted port of the linker] - -'--enable-stdcall-fixup' -'--disable-stdcall-fixup' - If the link finds a symbol that it cannot resolve, it will attempt - to do "fuzzy linking" by looking for another defined symbol that - differs only in the format of the symbol name (cdecl vs stdcall) - and will resolve that symbol by linking to the match. For example, - the undefined symbol '_foo' might be linked to the function - '_foo@12', or the undefined symbol '_bar@16' might be linked to the - function '_bar'. When the linker does this, it prints a warning, - since it normally should have failed to link, but sometimes import - libraries generated from third-party dlls may need this feature to - be usable. If you specify '--enable-stdcall-fixup', this feature - is fully enabled and warnings are not printed. If you specify - '--disable-stdcall-fixup', this feature is disabled and such - mismatches are considered to be errors. [This option is specific - to the i386 PE targeted port of the linker] - -'--export-all-symbols' - If given, all global symbols in the objects used to build a DLL - will be exported by the DLL. Note that this is the default if there - otherwise wouldn't be any exported symbols. When symbols are - explicitly exported via DEF files or implicitly exported via - function attributes, the default is to not export anything else - unless this option is given. Note that the symbols 'DllMain@12', - 'DllEntryPoint@0', 'DllMainCRTStartup@12', and 'impure_ptr' will - not be automatically exported. Also, symbols imported from other - DLLs will not be re-exported, nor will symbols specifying the DLL's - internal layout such as those beginning with '_head_' or ending - with '_iname'. In addition, no symbols from 'libgcc', 'libstd++', - 'libmingw32', or 'crtX.o' will be exported. Symbols whose names - begin with '__rtti_' or '__builtin_' will not be exported, to help - with C++ DLLs. Finally, there is an extensive list of - cygwin-private symbols that are not exported (obviously, this - applies on when building DLLs for cygwin targets). These - cygwin-excludes are: '_cygwin_dll_entry@12', - '_cygwin_crt0_common@8', '_cygwin_noncygwin_dll_entry@12', - '_fmode', '_impure_ptr', 'cygwin_attach_dll', 'cygwin_premain0', - 'cygwin_premain1', 'cygwin_premain2', 'cygwin_premain3', and - 'environ'. [This option is specific to the i386 PE targeted port - of the linker] - -'--exclude-symbols SYMBOL,SYMBOL,...' - Specifies a list of symbols which should not be automatically - exported. The symbol names may be delimited by commas or colons. - [This option is specific to the i386 PE targeted port of the - linker] - -'--file-alignment' - Specify the file alignment. Sections in the file will always begin - at file offsets which are multiples of this number. This defaults - to 512. [This option is specific to the i386 PE targeted port of - the linker] - -'--heap RESERVE' -'--heap RESERVE,COMMIT' - Specify the amount of memory to reserve (and optionally commit) to - be used as heap for this program. The default is 1Mb reserved, 4K - committed. [This option is specific to the i386 PE targeted port - of the linker] - -'--image-base VALUE' - Use VALUE as the base address of your program or dll. This is the - lowest memory location that will be used when your program or dll - is loaded. To reduce the need to relocate and improve performance - of your dlls, each should have a unique base address and not - overlap any other dlls. The default is 0x400000 for executables, - and 0x10000000 for dlls. [This option is specific to the i386 PE - targeted port of the linker] - -'--kill-at' - If given, the stdcall suffixes (@NN) will be stripped from symbols - before they are exported. [This option is specific to the i386 PE - targeted port of the linker] - -'--large-address-aware' - If given, the appropriate bit in the "Characteristics" field of the - COFF header is set to indicate that this executable supports - virtual addresses greater than 2 gigabytes. This should be used in - conjunction with the /3GB or /USERVA=VALUE megabytes switch in the - "[operating systems]" section of the BOOT.INI. Otherwise, this bit - has no effect. [This option is specific to PE targeted ports of - the linker] - -'--major-image-version VALUE' - Sets the major number of the "image version". Defaults to 1. - [This option is specific to the i386 PE targeted port of the - linker] - -'--major-os-version VALUE' - Sets the major number of the "os version". Defaults to 4. [This - option is specific to the i386 PE targeted port of the linker] - -'--major-subsystem-version VALUE' - Sets the major number of the "subsystem version". Defaults to 4. - [This option is specific to the i386 PE targeted port of the - linker] - -'--minor-image-version VALUE' - Sets the minor number of the "image version". Defaults to 0. - [This option is specific to the i386 PE targeted port of the - linker] - -'--minor-os-version VALUE' - Sets the minor number of the "os version". Defaults to 0. [This - option is specific to the i386 PE targeted port of the linker] - -'--minor-subsystem-version VALUE' - Sets the minor number of the "subsystem version". Defaults to 0. - [This option is specific to the i386 PE targeted port of the - linker] - -'--output-def FILE' - The linker will create the file FILE which will contain a DEF file - corresponding to the DLL the linker is generating. This DEF file - (which should be called '*.def') may be used to create an import - library with 'dlltool' or may be used as a reference to - automatically or implicitly exported symbols. [This option is - specific to the i386 PE targeted port of the linker] - -'--out-implib FILE' - The linker will create the file FILE which will contain an import - lib corresponding to the DLL the linker is generating. This import - lib (which should be called '*.dll.a' or '*.a' may be used to link - clients against the generated DLL; this behaviour makes it possible - to skip a separate 'dlltool' import library creation step. [This - option is specific to the i386 PE targeted port of the linker] - -'--enable-auto-image-base' - Automatically choose the image base for DLLs, unless one is - specified using the '--image-base' argument. By using a hash - generated from the dllname to create unique image bases for each - DLL, in-memory collisions and relocations which can delay program - execution are avoided. [This option is specific to the i386 PE - targeted port of the linker] - -'--disable-auto-image-base' - Do not automatically generate a unique image base. If there is no - user-specified image base ('--image-base') then use the platform - default. [This option is specific to the i386 PE targeted port of - the linker] - -'--dll-search-prefix STRING' - When linking dynamically to a dll without an import library, search - for '<string><basename>.dll' in preference to 'lib<basename>.dll'. - This behaviour allows easy distinction between DLLs built for the - various "subplatforms": native, cygwin, uwin, pw, etc. For - instance, cygwin DLLs typically use '--dll-search-prefix=cyg'. - [This option is specific to the i386 PE targeted port of the - linker] - -'--enable-auto-import' - Do sophisticated linking of '_symbol' to '__imp__symbol' for DATA - imports from DLLs, and create the necessary thunking symbols when - building the import libraries with those DATA exports. Note: Use - of the 'auto-import' extension will cause the text section of the - image file to be made writable. This does not conform to the - PE-COFF format specification published by Microsoft. - - Using 'auto-import' generally will 'just work' - but sometimes you - may see this message: - - "variable '<var>' can't be auto-imported. Please read the - documentation for ld's '--enable-auto-import' for details." - - This message occurs when some (sub)expression accesses an address - ultimately given by the sum of two constants (Win32 import tables - only allow one). Instances where this may occur include accesses - to member fields of struct variables imported from a DLL, as well - as using a constant index into an array variable imported from a - DLL. Any multiword variable (arrays, structs, long long, etc) may - trigger this error condition. However, regardless of the exact - data type of the offending exported variable, ld will always detect - it, issue the warning, and exit. - - There are several ways to address this difficulty, regardless of - the data type of the exported variable: - - One way is to use -enable-runtime-pseudo-reloc switch. This leaves - the task of adjusting references in your client code for runtime - environment, so this method works only when runtime environment - supports this feature. - - A second solution is to force one of the 'constants' to be a - variable - that is, unknown and un-optimizable at compile time. - For arrays, there are two possibilities: a) make the indexee (the - array's address) a variable, or b) make the 'constant' index a - variable. Thus: - - extern type extern_array[]; - extern_array[1] --> - { volatile type *t=extern_array; t[1] } - - or - - extern type extern_array[]; - extern_array[1] --> - { volatile int t=1; extern_array[t] } - - For structs (and most other multiword data types) the only option - is to make the struct itself (or the long long, or the ...) - variable: - - extern struct s extern_struct; - extern_struct.field --> - { volatile struct s *t=&extern_struct; t->field } - - or - - extern long long extern_ll; - extern_ll --> - { volatile long long * local_ll=&extern_ll; *local_ll } - - A third method of dealing with this difficulty is to abandon - 'auto-import' for the offending symbol and mark it with - '__declspec(dllimport)'. However, in practise that requires using - compile-time #defines to indicate whether you are building a DLL, - building client code that will link to the DLL, or merely - building/linking to a static library. In making the choice between - the various methods of resolving the 'direct address with constant - offset' problem, you should consider typical real-world usage: - - Original: - --foo.h - extern int arr[]; - --foo.c - #include "foo.h" - void main(int argc, char **argv){ - printf("%d\n",arr[1]); - } - - Solution 1: - --foo.h - extern int arr[]; - --foo.c - #include "foo.h" - void main(int argc, char **argv){ - /* This workaround is for win32 and cygwin; do not "optimize" */ - volatile int *parr = arr; - printf("%d\n",parr[1]); - } - - Solution 2: - --foo.h - /* Note: auto-export is assumed (no __declspec(dllexport)) */ - #if (defined(_WIN32) || defined(__CYGWIN__)) && \ - !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC)) - #define FOO_IMPORT __declspec(dllimport) - #else - #define FOO_IMPORT - #endif - extern FOO_IMPORT int arr[]; - --foo.c - #include "foo.h" - void main(int argc, char **argv){ - printf("%d\n",arr[1]); - } - - A fourth way to avoid this problem is to re-code your library to - use a functional interface rather than a data interface for the - offending variables (e.g. set_foo() and get_foo() accessor - functions). [This option is specific to the i386 PE targeted port - of the linker] - -'--disable-auto-import' - Do not attempt to do sophisticated linking of '_symbol' to - '__imp__symbol' for DATA imports from DLLs. [This option is - specific to the i386 PE targeted port of the linker] - -'--enable-runtime-pseudo-reloc' - If your code contains expressions described in -enable-auto-import - section, that is, DATA imports from DLL with non-zero offset, this - switch will create a vector of 'runtime pseudo relocations' which - can be used by runtime environment to adjust references to such - data in your client code. [This option is specific to the i386 PE - targeted port of the linker] - -'--disable-runtime-pseudo-reloc' - Do not create pseudo relocations for non-zero offset DATA imports - from DLLs. This is the default. [This option is specific to the - i386 PE targeted port of the linker] - -'--enable-extra-pe-debug' - Show additional debug info related to auto-import symbol thunking. - [This option is specific to the i386 PE targeted port of the - linker] - -'--section-alignment' - Sets the section alignment. Sections in memory will always begin - at addresses which are a multiple of this number. Defaults to - 0x1000. [This option is specific to the i386 PE targeted port of - the linker] - -'--stack RESERVE' -'--stack RESERVE,COMMIT' - Specify the amount of memory to reserve (and optionally commit) to - be used as stack for this program. The default is 2Mb reserved, 4K - committed. [This option is specific to the i386 PE targeted port - of the linker] - -'--subsystem WHICH' -'--subsystem WHICH:MAJOR' -'--subsystem WHICH:MAJOR.MINOR' - Specifies the subsystem under which your program will execute. The - legal values for WHICH are 'native', 'windows', 'console', 'posix', - and 'xbox'. You may optionally set the subsystem version also. - Numeric values are also accepted for WHICH. [This option is - specific to the i386 PE targeted port of the linker] - -2.1.2 Options specific to Motorola 68HC11 and 68HC12 targets ------------------------------------------------------------- - -The 68HC11 and 68HC12 linkers support specific options to control the -memory bank switching mapping and trampoline code generation. - -'--no-trampoline' - This option disables the generation of trampoline. By default a - trampoline is generated for each far function which is called using - a 'jsr' instruction (this happens when a pointer to a far function - is taken). - -'--bank-window NAME' - This option indicates to the linker the name of the memory region - in the 'MEMORY' specification that describes the memory bank - window. The definition of such region is then used by the linker - to compute paging and addresses within the memory window. - -2.2 Environment Variables -========================= - -You can change the behaviour of 'ld' with the environment variables -'GNUTARGET', 'LDEMULATION' and 'COLLECT_NO_DEMANGLE'. - - 'GNUTARGET' determines the input-file object format if you don't use -'-b' (or its synonym '--format'). Its value should be one of the BFD -names for an input format (*note BFD::). If there is no 'GNUTARGET' in -the environment, 'ld' uses the natural format of the target. If -'GNUTARGET' is set to 'default' then BFD attempts to discover the input -format by examining binary input files; this method often succeeds, but -there are potential ambiguities, since there is no method of ensuring -that the magic number used to specify object-file formats is unique. -However, the configuration procedure for BFD on each system places the -conventional format for that system first in the search-list, so -ambiguities are resolved in favor of convention. - - 'LDEMULATION' determines the default emulation if you don't use the -'-m' option. The emulation can affect various aspects of linker -behaviour, particularly the default linker script. You can list the -available emulations with the '--verbose' or '-V' options. If the '-m' -option is not used, and the 'LDEMULATION' environment variable is not -defined, the default emulation depends upon how the linker was -configured. - - Normally, the linker will default to demangling symbols. However, if -'COLLECT_NO_DEMANGLE' is set in the environment, then it will default to -not demangling symbols. This environment variable is used in a similar -fashion by the 'gcc' linker wrapper program. The default may be -overridden by the '--demangle' and '--no-demangle' options. - -3 Linker Scripts -**************** - -Every link is controlled by a "linker script". This script is written -in the linker command language. - - The main purpose of the linker script is to describe how the sections -in the input files should be mapped into the output file, and to control -the memory layout of the output file. Most linker scripts do nothing -more than this. However, when necessary, the linker script can also -direct the linker to perform many other operations, using the commands -described below. - - The linker always uses a linker script. If you do not supply one -yourself, the linker will use a default script that is compiled into the -linker executable. You can use the '--verbose' command line option to -display the default linker script. Certain command line options, such -as '-r' or '-N', will affect the default linker script. - - You may supply your own linker script by using the '-T' command line -option. When you do this, your linker script will replace the default -linker script. - - You may also use linker scripts implicitly by naming them as input -files to the linker, as though they were files to be linked. *Note -Implicit Linker Scripts::. - -3.1 Basic Linker Script Concepts -================================ - -We need to define some basic concepts and vocabulary in order to -describe the linker script language. - - The linker combines input files into a single output file. The -output file and each input file are in a special data format known as an -"object file format". Each file is called an "object file". The output -file is often called an "executable", but for our purposes we will also -call it an object file. Each object file has, among other things, a -list of "sections". We sometimes refer to a section in an input file as -an "input section"; similarly, a section in the output file is an -"output section". - - Each section in an object file has a name and a size. Most sections -also have an associated block of data, known as the "section contents". -A section may be marked as "loadable", which mean that the contents -should be loaded into memory when the output file is run. A section -with no contents may be "allocatable", which means that an area in -memory should be set aside, but nothing in particular should be loaded -there (in some cases this memory must be zeroed out). A section which -is neither loadable nor allocatable typically contains some sort of -debugging information. - - Every loadable or allocatable output section has two addresses. The -first is the "VMA", or virtual memory address. This is the address the -section will have when the output file is run. The second is the "LMA", -or load memory address. This is the address at which the section will -be loaded. In most cases the two addresses will be the same. An -example of when they might be different is when a data section is loaded -into ROM, and then copied into RAM when the program starts up (this -technique is often used to initialize global variables in a ROM based -system). In this case the ROM address would be the LMA, and the RAM -address would be the VMA. - - You can see the sections in an object file by using the 'objdump' -program with the '-h' option. - - Every object file also has a list of "symbols", known as the "symbol -table". A symbol may be defined or undefined. Each symbol has a name, -and each defined symbol has an address, among other information. If you -compile a C or C++ program into an object file, you will get a defined -symbol for every defined function and global or static variable. Every -undefined function or global variable which is referenced in the input -file will become an undefined symbol. - - You can see the symbols in an object file by using the 'nm' program, -or by using the 'objdump' program with the '-t' option. - -3.2 Linker Script Format -======================== - -Linker scripts are text files. - - You write a linker script as a series of commands. Each command is -either a keyword, possibly followed by arguments, or an assignment to a -symbol. You may separate commands using semicolons. Whitespace is -generally ignored. - - Strings such as file or format names can normally be entered -directly. If the file name contains a character such as a comma which -would otherwise serve to separate file names, you may put the file name -in double quotes. There is no way to use a double quote character in a -file name. - - You may include comments in linker scripts just as in C, delimited by -'/*' and '*/'. As in C, comments are syntactically equivalent to -whitespace. - -3.3 Simple Linker Script Example -================================ - -Many linker scripts are fairly simple. - - The simplest possible linker script has just one command: 'SECTIONS'. -You use the 'SECTIONS' command to describe the memory layout of the -output file. - - The 'SECTIONS' command is a powerful command. Here we will describe -a simple use of it. Let's assume your program consists only of code, -initialized data, and uninitialized data. These will be in the '.text', -'.data', and '.bss' sections, respectively. Let's assume further that -these are the only sections which appear in your input files. - - For this example, let's say that the code should be loaded at address -0x10000, and that the data should start at address 0x8000000. Here is a -linker script which will do that: - SECTIONS - { - . = 0x10000; - .text : { *(.text) } - . = 0x8000000; - .data : { *(.data) } - .bss : { *(.bss) } - } - - You write the 'SECTIONS' command as the keyword 'SECTIONS', followed -by a series of symbol assignments and output section descriptions -enclosed in curly braces. - - The first line inside the 'SECTIONS' command of the above example -sets the value of the special symbol '.', which is the location counter. -If you do not specify the address of an output section in some other way -(other ways are described later), the address is set from the current -value of the location counter. The location counter is then incremented -by the size of the output section. At the start of the 'SECTIONS' -command, the location counter has the value '0'. - - The second line defines an output section, '.text'. The colon is -required syntax which may be ignored for now. Within the curly braces -after the output section name, you list the names of the input sections -which should be placed into this output section. The '*' is a wildcard -which matches any file name. The expression '*(.text)' means all -'.text' input sections in all input files. - - Since the location counter is '0x10000' when the output section -'.text' is defined, the linker will set the address of the '.text' -section in the output file to be '0x10000'. - - The remaining lines define the '.data' and '.bss' sections in the -output file. The linker will place the '.data' output section at -address '0x8000000'. After the linker places the '.data' output -section, the value of the location counter will be '0x8000000' plus the -size of the '.data' output section. The effect is that the linker will -place the '.bss' output section immediately after the '.data' output -section in memory. - - The linker will ensure that each output section has the required -alignment, by increasing the location counter if necessary. In this -example, the specified addresses for the '.text' and '.data' sections -will probably satisfy any alignment constraints, but the linker may have -to create a small gap between the '.data' and '.bss' sections. - - That's it! That's a simple and complete linker script. - -3.4 Simple Linker Script Commands -================================= - -In this section we describe the simple linker script commands. - -3.4.1 Setting the Entry Point ------------------------------ - -The first instruction to execute in a program is called the "entry -point". You can use the 'ENTRY' linker script command to set the entry -point. The argument is a symbol name: - ENTRY(SYMBOL) - - There are several ways to set the entry point. The linker will set -the entry point by trying each of the following methods in order, and -stopping when one of them succeeds: - * the '-e' ENTRY command-line option; - * the 'ENTRY(SYMBOL)' command in a linker script; - * the value of the symbol 'start', if defined; - * the address of the first byte of the '.text' section, if present; - * The address '0'. - -3.4.2 Commands Dealing with Files ---------------------------------- - -Several linker script commands deal with files. - -'INCLUDE FILENAME' - Include the linker script FILENAME at this point. The file will be - searched for in the current directory, and in any directory - specified with the '-L' option. You can nest calls to 'INCLUDE' up - to 10 levels deep. - -'INPUT(FILE, FILE, ...)' -'INPUT(FILE FILE ...)' - The 'INPUT' command directs the linker to include the named files - in the link, as though they were named on the command line. - - For example, if you always want to include 'subr.o' any time you do - a link, but you can't be bothered to put it on every link command - line, then you can put 'INPUT (subr.o)' in your linker script. - - In fact, if you like, you can list all of your input files in the - linker script, and then invoke the linker with nothing but a '-T' - option. - - In case a "sysroot prefix" is configured, and the filename starts - with the '/' character, and the script being processed was located - inside the "sysroot prefix", the filename will be looked for in the - "sysroot prefix". Otherwise, the linker will try to open the file - in the current directory. If it is not found, the linker will - search through the archive library search path. See the - description of '-L' in *note Command Line Options: Options. - - If you use 'INPUT (-lFILE)', 'ld' will transform the name to - 'libFILE.a', as with the command line argument '-l'. - - When you use the 'INPUT' command in an implicit linker script, the - files will be included in the link at the point at which the linker - script file is included. This can affect archive searching. - -'GROUP(FILE, FILE, ...)' -'GROUP(FILE FILE ...)' - The 'GROUP' command is like 'INPUT', except that the named files - should all be archives, and they are searched repeatedly until no - new undefined references are created. See the description of '-(' - in *note Command Line Options: Options. - -'AS_NEEDED(FILE, FILE, ...)' -'AS_NEEDED(FILE FILE ...)' - This construct can appear only inside of the 'INPUT' or 'GROUP' - commands, among other filenames. The files listed will be handled - as if they appear directly in the 'INPUT' or 'GROUP' commands, with - the exception of ELF shared libraries, that will be added only when - they are actually needed. This construct essentially enables - '--as-needed' option for all the files listed inside of it and - restores previous '--as-needed' resp. '--no-as-needed' setting - afterwards. - -'OUTPUT(FILENAME)' - The 'OUTPUT' command names the output file. Using - 'OUTPUT(FILENAME)' in the linker script is exactly like using '-o - FILENAME' on the command line (*note Command Line Options: - Options.). If both are used, the command line option takes - precedence. - - You can use the 'OUTPUT' command to define a default name for the - output file other than the usual default of 'a.out'. - -'SEARCH_DIR(PATH)' - The 'SEARCH_DIR' command adds PATH to the list of paths where 'ld' - looks for archive libraries. Using 'SEARCH_DIR(PATH)' is exactly - like using '-L PATH' on the command line (*note Command Line - Options: Options.). If both are used, then the linker will search - both paths. Paths specified using the command line option are - searched first. - -'STARTUP(FILENAME)' - The 'STARTUP' command is just like the 'INPUT' command, except that - FILENAME will become the first input file to be linked, as though - it were specified first on the command line. This may be useful - when using a system in which the entry point is always the start of - the first file. - -3.4.3 Commands Dealing with Object File Formats ------------------------------------------------ - -A couple of linker script commands deal with object file formats. - -'OUTPUT_FORMAT(BFDNAME)' -'OUTPUT_FORMAT(DEFAULT, BIG, LITTLE)' - The 'OUTPUT_FORMAT' command names the BFD format to use for the - output file (*note BFD::). Using 'OUTPUT_FORMAT(BFDNAME)' is - exactly like using '--oformat BFDNAME' on the command line (*note - Command Line Options: Options.). If both are used, the command - line option takes precedence. - - You can use 'OUTPUT_FORMAT' with three arguments to use different - formats based on the '-EB' and '-EL' command line options. This - permits the linker script to set the output format based on the - desired endianness. - - If neither '-EB' nor '-EL' are used, then the output format will be - the first argument, DEFAULT. If '-EB' is used, the output format - will be the second argument, BIG. If '-EL' is used, the output - format will be the third argument, LITTLE. - - For example, the default linker script for the MIPS ELF target uses - this command: - OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips) - This says that the default format for the output file is - 'elf32-bigmips', but if the user uses the '-EL' command line - option, the output file will be created in the 'elf32-littlemips' - format. - -'TARGET(BFDNAME)' - The 'TARGET' command names the BFD format to use when reading input - files. It affects subsequent 'INPUT' and 'GROUP' commands. This - command is like using '-b BFDNAME' on the command line (*note - Command Line Options: Options.). If the 'TARGET' command is used - but 'OUTPUT_FORMAT' is not, then the last 'TARGET' command is also - used to set the format for the output file. *Note BFD::. - -3.4.4 Other Linker Script Commands ----------------------------------- - -There are a few other linker scripts commands. - -'ASSERT(EXP, MESSAGE)' - Ensure that EXP is non-zero. If it is zero, then exit the linker - with an error code, and print MESSAGE. - -'EXTERN(SYMBOL SYMBOL ...)' - Force SYMBOL to be entered in the output file as an undefined - symbol. Doing this may, for example, trigger linking of additional - modules from standard libraries. You may list several SYMBOLs for - each 'EXTERN', and you may use 'EXTERN' multiple times. This - command has the same effect as the '-u' command-line option. - -'FORCE_COMMON_ALLOCATION' - This command has the same effect as the '-d' command-line option: - to make 'ld' assign space to common symbols even if a relocatable - output file is specified ('-r'). - -'INHIBIT_COMMON_ALLOCATION' - This command has the same effect as the '--no-define-common' - command-line option: to make 'ld' omit the assignment of addresses - to common symbols even for a non-relocatable output file. - -'NOCROSSREFS(SECTION SECTION ...)' - This command may be used to tell 'ld' to issue an error about any - references among certain output sections. - - In certain types of programs, particularly on embedded systems when - using overlays, when one section is loaded into memory, another - section will not be. Any direct references between the two - sections would be errors. For example, it would be an error if - code in one section called a function defined in the other section. - - The 'NOCROSSREFS' command takes a list of output section names. If - 'ld' detects any cross references between the sections, it reports - an error and returns a non-zero exit status. Note that the - 'NOCROSSREFS' command uses output section names, not input section - names. - -'OUTPUT_ARCH(BFDARCH)' - Specify a particular output machine architecture. The argument is - one of the names used by the BFD library (*note BFD::). You can - see the architecture of an object file by using the 'objdump' - program with the '-f' option. - -3.5 Assigning Values to Symbols -=============================== - -You may assign a value to a symbol in a linker script. This will define -the symbol and place it into the symbol table with a global scope. - -3.5.1 Simple Assignments ------------------------- - -You may assign to a symbol using any of the C assignment operators: - -'SYMBOL = EXPRESSION ;' -'SYMBOL += EXPRESSION ;' -'SYMBOL -= EXPRESSION ;' -'SYMBOL *= EXPRESSION ;' -'SYMBOL /= EXPRESSION ;' -'SYMBOL <<= EXPRESSION ;' -'SYMBOL >>= EXPRESSION ;' -'SYMBOL &= EXPRESSION ;' -'SYMBOL |= EXPRESSION ;' - - The first case will define SYMBOL to the value of EXPRESSION. In the -other cases, SYMBOL must already be defined, and the value will be -adjusted accordingly. - - The special symbol name '.' indicates the location counter. You may -only use this within a 'SECTIONS' command. *Note Location Counter::. - - The semicolon after EXPRESSION is required. - - Expressions are defined below; see *note Expressions::. - - You may write symbol assignments as commands in their own right, or -as statements within a 'SECTIONS' command, or as part of an output -section description in a 'SECTIONS' command. - - The section of the symbol will be set from the section of the -expression; for more information, see *note Expression Section::. - - Here is an example showing the three different places that symbol -assignments may be used: - - floating_point = 0; - SECTIONS - { - .text : - { - *(.text) - _etext = .; - } - _bdata = (. + 3) & ~ 3; - .data : { *(.data) } - } -In this example, the symbol 'floating_point' will be defined as zero. -The symbol '_etext' will be defined as the address following the last -'.text' input section. The symbol '_bdata' will be defined as the -address following the '.text' output section aligned upward to a 4 byte -boundary. - -3.5.2 PROVIDE -------------- - -In some cases, it is desirable for a linker script to define a symbol -only if it is referenced and is not defined by any object included in -the link. For example, traditional linkers defined the symbol 'etext'. -However, ANSI C requires that the user be able to use 'etext' as a -function name without encountering an error. The 'PROVIDE' keyword may -be used to define a symbol, such as 'etext', only if it is referenced -but not defined. The syntax is 'PROVIDE(SYMBOL = EXPRESSION)'. - - Here is an example of using 'PROVIDE' to define 'etext': - SECTIONS - { - .text : - { - *(.text) - _etext = .; - PROVIDE(etext = .); - } - } - - In this example, if the program defines '_etext' (with a leading -underscore), the linker will give a multiple definition error. If, on -the other hand, the program defines 'etext' (with no leading -underscore), the linker will silently use the definition in the program. -If the program references 'etext' but does not define it, the linker -will use the definition in the linker script. - -3.5.3 PROVIDE_HIDDEN --------------------- - -Similar to 'PROVIDE'. For ELF targeted ports, the symbol will be hidden -and won't be exported. - -3.5.4 Source Code Reference ---------------------------- - -Accessing a linker script defined variable from source code is not -intuitive. In particular a linker script symbol is not equivalent to a -variable declaration in a high level language, it is instead a symbol -that does not have a value. - - Before going further, it is important to note that compilers often -transform names in the source code into different names when they are -stored in the symbol table. For example, Fortran compilers commonly -prepend or append an underscore, and C++ performs extensive 'name -mangling'. Therefore there might be a discrepancy between the name of a -variable as it is used in source code and the name of the same variable -as it is defined in a linker script. For example in C a linker script -variable might be referred to as: - - extern int foo; - - But in the linker script it might be defined as: - - _foo = 1000; - - In the remaining examples however it is assumed that no name -transformation has taken place. - - When a symbol is declared in a high level language such as C, two -things happen. The first is that the compiler reserves enough space in -the program's memory to hold the _value_ of the symbol. The second is -that the compiler creates an entry in the program's symbol table which -holds the symbol's _address_. ie the symbol table contains the address -of the block of memory holding the symbol's value. So for example the -following C declaration, at file scope: - - int foo = 1000; - - creates a entry called 'foo' in the symbol table. This entry holds -the address of an 'int' sized block of memory where the number 1000 is -initially stored. - - When a program references a symbol the compiler generates code that -first accesses the symbol table to find the address of the symbol's -memory block and then code to read the value from that memory block. -So: - - foo = 1; - - looks up the symbol 'foo' in the symbol table, gets the address -associated with this symbol and then writes the value 1 into that -address. Whereas: - - int * a = & foo; - - looks up the symbol 'foo' in the symbol table, gets it address and -then copies this address into the block of memory associated with the -variable 'a'. - - Linker scripts symbol declarations, by contrast, create an entry in -the symbol table but do not assign any memory to them. Thus they are an -address without a value. So for example the linker script definition: - - foo = 1000; - - creates an entry in the symbol table called 'foo' which holds the -address of memory location 1000, but nothing special is stored at -address 1000. This means that you cannot access the _value_ of a linker -script defined symbol - it has no value - all you can do is access the -_address_ of a linker script defined symbol. - - Hence when you are using a linker script defined symbol in source -code you should always take the address of the symbol, and never attempt -to use its value. For example suppose you want to copy the contents of -a section of memory called .ROM into a section called .FLASH and the -linker script contains these declarations: - - start_of_ROM = .ROM; - end_of_ROM = .ROM + sizeof (.ROM) - 1; - start_of_FLASH = .FLASH; - - Then the C source code to perform the copy would be: - - extern char start_of_ROM, end_of_ROM, start_of_FLASH; - - memcpy (& start_of_FLASH, & start_of_ROM, & end_of_ROM - & start_of_ROM); - - Note the use of the '&' operators. These are correct. - -3.6 SECTIONS Command -==================== - -The 'SECTIONS' command tells the linker how to map input sections into -output sections, and how to place the output sections in memory. - - The format of the 'SECTIONS' command is: - SECTIONS - { - SECTIONS-COMMAND - SECTIONS-COMMAND - ... - } - - Each SECTIONS-COMMAND may of be one of the following: - - * an 'ENTRY' command (*note Entry command: Entry Point.) - * a symbol assignment (*note Assignments::) - * an output section description - * an overlay description - - The 'ENTRY' command and symbol assignments are permitted inside the -'SECTIONS' command for convenience in using the location counter in -those commands. This can also make the linker script easier to -understand because you can use those commands at meaningful points in -the layout of the output file. - - Output section descriptions and overlay descriptions are described -below. - - If you do not use a 'SECTIONS' command in your linker script, the -linker will place each input section into an identically named output -section in the order that the sections are first encountered in the -input files. If all input sections are present in the first file, for -example, the order of sections in the output file will match the order -in the first input file. The first section will be at address zero. - -3.6.1 Output Section Description --------------------------------- - -The full description of an output section looks like this: - SECTION [ADDRESS] [(TYPE)] : - [AT(LMA)] [ALIGN(SECTION_ALIGN)] [SUBALIGN(SUBSECTION_ALIGN)] - { - OUTPUT-SECTION-COMMAND - OUTPUT-SECTION-COMMAND - ... - } [>REGION] [AT>LMA_REGION] [:PHDR :PHDR ...] [=FILLEXP] - - Most output sections do not use most of the optional section -attributes. - - The whitespace around SECTION is required, so that the section name -is unambiguous. The colon and the curly braces are also required. The -line breaks and other white space are optional. - - Each OUTPUT-SECTION-COMMAND may be one of the following: - - * a symbol assignment (*note Assignments::) - * an input section description (*note Input Section::) - * data values to include directly (*note Output Section Data::) - * a special output section keyword (*note Output Section Keywords::) - -3.6.2 Output Section Name -------------------------- - -The name of the output section is SECTION. SECTION must meet the -constraints of your output format. In formats which only support a -limited number of sections, such as 'a.out', the name must be one of the -names supported by the format ('a.out', for example, allows only -'.text', '.data' or '.bss'). If the output format supports any number -of sections, but with numbers and not names (as is the case for Oasys), -the name should be supplied as a quoted numeric string. A section name -may consist of any sequence of characters, but a name which contains any -unusual characters such as commas must be quoted. - - The output section name '/DISCARD/' is special; *note Output Section -Discarding::. - -3.6.3 Output Section Address ----------------------------- - -The ADDRESS is an expression for the VMA (the virtual memory address) of -the output section. If you do not provide ADDRESS, the linker will set -it based on REGION if present, or otherwise based on the current value -of the location counter. - - If you provide ADDRESS, the address of the output section will be set -to precisely that. If you provide neither ADDRESS nor REGION, then the -address of the output section will be set to the current value of the -location counter aligned to the alignment requirements of the output -section. The alignment requirement of the output section is the -strictest alignment of any input section contained within the output -section. - - For example, - .text . : { *(.text) } -and - .text : { *(.text) } -are subtly different. The first will set the address of the '.text' -output section to the current value of the location counter. The second -will set it to the current value of the location counter aligned to the -strictest alignment of a '.text' input section. - - The ADDRESS may be an arbitrary expression; *note Expressions::. For -example, if you want to align the section on a 0x10 byte boundary, so -that the lowest four bits of the section address are zero, you could do -something like this: - .text ALIGN(0x10) : { *(.text) } -This works because 'ALIGN' returns the current location counter aligned -upward to the specified value. - - Specifying ADDRESS for a section will change the value of the -location counter. - -3.6.4 Input Section Description -------------------------------- - -The most common output section command is an input section description. - - The input section description is the most basic linker script -operation. You use output sections to tell the linker how to lay out -your program in memory. You use input section descriptions to tell the -linker how to map the input files into your memory layout. - -3.6.4.1 Input Section Basics -............................ - -An input section description consists of a file name optionally followed -by a list of section names in parentheses. - - The file name and the section name may be wildcard patterns, which we -describe further below (*note Input Section Wildcards::). - - The most common input section description is to include all input -sections with a particular name in the output section. For example, to -include all input '.text' sections, you would write: - *(.text) -Here the '*' is a wildcard which matches any file name. To exclude a -list of files from matching the file name wildcard, EXCLUDE_FILE may be -used to match all files except the ones specified in the EXCLUDE_FILE -list. For example: - (*(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors)) - will cause all .ctors sections from all files except 'crtend.o' and -'otherfile.o' to be included. - - There are two ways to include more than one section: - *(.text .rdata) - *(.text) *(.rdata) -The difference between these is the order in which the '.text' and -'.rdata' input sections will appear in the output section. In the first -example, they will be intermingled, appearing in the same order as they -are found in the linker input. In the second example, all '.text' input -sections will appear first, followed by all '.rdata' input sections. - - You can specify a file name to include sections from a particular -file. You would do this if one or more of your files contain special -data that needs to be at a particular location in memory. For example: - data.o(.data) - - If you use a file name without a list of sections, then all sections -in the input file will be included in the output section. This is not -commonly done, but it may by useful on occasion. For example: - data.o - - When you use a file name which does not contain any wild card -characters, the linker will first see if you also specified the file -name on the linker command line or in an 'INPUT' command. If you did -not, the linker will attempt to open the file as an input file, as -though it appeared on the command line. Note that this differs from an -'INPUT' command, because the linker will not search for the file in the -archive search path. - -3.6.4.2 Input Section Wildcard Patterns -....................................... - -In an input section description, either the file name or the section -name or both may be wildcard patterns. - - The file name of '*' seen in many examples is a simple wildcard -pattern for the file name. - - The wildcard patterns are like those used by the Unix shell. - -'*' - matches any number of characters -'?' - matches any single character -'[CHARS]' - matches a single instance of any of the CHARS; the '-' character - may be used to specify a range of characters, as in '[a-z]' to - match any lower case letter -'\' - quotes the following character - - When a file name is matched with a wildcard, the wildcard characters -will not match a '/' character (used to separate directory names on -Unix). A pattern consisting of a single '*' character is an exception; -it will always match any file name, whether it contains a '/' or not. -In a section name, the wildcard characters will match a '/' character. - - File name wildcard patterns only match files which are explicitly -specified on the command line or in an 'INPUT' command. The linker does -not search directories to expand wildcards. - - If a file name matches more than one wildcard pattern, or if a file -name appears explicitly and is also matched by a wildcard pattern, the -linker will use the first match in the linker script. For example, this -sequence of input section descriptions is probably in error, because the -'data.o' rule will not be used: - .data : { *(.data) } - .data1 : { data.o(.data) } - - Normally, the linker will place files and sections matched by -wildcards in the order in which they are seen during the link. You can -change this by using the 'SORT_BY_NAME' keyword, which appears before a -wildcard pattern in parentheses (e.g., 'SORT_BY_NAME(.text*)'). When -the 'SORT_BY_NAME' keyword is used, the linker will sort the files or -sections into ascending order by name before placing them in the output -file. - - 'SORT_BY_ALIGNMENT' is very similar to 'SORT_BY_NAME'. The -difference is 'SORT_BY_ALIGNMENT' will sort sections into ascending -order by alignment before placing them in the output file. - - 'SORT' is an alias for 'SORT_BY_NAME'. - - When there are nested section sorting commands in linker script, -there can be at most 1 level of nesting for section sorting commands. - - 1. 'SORT_BY_NAME' ('SORT_BY_ALIGNMENT' (wildcard section pattern)). - It will sort the input sections by name first, then by alignment if - 2 sections have the same name. - 2. 'SORT_BY_ALIGNMENT' ('SORT_BY_NAME' (wildcard section pattern)). - It will sort the input sections by alignment first, then by name if - 2 sections have the same alignment. - 3. 'SORT_BY_NAME' ('SORT_BY_NAME' (wildcard section pattern)) is - treated the same as 'SORT_BY_NAME' (wildcard section pattern). - 4. 'SORT_BY_ALIGNMENT' ('SORT_BY_ALIGNMENT' (wildcard section - pattern)) is treated the same as 'SORT_BY_ALIGNMENT' (wildcard - section pattern). - 5. All other nested section sorting commands are invalid. - - When both command line section sorting option and linker script -section sorting command are used, section sorting command always takes -precedence over the command line option. - - If the section sorting command in linker script isn't nested, the -command line option will make the section sorting command to be treated -as nested sorting command. - - 1. 'SORT_BY_NAME' (wildcard section pattern ) with '--sort-sections - alignment' is equivalent to 'SORT_BY_NAME' ('SORT_BY_ALIGNMENT' - (wildcard section pattern)). - 2. 'SORT_BY_ALIGNMENT' (wildcard section pattern) with '--sort-section - name' is equivalent to 'SORT_BY_ALIGNMENT' ('SORT_BY_NAME' - (wildcard section pattern)). - - If the section sorting command in linker script is nested, the -command line option will be ignored. - - If you ever get confused about where input sections are going, use -the '-M' linker option to generate a map file. The map file shows -precisely how input sections are mapped to output sections. - - This example shows how wildcard patterns might be used to partition -files. This linker script directs the linker to place all '.text' -sections in '.text' and all '.bss' sections in '.bss'. The linker will -place the '.data' section from all files beginning with an upper case -character in '.DATA'; for all other files, the linker will place the -'.data' section in '.data'. - SECTIONS { - .text : { *(.text) } - .DATA : { [A-Z]*(.data) } - .data : { *(.data) } - .bss : { *(.bss) } - } - -3.6.4.3 Input Section for Common Symbols -........................................ - -A special notation is needed for common symbols, because in many object -file formats common symbols do not have a particular input section. The -linker treats common symbols as though they are in an input section -named 'COMMON'. - - You may use file names with the 'COMMON' section just as with any -other input sections. You can use this to place common symbols from a -particular input file in one section while common symbols from other -input files are placed in another section. - - In most cases, common symbols in input files will be placed in the -'.bss' section in the output file. For example: - .bss { *(.bss) *(COMMON) } - - Some object file formats have more than one type of common symbol. -For example, the MIPS ELF object file format distinguishes standard -common symbols and small common symbols. In this case, the linker will -use a different special section name for other types of common symbols. -In the case of MIPS ELF, the linker uses 'COMMON' for standard common -symbols and '.scommon' for small common symbols. This permits you to -map the different types of common symbols into memory at different -locations. - - You will sometimes see '[COMMON]' in old linker scripts. This -notation is now considered obsolete. It is equivalent to '*(COMMON)'. - -3.6.4.4 Input Section and Garbage Collection -............................................ - -When link-time garbage collection is in use ('--gc-sections'), it is -often useful to mark sections that should not be eliminated. This is -accomplished by surrounding an input section's wildcard entry with -'KEEP()', as in 'KEEP(*(.init))' or 'KEEP(SORT_BY_NAME(*)(.ctors))'. - -3.6.4.5 Input Section Example -............................. - -The following example is a complete linker script. It tells the linker -to read all of the sections from file 'all.o' and place them at the -start of output section 'outputa' which starts at location '0x10000'. -All of section '.input1' from file 'foo.o' follows immediately, in the -same output section. All of section '.input2' from 'foo.o' goes into -output section 'outputb', followed by section '.input1' from 'foo1.o'. -All of the remaining '.input1' and '.input2' sections from any files are -written to output section 'outputc'. - - SECTIONS { - outputa 0x10000 : - { - all.o - foo.o (.input1) - } - outputb : - { - foo.o (.input2) - foo1.o (.input1) - } - outputc : - { - *(.input1) - *(.input2) - } - } - -3.6.5 Output Section Data -------------------------- - -You can include explicit bytes of data in an output section by using -'BYTE', 'SHORT', 'LONG', 'QUAD', or 'SQUAD' as an output section -command. Each keyword is followed by an expression in parentheses -providing the value to store (*note Expressions::). The value of the -expression is stored at the current value of the location counter. - - The 'BYTE', 'SHORT', 'LONG', and 'QUAD' commands store one, two, -four, and eight bytes (respectively). After storing the bytes, the -location counter is incremented by the number of bytes stored. - - For example, this will store the byte 1 followed by the four byte -value of the symbol 'addr': - BYTE(1) - LONG(addr) - - When using a 64 bit host or target, 'QUAD' and 'SQUAD' are the same; -they both store an 8 byte, or 64 bit, value. When both host and target -are 32 bits, an expression is computed as 32 bits. In this case 'QUAD' -stores a 32 bit value zero extended to 64 bits, and 'SQUAD' stores a 32 -bit value sign extended to 64 bits. - - If the object file format of the output file has an explicit -endianness, which is the normal case, the value will be stored in that -endianness. When the object file format does not have an explicit -endianness, as is true of, for example, S-records, the value will be -stored in the endianness of the first input object file. - - Note--these commands only work inside a section description and not -between them, so the following will produce an error from the linker: - SECTIONS { .text : { *(.text) } LONG(1) .data : { *(.data) } } - whereas this will work: - SECTIONS { .text : { *(.text) ; LONG(1) } .data : { *(.data) } } - - You may use the 'FILL' command to set the fill pattern for the -current section. It is followed by an expression in parentheses. Any -otherwise unspecified regions of memory within the section (for example, -gaps left due to the required alignment of input sections) are filled -with the value of the expression, repeated as necessary. A 'FILL' -statement covers memory locations after the point at which it occurs in -the section definition; by including more than one 'FILL' statement, you -can have different fill patterns in different parts of an output -section. - - This example shows how to fill unspecified regions of memory with the -value '0x90': - FILL(0x90909090) - - The 'FILL' command is similar to the '=FILLEXP' output section -attribute, but it only affects the part of the section following the -'FILL' command, rather than the entire section. If both are used, the -'FILL' command takes precedence. *Note Output Section Fill::, for -details on the fill expression. - -3.6.6 Output Section Keywords ------------------------------ - -There are a couple of keywords which can appear as output section -commands. - -'CREATE_OBJECT_SYMBOLS' - The command tells the linker to create a symbol for each input - file. The name of each symbol will be the name of the - corresponding input file. The section of each symbol will be the - output section in which the 'CREATE_OBJECT_SYMBOLS' command - appears. - - This is conventional for the a.out object file format. It is not - normally used for any other object file format. - -'CONSTRUCTORS' - When linking using the a.out object file format, the linker uses an - unusual set construct to support C++ global constructors and - destructors. When linking object file formats which do not support - arbitrary sections, such as ECOFF and XCOFF, the linker will - automatically recognize C++ global constructors and destructors by - name. For these object file formats, the 'CONSTRUCTORS' command - tells the linker to place constructor information in the output - section where the 'CONSTRUCTORS' command appears. The - 'CONSTRUCTORS' command is ignored for other object file formats. - - The symbol '__CTOR_LIST__' marks the start of the global - constructors, and the symbol '__CTOR_END__' marks the end. - Similarly, '__DTOR_LIST__' and '__DTOR_END__' mark the start and - end of the global destructors. The first word in the list is the - number of entries, followed by the address of each constructor or - destructor, followed by a zero word. The compiler must arrange to - actually run the code. For these object file formats GNU C++ - normally calls constructors from a subroutine '__main'; a call to - '__main' is automatically inserted into the startup code for - 'main'. GNU C++ normally runs destructors either by using - 'atexit', or directly from the function 'exit'. - - For object file formats such as 'COFF' or 'ELF' which support - arbitrary section names, GNU C++ will normally arrange to put the - addresses of global constructors and destructors into the '.ctors' - and '.dtors' sections. Placing the following sequence into your - linker script will build the sort of table which the GNU C++ - runtime code expects to see. - - __CTOR_LIST__ = .; - LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2) - *(.ctors) - LONG(0) - __CTOR_END__ = .; - __DTOR_LIST__ = .; - LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2) - *(.dtors) - LONG(0) - __DTOR_END__ = .; - - If you are using the GNU C++ support for initialization priority, - which provides some control over the order in which global - constructors are run, you must sort the constructors at link time - to ensure that they are executed in the correct order. When using - the 'CONSTRUCTORS' command, use 'SORT_BY_NAME(CONSTRUCTORS)' - instead. When using the '.ctors' and '.dtors' sections, use - '*(SORT_BY_NAME(.ctors))' and '*(SORT_BY_NAME(.dtors))' instead of - just '*(.ctors)' and '*(.dtors)'. - - Normally the compiler and linker will handle these issues - automatically, and you will not need to concern yourself with them. - However, you may need to consider this if you are using C++ and - writing your own linker scripts. - -3.6.7 Output Section Discarding -------------------------------- - -The linker will not create output sections with no contents. This is -for convenience when referring to input sections that may or may not be -present in any of the input files. For example: - .foo : { *(.foo) } -will only create a '.foo' section in the output file if there is a -'.foo' section in at least one input file, and if the input sections are -not all empty. Other link script directives that allocate space in an -output section will also create the output section. - - The linker will ignore address assignments (*note Output Section -Address::) on discarded output sections, except when the linker script -defines symbols in the output section. In that case the linker will -obey the address assignments, possibly advancing dot even though the -section is discarded. - - The special output section name '/DISCARD/' may be used to discard -input sections. Any input sections which are assigned to an output -section named '/DISCARD/' are not included in the output file. - -3.6.8 Output Section Attributes -------------------------------- - -We showed above that the full description of an output section looked -like this: - SECTION [ADDRESS] [(TYPE)] : - [AT(LMA)] [ALIGN(SECTION_ALIGN)] [SUBALIGN(SUBSECTION_ALIGN)] - { - OUTPUT-SECTION-COMMAND - OUTPUT-SECTION-COMMAND - ... - } [>REGION] [AT>LMA_REGION] [:PHDR :PHDR ...] [=FILLEXP] - We've already described SECTION, ADDRESS, and OUTPUT-SECTION-COMMAND. -In this section we will describe the remaining section attributes. - -3.6.8.1 Output Section Type -........................... - -Each output section may have a type. The type is a keyword in -parentheses. The following types are defined: - -'NOLOAD' - The section should be marked as not loadable, so that it will not - be loaded into memory when the program is run. -'DSECT' -'COPY' -'INFO' -'OVERLAY' - These type names are supported for backward compatibility, and are - rarely used. They all have the same effect: the section should be - marked as not allocatable, so that no memory is allocated for the - section when the program is run. - - The linker normally sets the attributes of an output section based on -the input sections which map into it. You can override this by using -the section type. For example, in the script sample below, the 'ROM' -section is addressed at memory location '0' and does not need to be -loaded when the program is run. The contents of the 'ROM' section will -appear in the linker output file as usual. - SECTIONS { - ROM 0 (NOLOAD) : { ... } - ... - } - -3.6.8.2 Output Section LMA -.......................... - -Every section has a virtual address (VMA) and a load address (LMA); see -*note Basic Script Concepts::. The address expression which may appear -in an output section description sets the VMA (*note Output Section -Address::). - - The expression LMA that follows the 'AT' keyword specifies the load -address of the section. - - Alternatively, with 'AT>LMA_REGION' expression, you may specify a -memory region for the section's load address. *Note MEMORY::. Note -that if the section has not had a VMA assigned to it then the linker -will use the LMA_REGION as the VMA region as well. - - If neither 'AT' nor 'AT>' is specified for an allocatable section, -the linker will set the LMA such that the difference between VMA and LMA -for the section is the same as the preceding output section in the same -region. If there is no preceding output section or the section is not -allocatable, the linker will set the LMA equal to the VMA. *Note Output -Section Region::. - - This feature is designed to make it easy to build a ROM image. For -example, the following linker script creates three output sections: one -called '.text', which starts at '0x1000', one called '.mdata', which is -loaded at the end of the '.text' section even though its VMA is -'0x2000', and one called '.bss' to hold uninitialized data at address -'0x3000'. The symbol '_data' is defined with the value '0x2000', which -shows that the location counter holds the VMA value, not the LMA value. - - SECTIONS - { - .text 0x1000 : { *(.text) _etext = . ; } - .mdata 0x2000 : - AT ( ADDR (.text) + SIZEOF (.text) ) - { _data = . ; *(.data); _edata = . ; } - .bss 0x3000 : - { _bstart = . ; *(.bss) *(COMMON) ; _bend = . ;} - } - - The run-time initialization code for use with a program generated -with this linker script would include something like the following, to -copy the initialized data from the ROM image to its runtime address. -Notice how this code takes advantage of the symbols defined by the -linker script. - - extern char _etext, _data, _edata, _bstart, _bend; - char *src = &_etext; - char *dst = &_data; - - /* ROM has data at end of text; copy it. */ - while (dst < &_edata) { - *dst++ = *src++; - } - - /* Zero bss */ - for (dst = &_bstart; dst< &_bend; dst++) - *dst = 0; - -3.6.8.3 Forced Output Alignment -............................... - -You can increase an output section's alignment by using ALIGN. - -3.6.8.4 Forced Input Alignment -.............................. - -You can force input section alignment within an output section by using -SUBALIGN. The value specified overrides any alignment given by input -sections, whether larger or smaller. - -3.6.8.5 Output Section Region -............................. - -You can assign a section to a previously defined region of memory by -using '>REGION'. *Note MEMORY::. - - Here is a simple example: - MEMORY { rom : ORIGIN = 0x1000, LENGTH = 0x1000 } - SECTIONS { ROM : { *(.text) } >rom } - -3.6.8.6 Output Section Phdr -........................... - -You can assign a section to a previously defined program segment by -using ':PHDR'. *Note PHDRS::. If a section is assigned to one or more -segments, then all subsequent allocated sections will be assigned to -those segments as well, unless they use an explicitly ':PHDR' modifier. -You can use ':NONE' to tell the linker to not put the section in any -segment at all. - - Here is a simple example: - PHDRS { text PT_LOAD ; } - SECTIONS { .text : { *(.text) } :text } - -3.6.8.7 Output Section Fill -........................... - -You can set the fill pattern for an entire section by using '=FILLEXP'. -FILLEXP is an expression (*note Expressions::). Any otherwise -unspecified regions of memory within the output section (for example, -gaps left due to the required alignment of input sections) will be -filled with the value, repeated as necessary. If the fill expression is -a simple hex number, ie. a string of hex digit starting with '0x' and -without a trailing 'k' or 'M', then an arbitrarily long sequence of hex -digits can be used to specify the fill pattern; Leading zeros become -part of the pattern too. For all other cases, including extra -parentheses or a unary '+', the fill pattern is the four least -significant bytes of the value of the expression. In all cases, the -number is big-endian. - - You can also change the fill value with a 'FILL' command in the -output section commands; (*note Output Section Data::). - - Here is a simple example: - SECTIONS { .text : { *(.text) } =0x90909090 } - -3.6.9 Overlay Description -------------------------- - -An overlay description provides an easy way to describe sections which -are to be loaded as part of a single memory image but are to be run at -the same memory address. At run time, some sort of overlay manager will -copy the overlaid sections in and out of the runtime memory address as -required, perhaps by simply manipulating addressing bits. This approach -can be useful, for example, when a certain region of memory is faster -than another. - - Overlays are described using the 'OVERLAY' command. The 'OVERLAY' -command is used within a 'SECTIONS' command, like an output section -description. The full syntax of the 'OVERLAY' command is as follows: - OVERLAY [START] : [NOCROSSREFS] [AT ( LDADDR )] - { - SECNAME1 - { - OUTPUT-SECTION-COMMAND - OUTPUT-SECTION-COMMAND - ... - } [:PHDR...] [=FILL] - SECNAME2 - { - OUTPUT-SECTION-COMMAND - OUTPUT-SECTION-COMMAND - ... - } [:PHDR...] [=FILL] - ... - } [>REGION] [:PHDR...] [=FILL] - - Everything is optional except 'OVERLAY' (a keyword), and each section -must have a name (SECNAME1 and SECNAME2 above). The section definitions -within the 'OVERLAY' construct are identical to those within the general -'SECTIONS' contruct (*note SECTIONS::), except that no addresses and no -memory regions may be defined for sections within an 'OVERLAY'. - - The sections are all defined with the same starting address. The -load addresses of the sections are arranged such that they are -consecutive in memory starting at the load address used for the -'OVERLAY' as a whole (as with normal section definitions, the load -address is optional, and defaults to the start address; the start -address is also optional, and defaults to the current value of the -location counter). - - If the 'NOCROSSREFS' keyword is used, and there any references among -the sections, the linker will report an error. Since the sections all -run at the same address, it normally does not make sense for one section -to refer directly to another. *Note NOCROSSREFS: Miscellaneous -Commands. - - For each section within the 'OVERLAY', the linker automatically -provides two symbols. The symbol '__load_start_SECNAME' is defined as -the starting load address of the section. The symbol -'__load_stop_SECNAME' is defined as the final load address of the -section. Any characters within SECNAME which are not legal within C -identifiers are removed. C (or assembler) code may use these symbols to -move the overlaid sections around as necessary. - - At the end of the overlay, the value of the location counter is set -to the start address of the overlay plus the size of the largest -section. - - Here is an example. Remember that this would appear inside a -'SECTIONS' construct. - OVERLAY 0x1000 : AT (0x4000) - { - .text0 { o1/*.o(.text) } - .text1 { o2/*.o(.text) } - } -This will define both '.text0' and '.text1' to start at address 0x1000. -'.text0' will be loaded at address 0x4000, and '.text1' will be loaded -immediately after '.text0'. The following symbols will be defined if -referenced: '__load_start_text0', '__load_stop_text0', -'__load_start_text1', '__load_stop_text1'. - - C code to copy overlay '.text1' into the overlay area might look like -the following. - - extern char __load_start_text1, __load_stop_text1; - memcpy ((char *) 0x1000, &__load_start_text1, - &__load_stop_text1 - &__load_start_text1); - - Note that the 'OVERLAY' command is just syntactic sugar, since -everything it does can be done using the more basic commands. The above -example could have been written identically as follows. - - .text0 0x1000 : AT (0x4000) { o1/*.o(.text) } - PROVIDE (__load_start_text0 = LOADADDR (.text0)); - PROVIDE (__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0)); - .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) { o2/*.o(.text) } - PROVIDE (__load_start_text1 = LOADADDR (.text1)); - PROVIDE (__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1)); - . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1)); - -3.7 MEMORY Command -================== - -The linker's default configuration permits allocation of all available -memory. You can override this by using the 'MEMORY' command. - - The 'MEMORY' command describes the location and size of blocks of -memory in the target. You can use it to describe which memory regions -may be used by the linker, and which memory regions it must avoid. You -can then assign sections to particular memory regions. The linker will -set section addresses based on the memory regions, and will warn about -regions that become too full. The linker will not shuffle sections -around to fit into the available regions. - - A linker script may contain at most one use of the 'MEMORY' command. -However, you can define as many blocks of memory within it as you wish. -The syntax is: - MEMORY - { - NAME [(ATTR)] : ORIGIN = ORIGIN, LENGTH = LEN - ... - } - - The NAME is a name used in the linker script to refer to the region. -The region name has no meaning outside of the linker script. Region -names are stored in a separate name space, and will not conflict with -symbol names, file names, or section names. Each memory region must -have a distinct name. - - The ATTR string is an optional list of attributes that specify -whether to use a particular memory region for an input section which is -not explicitly mapped in the linker script. As described in *note -SECTIONS::, if you do not specify an output section for some input -section, the linker will create an output section with the same name as -the input section. If you define region attributes, the linker will use -them to select the memory region for the output section that it creates. - - The ATTR string must consist only of the following characters: -'R' - Read-only section -'W' - Read/write section -'X' - Executable section -'A' - Allocatable section -'I' - Initialized section -'L' - Same as 'I' -'!' - Invert the sense of any of the preceding attributes - - If a unmapped section matches any of the listed attributes other than -'!', it will be placed in the memory region. The '!' attribute reverses -this test, so that an unmapped section will be placed in the memory -region only if it does not match any of the listed attributes. - - The ORIGIN is an numerical expression for the start address of the -memory region. The expression must evaluate to a constant and it cannot -involve any symbols. The keyword 'ORIGIN' may be abbreviated to 'org' -or 'o' (but not, for example, 'ORG'). - - The LEN is an expression for the size in bytes of the memory region. -As with the ORIGIN expression, the expression must be numerical only and -must evaluate to a constant. The keyword 'LENGTH' may be abbreviated to -'len' or 'l'. - - In the following example, we specify that there are two memory -regions available for allocation: one starting at '0' for 256 kilobytes, -and the other starting at '0x40000000' for four megabytes. The linker -will place into the 'rom' memory region every section which is not -explicitly mapped into a memory region, and is either read-only or -executable. The linker will place other sections which are not -explicitly mapped into a memory region into the 'ram' memory region. - - MEMORY - { - rom (rx) : ORIGIN = 0, LENGTH = 256K - ram (!rx) : org = 0x40000000, l = 4M - } - - Once you define a memory region, you can direct the linker to place -specific output sections into that memory region by using the '>REGION' -output section attribute. For example, if you have a memory region -named 'mem', you would use '>mem' in the output section definition. -*Note Output Section Region::. If no address was specified for the -output section, the linker will set the address to the next available -address within the memory region. If the combined output sections -directed to a memory region are too large for the region, the linker -will issue an error message. - - It is possible to access the origin and length of a memory in an -expression via the 'ORIGIN(MEMORY)' and 'LENGTH(MEMORY)' functions: - - _fstack = ORIGIN(ram) + LENGTH(ram) - 4; - -3.8 PHDRS Command -================= - -The ELF object file format uses "program headers", also knows as -"segments". The program headers describe how the program should be -loaded into memory. You can print them out by using the 'objdump' -program with the '-p' option. - - When you run an ELF program on a native ELF system, the system loader -reads the program headers in order to figure out how to load the -program. This will only work if the program headers are set correctly. -This manual does not describe the details of how the system loader -interprets program headers; for more information, see the ELF ABI. - - The linker will create reasonable program headers by default. -However, in some cases, you may need to specify the program headers more -precisely. You may use the 'PHDRS' command for this purpose. When the -linker sees the 'PHDRS' command in the linker script, it will not create -any program headers other than the ones specified. - - The linker only pays attention to the 'PHDRS' command when generating -an ELF output file. In other cases, the linker will simply ignore -'PHDRS'. - - This is the syntax of the 'PHDRS' command. The words 'PHDRS', -'FILEHDR', 'AT', and 'FLAGS' are keywords. - - PHDRS - { - NAME TYPE [ FILEHDR ] [ PHDRS ] [ AT ( ADDRESS ) ] - [ FLAGS ( FLAGS ) ] ; - } - - The NAME is used only for reference in the 'SECTIONS' command of the -linker script. It is not put into the output file. Program header -names are stored in a separate name space, and will not conflict with -symbol names, file names, or section names. Each program header must -have a distinct name. - - Certain program header types describe segments of memory which the -system loader will load from the file. In the linker script, you -specify the contents of these segments by placing allocatable output -sections in the segments. You use the ':PHDR' output section attribute -to place a section in a particular segment. *Note Output Section -Phdr::. - - It is normal to put certain sections in more than one segment. This -merely implies that one segment of memory contains another. You may -repeat ':PHDR', using it once for each segment which should contain the -section. - - If you place a section in one or more segments using ':PHDR', then -the linker will place all subsequent allocatable sections which do not -specify ':PHDR' in the same segments. This is for convenience, since -generally a whole set of contiguous sections will be placed in a single -segment. You can use ':NONE' to override the default segment and tell -the linker to not put the section in any segment at all. - - You may use the 'FILEHDR' and 'PHDRS' keywords appear after the -program header type to further describe the contents of the segment. -The 'FILEHDR' keyword means that the segment should include the ELF file -header. The 'PHDRS' keyword means that the segment should include the -ELF program headers themselves. - - The TYPE may be one of the following. The numbers indicate the value -of the keyword. - -'PT_NULL' (0) - Indicates an unused program header. - -'PT_LOAD' (1) - Indicates that this program header describes a segment to be loaded - from the file. - -'PT_DYNAMIC' (2) - Indicates a segment where dynamic linking information can be found. - -'PT_INTERP' (3) - Indicates a segment where the name of the program interpreter may - be found. - -'PT_NOTE' (4) - Indicates a segment holding note information. - -'PT_SHLIB' (5) - A reserved program header type, defined but not specified by the - ELF ABI. - -'PT_PHDR' (6) - Indicates a segment where the program headers may be found. - -EXPRESSION - An expression giving the numeric type of the program header. This - may be used for types not defined above. - - You can specify that a segment should be loaded at a particular -address in memory by using an 'AT' expression. This is identical to the -'AT' command used as an output section attribute (*note Output Section -LMA::). The 'AT' command for a program header overrides the output -section attribute. - - The linker will normally set the segment flags based on the sections -which comprise the segment. You may use the 'FLAGS' keyword to -explicitly specify the segment flags. The value of FLAGS must be an -integer. It is used to set the 'p_flags' field of the program header. - - Here is an example of 'PHDRS'. This shows a typical set of program -headers used on a native ELF system. - - PHDRS - { - headers PT_PHDR PHDRS ; - interp PT_INTERP ; - text PT_LOAD FILEHDR PHDRS ; - data PT_LOAD ; - dynamic PT_DYNAMIC ; - } - - SECTIONS - { - . = SIZEOF_HEADERS; - .interp : { *(.interp) } :text :interp - .text : { *(.text) } :text - .rodata : { *(.rodata) } /* defaults to :text */ - ... - . = . + 0x1000; /* move to a new page in memory */ - .data : { *(.data) } :data - .dynamic : { *(.dynamic) } :data :dynamic - ... - } - -3.9 VERSION Command -=================== - -The linker supports symbol versions when using ELF. Symbol versions are -only useful when using shared libraries. The dynamic linker can use -symbol versions to select a specific version of a function when it runs -a program that may have been linked against an earlier version of the -shared library. - - You can include a version script directly in the main linker script, -or you can supply the version script as an implicit linker script. You -can also use the '--version-script' linker option. - - The syntax of the 'VERSION' command is simply - VERSION { version-script-commands } - - The format of the version script commands is identical to that used -by Sun's linker in Solaris 2.5. The version script defines a tree of -version nodes. You specify the node names and interdependencies in the -version script. You can specify which symbols are bound to which -version nodes, and you can reduce a specified set of symbols to local -scope so that they are not globally visible outside of the shared -library. - - The easiest way to demonstrate the version script language is with a -few examples. - - VERS_1.1 { - global: - foo1; - local: - old*; - original*; - new*; - }; - - VERS_1.2 { - foo2; - } VERS_1.1; - - VERS_2.0 { - bar1; bar2; - extern "C++" { - ns::*; - "int f(int, double)"; - } - } VERS_1.2; - - This example version script defines three version nodes. The first -version node defined is 'VERS_1.1'; it has no other dependencies. The -script binds the symbol 'foo1' to 'VERS_1.1'. It reduces a number of -symbols to local scope so that they are not visible outside of the -shared library; this is done using wildcard patterns, so that any symbol -whose name begins with 'old', 'original', or 'new' is matched. The -wildcard patterns available are the same as those used in the shell when -matching filenames (also known as "globbing"). However, if you specify -the symbol name inside double quotes, then the name is treated as -literal, rather than as a glob pattern. - - Next, the version script defines node 'VERS_1.2'. This node depends -upon 'VERS_1.1'. The script binds the symbol 'foo2' to the version node -'VERS_1.2'. - - Finally, the version script defines node 'VERS_2.0'. This node -depends upon 'VERS_1.2'. The scripts binds the symbols 'bar1' and -'bar2' are bound to the version node 'VERS_2.0'. - - When the linker finds a symbol defined in a library which is not -specifically bound to a version node, it will effectively bind it to an -unspecified base version of the library. You can bind all otherwise -unspecified symbols to a given version node by using 'global: *;' -somewhere in the version script. - - The names of the version nodes have no specific meaning other than -what they might suggest to the person reading them. The '2.0' version -could just as well have appeared in between '1.1' and '1.2'. However, -this would be a confusing way to write a version script. - - Node name can be omitted, provided it is the only version node in the -version script. Such version script doesn't assign any versions to -symbols, only selects which symbols will be globally visible out and -which won't. - - { global: foo; bar; local: *; }; - - When you link an application against a shared library that has -versioned symbols, the application itself knows which version of each -symbol it requires, and it also knows which version nodes it needs from -each shared library it is linked against. Thus at runtime, the dynamic -loader can make a quick check to make sure that the libraries you have -linked against do in fact supply all of the version nodes that the -application will need to resolve all of the dynamic symbols. In this -way it is possible for the dynamic linker to know with certainty that -all external symbols that it needs will be resolvable without having to -search for each symbol reference. - - The symbol versioning is in effect a much more sophisticated way of -doing minor version checking that SunOS does. The fundamental problem -that is being addressed here is that typically references to external -functions are bound on an as-needed basis, and are not all bound when -the application starts up. If a shared library is out of date, a -required interface may be missing; when the application tries to use -that interface, it may suddenly and unexpectedly fail. With symbol -versioning, the user will get a warning when they start their program if -the libraries being used with the application are too old. - - There are several GNU extensions to Sun's versioning approach. The -first of these is the ability to bind a symbol to a version node in the -source file where the symbol is defined instead of in the versioning -script. This was done mainly to reduce the burden on the library -maintainer. You can do this by putting something like: - __asm__(".symver original_foo,foo@VERS_1.1"); -in the C source file. This renames the function 'original_foo' to be an -alias for 'foo' bound to the version node 'VERS_1.1'. The 'local:' -directive can be used to prevent the symbol 'original_foo' from being -exported. A '.symver' directive takes precedence over a version script. - - The second GNU extension is to allow multiple versions of the same -function to appear in a given shared library. In this way you can make -an incompatible change to an interface without increasing the major -version number of the shared library, while still allowing applications -linked against the old interface to continue to function. - - To do this, you must use multiple '.symver' directives in the source -file. Here is an example: - - __asm__(".symver original_foo,foo@"); - __asm__(".symver old_foo,foo@VERS_1.1"); - __asm__(".symver old_foo1,foo@VERS_1.2"); - __asm__(".symver new_foo,foo@@VERS_2.0"); - - In this example, 'foo@' represents the symbol 'foo' bound to the -unspecified base version of the symbol. The source file that contains -this example would define 4 C functions: 'original_foo', 'old_foo', -'old_foo1', and 'new_foo'. - - When you have multiple definitions of a given symbol, there needs to -be some way to specify a default version to which external references to -this symbol will be bound. You can do this with the 'foo@@VERS_2.0' -type of '.symver' directive. You can only declare one version of a -symbol as the default in this manner; otherwise you would effectively -have multiple definitions of the same symbol. - - If you wish to bind a reference to a specific version of the symbol -within the shared library, you can use the aliases of convenience (i.e., -'old_foo'), or you can use the '.symver' directive to specifically bind -to an external version of the function in question. - - You can also specify the language in the version script: - - VERSION extern "lang" { version-script-commands } - - The supported 'lang's are 'C', 'C++', and 'Java'. The linker will -iterate over the list of symbols at the link time and demangle them -according to 'lang' before matching them to the patterns specified in -'version-script-commands'. - - Demangled names may contains spaces and other special characters. As -described above, you can use a glob pattern to match demangled names, or -you can use a double-quoted string to match the string exactly. In the -latter case, be aware that minor differences (such as differing -whitespace) between the version script and the demangler output will -cause a mismatch. As the exact string generated by the demangler might -change in the future, even if the mangled name does not, you should -check that all of your version directives are behaving as you expect -when you upgrade. - -3.10 Expressions in Linker Scripts -================================== - -The syntax for expressions in the linker script language is identical to -that of C expressions. All expressions are evaluated as integers. All -expressions are evaluated in the same size, which is 32 bits if both the -host and target are 32 bits, and is otherwise 64 bits. - - You can use and set symbol values in expressions. - - The linker defines several special purpose builtin functions for use -in expressions. - -3.10.1 Constants ----------------- - -All constants are integers. - - As in C, the linker considers an integer beginning with '0' to be -octal, and an integer beginning with '0x' or '0X' to be hexadecimal. -The linker considers other integers to be decimal. - - In addition, you can use the suffixes 'K' and 'M' to scale a constant -by '1024' or '1024*1024' respectively. For example, the following all -refer to the same quantity: - _fourk_1 = 4K; - _fourk_2 = 4096; - _fourk_3 = 0x1000; - -3.10.2 Symbol Names -------------------- - -Unless quoted, symbol names start with a letter, underscore, or period -and may include letters, digits, underscores, periods, and hyphens. -Unquoted symbol names must not conflict with any keywords. You can -specify a symbol which contains odd characters or has the same name as a -keyword by surrounding the symbol name in double quotes: - "SECTION" = 9; - "with a space" = "also with a space" + 10; - - Since symbols can contain many non-alphabetic characters, it is -safest to delimit symbols with spaces. For example, 'A-B' is one -symbol, whereas 'A - B' is an expression involving subtraction. - -3.10.3 Orphan Sections ----------------------- - -Orphan sections are sections present in the input files which are not -explicitly placed into the output file by the linker script. The linker -will still copy these sections into the output file, but it has to guess -as to where they should be placed. The linker uses a simple heuristic -to do this. It attempts to place orphan sections after non-orphan -sections of the same attribute, such as code vs data, loadable vs -non-loadable, etc. If there is not enough room to do this then it -places at the end of the file. - - For ELF targets, the attribute of the section includes section type -as well as section flag. - -3.10.4 The Location Counter ---------------------------- - -The special linker variable "dot" '.' always contains the current output -location counter. Since the '.' always refers to a location in an -output section, it may only appear in an expression within a 'SECTIONS' -command. The '.' symbol may appear anywhere that an ordinary symbol is -allowed in an expression. - - Assigning a value to '.' will cause the location counter to be moved. -This may be used to create holes in the output section. The location -counter may not be moved backwards inside an output section, and may not -be moved backwards outside of an output section if so doing creates -areas with overlapping LMAs. - - SECTIONS - { - output : - { - file1(.text) - . = . + 1000; - file2(.text) - . += 1000; - file3(.text) - } = 0x12345678; - } -In the previous example, the '.text' section from 'file1' is located at -the beginning of the output section 'output'. It is followed by a 1000 -byte gap. Then the '.text' section from 'file2' appears, also with a -1000 byte gap following before the '.text' section from 'file3'. The -notation '= 0x12345678' specifies what data to write in the gaps (*note -Output Section Fill::). - - Note: '.' actually refers to the byte offset from the start of the -current containing object. Normally this is the 'SECTIONS' statement, -whose start address is 0, hence '.' can be used as an absolute address. -If '.' is used inside a section description however, it refers to the -byte offset from the start of that section, not an absolute address. -Thus in a script like this: - - SECTIONS - { - . = 0x100 - .text: { - *(.text) - . = 0x200 - } - . = 0x500 - .data: { - *(.data) - . += 0x600 - } - } - - The '.text' section will be assigned a starting address of 0x100 and -a size of exactly 0x200 bytes, even if there is not enough data in the -'.text' input sections to fill this area. (If there is too much data, -an error will be produced because this would be an attempt to move '.' -backwards). The '.data' section will start at 0x500 and it will have an -extra 0x600 bytes worth of space after the end of the values from the -'.data' input sections and before the end of the '.data' output section -itself. - - Setting symbols to the value of the location counter outside of an -output section statement can result in unexpected values if the linker -needs to place orphan sections. For example, given the following: - - SECTIONS - { - start_of_text = . ; - .text: { *(.text) } - end_of_text = . ; - - start_of_data = . ; - .data: { *(.data) } - end_of_data = . ; - } - - If the linker needs to place some input section, e.g. '.rodata', not -mentioned in the script, it might choose to place that section between -'.text' and '.data'. You might think the linker should place '.rodata' -on the blank line in the above script, but blank lines are of no -particular significance to the linker. As well, the linker doesn't -associate the above symbol names with their sections. Instead, it -assumes that all assignments or other statements belong to the previous -output section, except for the special case of an assignment to '.'. -I.e., the linker will place the orphan '.rodata' section as if the -script was written as follows: - - SECTIONS - { - start_of_text = . ; - .text: { *(.text) } - end_of_text = . ; - - start_of_data = . ; - .rodata: { *(.rodata) } - .data: { *(.data) } - end_of_data = . ; - } - - This may or may not be the script author's intention for the value of -'start_of_data'. One way to influence the orphan section placement is -to assign the location counter to itself, as the linker assumes that an -assignment to '.' is setting the start address of a following output -section and thus should be grouped with that section. So you could -write: - - SECTIONS - { - start_of_text = . ; - .text: { *(.text) } - end_of_text = . ; - - . = . ; - start_of_data = . ; - .data: { *(.data) } - end_of_data = . ; - } - - Now, the orphan '.rodata' section will be placed between -'end_of_text' and 'start_of_data'. - -3.10.5 Operators ----------------- - -The linker recognizes the standard C set of arithmetic operators, with -the standard bindings and precedence levels: - precedence associativity Operators Notes - (highest) - 1 left ! - ~ (1) - 2 left * / % - 3 left + - - 4 left >> << - 5 left == != > < <= >= - 6 left & - 7 left | - 8 left && - 9 left || - 10 right ? : - 11 right &= += -= *= /= (2) - (lowest) - Notes: (1) Prefix operators (2) *Note Assignments::. - -3.10.6 Evaluation ------------------ - -The linker evaluates expressions lazily. It only computes the value of -an expression when absolutely necessary. - - The linker needs some information, such as the value of the start -address of the first section, and the origins and lengths of memory -regions, in order to do any linking at all. These values are computed -as soon as possible when the linker reads in the linker script. - - However, other values (such as symbol values) are not known or needed -until after storage allocation. Such values are evaluated later, when -other information (such as the sizes of output sections) is available -for use in the symbol assignment expression. - - The sizes of sections cannot be known until after allocation, so -assignments dependent upon these are not performed until after -allocation. - - Some expressions, such as those depending upon the location counter -'.', must be evaluated during section allocation. - - If the result of an expression is required, but the value is not -available, then an error results. For example, a script like the -following - SECTIONS - { - .text 9+this_isnt_constant : - { *(.text) } - } -will cause the error message 'non constant expression for initial -address'. - -3.10.7 The Section of an Expression ------------------------------------ - -When the linker evaluates an expression, the result is either absolute -or relative to some section. A relative expression is expressed as a -fixed offset from the base of a section. - - The position of the expression within the linker script determines -whether it is absolute or relative. An expression which appears within -an output section definition is relative to the base of the output -section. An expression which appears elsewhere will be absolute. - - A symbol set to a relative expression will be relocatable if you -request relocatable output using the '-r' option. That means that a -further link operation may change the value of the symbol. The symbol's -section will be the section of the relative expression. - - A symbol set to an absolute expression will retain the same value -through any further link operation. The symbol will be absolute, and -will not have any particular associated section. - - You can use the builtin function 'ABSOLUTE' to force an expression to -be absolute when it would otherwise be relative. For example, to create -an absolute symbol set to the address of the end of the output section -'.data': - SECTIONS - { - .data : { *(.data) _edata = ABSOLUTE(.); } - } -If 'ABSOLUTE' were not used, '_edata' would be relative to the '.data' -section. - -3.10.8 Builtin Functions ------------------------- - -The linker script language includes a number of builtin functions for -use in linker script expressions. - -'ABSOLUTE(EXP)' - Return the absolute (non-relocatable, as opposed to non-negative) - value of the expression EXP. Primarily useful to assign an - absolute value to a symbol within a section definition, where - symbol values are normally section relative. *Note Expression - Section::. - -'ADDR(SECTION)' - Return the absolute address (the VMA) of the named SECTION. Your - script must previously have defined the location of that section. - In the following example, 'symbol_1' and 'symbol_2' are assigned - identical values: - SECTIONS { ... - .output1 : - { - start_of_output_1 = ABSOLUTE(.); - ... - } - .output : - { - symbol_1 = ADDR(.output1); - symbol_2 = start_of_output_1; - } - ... } - -'ALIGN(ALIGN)' -'ALIGN(EXP,ALIGN)' - Return the location counter ('.') or arbitrary expression aligned - to the next ALIGN boundary. The single operand 'ALIGN' doesn't - change the value of the location counter--it just does arithmetic - on it. The two operand 'ALIGN' allows an arbitrary expression to - be aligned upwards ('ALIGN(ALIGN)' is equivalent to 'ALIGN(., - ALIGN)'). - - Here is an example which aligns the output '.data' section to the - next '0x2000' byte boundary after the preceding section and sets a - variable within the section to the next '0x8000' boundary after the - input sections: - SECTIONS { ... - .data ALIGN(0x2000): { - *(.data) - variable = ALIGN(0x8000); - } - ... } - The first use of 'ALIGN' in this example specifies the location of - a section because it is used as the optional ADDRESS attribute of a - section definition (*note Output Section Address::). The second - use of 'ALIGN' is used to defines the value of a symbol. - - The builtin function 'NEXT' is closely related to 'ALIGN'. - -'ALIGNOF(SECTION)' - Return the alignment in bytes of the named SECTION, if that section - has been allocated. If the section has not been allocated when - this is evaluated, the linker will report an error. In the - following example, the alignment of the '.output' section is stored - as the first value in that section. - SECTIONS{ ... - .output { - LONG (ALIGNOF (.output)) - ... - } - ... } - -'BLOCK(EXP)' - This is a synonym for 'ALIGN', for compatibility with older linker - scripts. It is most often seen when setting the address of an - output section. - -'DATA_SEGMENT_ALIGN(MAXPAGESIZE, COMMONPAGESIZE)' - This is equivalent to either - (ALIGN(MAXPAGESIZE) + (. & (MAXPAGESIZE - 1))) - or - (ALIGN(MAXPAGESIZE) + (. & (MAXPAGESIZE - COMMONPAGESIZE))) - depending on whether the latter uses fewer COMMONPAGESIZE sized - pages for the data segment (area between the result of this - expression and 'DATA_SEGMENT_END') than the former or not. If the - latter form is used, it means COMMONPAGESIZE bytes of runtime - memory will be saved at the expense of up to COMMONPAGESIZE wasted - bytes in the on-disk file. - - This expression can only be used directly in 'SECTIONS' commands, - not in any output section descriptions and only once in the linker - script. COMMONPAGESIZE should be less or equal to MAXPAGESIZE and - should be the system page size the object wants to be optimized for - (while still working on system page sizes up to MAXPAGESIZE). - - Example: - . = DATA_SEGMENT_ALIGN(0x10000, 0x2000); - -'DATA_SEGMENT_END(EXP)' - This defines the end of data segment for 'DATA_SEGMENT_ALIGN' - evaluation purposes. - - . = DATA_SEGMENT_END(.); - -'DATA_SEGMENT_RELRO_END(OFFSET, EXP)' - This defines the end of the 'PT_GNU_RELRO' segment when '-z relro' - option is used. Second argument is returned. When '-z relro' - option is not present, 'DATA_SEGMENT_RELRO_END' does nothing, - otherwise 'DATA_SEGMENT_ALIGN' is padded so that EXP + OFFSET is - aligned to the most commonly used page boundary for particular - target. If present in the linker script, it must always come in - between 'DATA_SEGMENT_ALIGN' and 'DATA_SEGMENT_END'. - - . = DATA_SEGMENT_RELRO_END(24, .); - -'DEFINED(SYMBOL)' - Return 1 if SYMBOL is in the linker global symbol table and is - defined before the statement using DEFINED in the script, otherwise - return 0. You can use this function to provide default values for - symbols. For example, the following script fragment shows how to - set a global symbol 'begin' to the first location in the '.text' - section--but if a symbol called 'begin' already existed, its value - is preserved: - - SECTIONS { ... - .text : { - begin = DEFINED(begin) ? begin : . ; - ... - } - ... - } - -'LENGTH(MEMORY)' - Return the length of the memory region named MEMORY. - -'LOADADDR(SECTION)' - Return the absolute LMA of the named SECTION. This is normally the - same as 'ADDR', but it may be different if the 'AT' attribute is - used in the output section definition (*note Output Section LMA::). - -'MAX(EXP1, EXP2)' - Returns the maximum of EXP1 and EXP2. - -'MIN(EXP1, EXP2)' - Returns the minimum of EXP1 and EXP2. - -'NEXT(EXP)' - Return the next unallocated address that is a multiple of EXP. - This function is closely related to 'ALIGN(EXP)'; unless you use - the 'MEMORY' command to define discontinuous memory for the output - file, the two functions are equivalent. - -'ORIGIN(MEMORY)' - Return the origin of the memory region named MEMORY. - -'SEGMENT_START(SEGMENT, DEFAULT)' - Return the base address of the named SEGMENT. If an explicit value - has been given for this segment (with a command-line '-T' option) - that value will be returned; otherwise the value will be DEFAULT. - At present, the '-T' command-line option can only be used to set - the base address for the "text", "data", and "bss" sections, but - you use 'SEGMENT_START' with any segment name. - -'SIZEOF(SECTION)' - Return the size in bytes of the named SECTION, if that section has - been allocated. If the section has not been allocated when this is - evaluated, the linker will report an error. In the following - example, 'symbol_1' and 'symbol_2' are assigned identical values: - SECTIONS{ ... - .output { - .start = . ; - ... - .end = . ; - } - symbol_1 = .end - .start ; - symbol_2 = SIZEOF(.output); - ... } - -'SIZEOF_HEADERS' -'sizeof_headers' - Return the size in bytes of the output file's headers. This is - information which appears at the start of the output file. You can - use this number when setting the start address of the first - section, if you choose, to facilitate paging. - - When producing an ELF output file, if the linker script uses the - 'SIZEOF_HEADERS' builtin function, the linker must compute the - number of program headers before it has determined all the section - addresses and sizes. If the linker later discovers that it needs - additional program headers, it will report an error 'not enough - room for program headers'. To avoid this error, you must avoid - using the 'SIZEOF_HEADERS' function, or you must rework your linker - script to avoid forcing the linker to use additional program - headers, or you must define the program headers yourself using the - 'PHDRS' command (*note PHDRS::). - -3.11 Implicit Linker Scripts -============================ - -If you specify a linker input file which the linker can not recognize as -an object file or an archive file, it will try to read the file as a -linker script. If the file can not be parsed as a linker script, the -linker will report an error. - - An implicit linker script will not replace the default linker script. - - Typically an implicit linker script would contain only symbol -assignments, or the 'INPUT', 'GROUP', or 'VERSION' commands. - - Any input files read because of an implicit linker script will be -read at the position in the command line where the implicit linker -script was read. This can affect archive searching. - -4 Machine Dependent Features -**************************** - -'ld' has additional features on some platforms; the following sections -describe them. Machines where 'ld' has no additional functionality are -not listed. - -4.1 'ld' and the H8/300 -======================= - -For the H8/300, 'ld' can perform these global optimizations when you -specify the '--relax' command-line option. - -_relaxing address modes_ - 'ld' finds all 'jsr' and 'jmp' instructions whose targets are - within eight bits, and turns them into eight-bit program-counter - relative 'bsr' and 'bra' instructions, respectively. - -_synthesizing instructions_ - 'ld' finds all 'mov.b' instructions which use the sixteen-bit - absolute address form, but refer to the top page of memory, and - changes them to use the eight-bit address form. (That is: the - linker turns 'mov.b '@'AA:16' into 'mov.b '@'AA:8' whenever the - address AA is in the top page of memory). - -_bit manipulation instructions_ - 'ld' finds all bit manipulation instructions like 'band, bclr, - biand, bild, bior, bist, bixor, bld, bnot, bor, bset, bst, btst, - bxor' which use 32 bit and 16 bit absolute address form, but refer - to the top page of memory, and changes them to use the 8 bit - address form. (That is: the linker turns 'bset #xx:3,'@'AA:32' - into 'bset #xx:3,'@'AA:8' whenever the address AA is in the top - page of memory). - -_system control instructions_ - 'ld' finds all 'ldc.w, stc.w' instructions which use the 32 bit - absolute address form, but refer to the top page of memory, and - changes them to use 16 bit address form. (That is: the linker - turns 'ldc.w '@'AA:32,ccr' into 'ldc.w '@'AA:16,ccr' whenever the - address AA is in the top page of memory). - -4.2 'ld' and the Intel 960 Family -================================= - -You can use the '-AARCHITECTURE' command line option to specify one of -the two-letter names identifying members of the 960 family; the option -specifies the desired output target, and warns of any incompatible -instructions in the input files. It also modifies the linker's search -strategy for archive libraries, to support the use of libraries specific -to each particular architecture, by including in the search loop names -suffixed with the string identifying the architecture. - - For example, if your 'ld' command line included '-ACA' as well as -'-ltry', the linker would look (in its built-in search paths, and in any -paths you specify with '-L') for a library with the names - - try - libtry.a - tryca - libtryca.a - -The first two possibilities would be considered in any event; the last -two are due to the use of '-ACA'. - - You can meaningfully use '-A' more than once on a command line, since -the 960 architecture family allows combination of target architectures; -each use will add another pair of name variants to search for when '-l' -specifies a library. - - 'ld' supports the '--relax' option for the i960 family. If you -specify '--relax', 'ld' finds all 'balx' and 'calx' instructions whose -targets are within 24 bits, and turns them into 24-bit program-counter -relative 'bal' and 'cal' instructions, respectively. 'ld' also turns -'cal' instructions into 'bal' instructions when it determines that the -target subroutine is a leaf routine (that is, the target subroutine does -not itself call any subroutines). - -4.3 'ld' and the Motorola 68HC11 and 68HC12 families -==================================================== - -4.3.1 Linker Relaxation ------------------------ - -For the Motorola 68HC11, 'ld' can perform these global optimizations -when you specify the '--relax' command-line option. - -_relaxing address modes_ - 'ld' finds all 'jsr' and 'jmp' instructions whose targets are - within eight bits, and turns them into eight-bit program-counter - relative 'bsr' and 'bra' instructions, respectively. - - 'ld' also looks at all 16-bit extended addressing modes and - transforms them in a direct addressing mode when the address is in - page 0 (between 0 and 0x0ff). - -_relaxing gcc instruction group_ - When 'gcc' is called with '-mrelax', it can emit group of - instructions that the linker can optimize to use a 68HC11 direct - addressing mode. These instructions consists of 'bclr' or 'bset' - instructions. - -4.3.2 Trampoline Generation ---------------------------- - -For 68HC11 and 68HC12, 'ld' can generate trampoline code to call a far -function using a normal 'jsr' instruction. The linker will also change -the relocation to some far function to use the trampoline address -instead of the function address. This is typically the case when a -pointer to a function is taken. The pointer will in fact point to the -function trampoline. - - The '--pic-veneer' switch makes the linker use PIC sequences for -ARM/Thumb interworking veneers, even if the rest of the binary is not -PIC. This avoids problems on uClinux targets where '--emit-relocs' is -used to generate relocatable binaries. - -4.4 'ld' and the ARM family -=========================== - -For the ARM, 'ld' will generate code stubs to allow functions calls -between ARM and Thumb code. These stubs only work with code that has -been compiled and assembled with the '-mthumb-interwork' command line -option. If it is necessary to link with old ARM object files or -libraries, which have not been compiled with the -mthumb-interwork -option then the '--support-old-code' command line switch should be given -to the linker. This will make it generate larger stub functions which -will work with non-interworking aware ARM code. Note, however, the -linker does not support generating stubs for function calls to -non-interworking aware Thumb code. - - The '--thumb-entry' switch is a duplicate of the generic '--entry' -switch, in that it sets the program's starting address. But it also -sets the bottom bit of the address, so that it can be branched to using -a BX instruction, and the program will start executing in Thumb mode -straight away. - - The '--be8' switch instructs 'ld' to generate BE8 format executables. -This option is only valid when linking big-endian objects. The -resulting image will contain big-endian data and little-endian code. - - The 'R_ARM_TARGET1' relocation is typically used for entries in the -'.init_array' section. It is interpreted as either 'R_ARM_REL32' or -'R_ARM_ABS32', depending on the target. The '--target1-rel' and -'--target1-abs' switches override the default. - - The '--target2=type' switch overrides the default definition of the -'R_ARM_TARGET2' relocation. Valid values for 'type', their meanings, -and target defaults are as follows: -'rel' - 'R_ARM_REL32' (arm*-*-elf, arm*-*-eabi) -'abs' - 'R_ARM_ABS32' (arm*-*-symbianelf) -'got-rel' - 'R_ARM_GOT_PREL' (arm*-*-linux, arm*-*-*bsd) - - The 'R_ARM_V4BX' relocation (defined by the ARM AAELF specification) -enables objects compiled for the ARMv4 architecture to be -interworking-safe when linked with other objects compiled for ARMv4t, -but also allows pure ARMv4 binaries to be built from the same ARMv4 -objects. - - In the latter case, the switch '--fix-v4bx' must be passed to the -linker, which causes v4t 'BX rM' instructions to be rewritten as 'MOV -PC,rM', since v4 processors do not have a 'BX' instruction. - - In the former case, the switch should not be used, and 'R_ARM_V4BX' -relocations are ignored. - - The '--use-blx' switch enables the linker to use ARM/Thumb BLX -instructions (available on ARMv5t and above) in various situations. -Currently it is used to perform calls via the PLT from Thumb code using -BLX rather than using BX and a mode-switching stub before each PLT -entry. This should lead to such calls executing slightly faster. - - This option is enabled implicitly for SymbianOS, so there is no need -to specify it if you are using that target. - - The '--vfp11-denorm-fix' switch enables a link-time workaround for a -bug in certain VFP11 coprocessor hardware, which sometimes allows -instructions with denorm operands (which must be handled by support -code) to have those operands overwritten by subsequent instructions -before the support code can read the intended values. - - The bug may be avoided in scalar mode if you allow at least one -intervening instruction between a VFP11 instruction which uses a -register and another instruction which writes to the same register, or -at least two intervening instructions if vector mode is in use. The bug -only affects full-compliance floating-point mode: you do not need this -workaround if you are using "runfast" mode. Please contact ARM for -further details. - - If you know you are using buggy VFP11 hardware, you can enable this -workaround by specifying the linker option '--vfp-denorm-fix=scalar' if -you are using the VFP11 scalar mode only, or '--vfp-denorm-fix=vector' -if you are using vector mode (the latter also works for scalar code). -The default is '--vfp-denorm-fix=none'. - - If the workaround is enabled, instructions are scanned for -potentially-troublesome sequences, and a veneer is created for each such -sequence which may trigger the erratum. The veneer consists of the -first instruction of the sequence and a branch back to the subsequent -instruction. The original instruction is then replaced with a branch to -the veneer. The extra cycles required to call and return from the -veneer are sufficient to avoid the erratum in both the scalar and vector -cases. - - The '--no-enum-size-warning' switch prevents the linker from warning -when linking object files that specify incompatible EABI enumeration -size attributes. For example, with this switch enabled, linking of an -object file using 32-bit enumeration values with another using -enumeration values fitted into the smallest possible space will not be -diagnosed. - -4.5 'ld' and HPPA 32-bit ELF Support -==================================== - -When generating a shared library, 'ld' will by default generate import -stubs suitable for use with a single sub-space application. The -'--multi-subspace' switch causes 'ld' to generate export stubs, and -different (larger) import stubs suitable for use with multiple -sub-spaces. - - Long branch stubs and import/export stubs are placed by 'ld' in stub -sections located between groups of input sections. '--stub-group-size' -specifies the maximum size of a group of input sections handled by one -stub section. Since branch offsets are signed, a stub section may serve -two groups of input sections, one group before the stub section, and one -group after it. However, when using conditional branches that require -stubs, it may be better (for branch prediction) that stub sections only -serve one group of input sections. A negative value for 'N' chooses -this scheme, ensuring that branches to stubs always use a negative -offset. Two special values of 'N' are recognized, '1' and '-1'. These -both instruct 'ld' to automatically size input section groups for the -branch types detected, with the same behaviour regarding stub placement -as other positive or negative values of 'N' respectively. - - Note that '--stub-group-size' does not split input sections. A -single input section larger than the group size specified will of course -create a larger group (of one section). If input sections are too -large, it may not be possible for a branch to reach its stub. - -4.6 'ld' and MMIX -================= - -For MMIX, there is a choice of generating 'ELF' object files or 'mmo' -object files when linking. The simulator 'mmix' understands the 'mmo' -format. The binutils 'objcopy' utility can translate between the two -formats. - - There is one special section, the '.MMIX.reg_contents' section. -Contents in this section is assumed to correspond to that of global -registers, and symbols referring to it are translated to special -symbols, equal to registers. In a final link, the start address of the -'.MMIX.reg_contents' section corresponds to the first allocated global -register multiplied by 8. Register '$255' is not included in this -section; it is always set to the program entry, which is at the symbol -'Main' for 'mmo' files. - - Symbols with the prefix '__.MMIX.start.', for example -'__.MMIX.start..text' and '__.MMIX.start..data' are special; there must -be only one each, even if they are local. The default linker script -uses these to set the default start address of a section. - - Initial and trailing multiples of zero-valued 32-bit words in a -section, are left out from an mmo file. - -4.7 'ld' and MSP430 -=================== - -For the MSP430 it is possible to select the MPU architecture. The flag -'-m [mpu type]' will select an appropriate linker script for selected -MPU type. (To get a list of known MPUs just pass '-m help' option to -the linker). - - The linker will recognize some extra sections which are MSP430 -specific: - -''.vectors'' - Defines a portion of ROM where interrupt vectors located. - -''.bootloader'' - Defines the bootloader portion of the ROM (if applicable). Any - code in this section will be uploaded to the MPU. - -''.infomem'' - Defines an information memory section (if applicable). Any code in - this section will be uploaded to the MPU. - -''.infomemnobits'' - This is the same as the '.infomem' section except that any code in - this section will not be uploaded to the MPU. - -''.noinit'' - Denotes a portion of RAM located above '.bss' section. - - The last two sections are used by gcc. - -4.8 'ld' and PowerPC 32-bit ELF Support -======================================= - -Branches on PowerPC processors are limited to a signed 26-bit -displacement, which may result in 'ld' giving 'relocation truncated to -fit' errors with very large programs. '--relax' enables the generation -of trampolines that can access the entire 32-bit address space. These -trampolines are inserted at section boundaries, so may not themselves be -reachable if an input section exceeds 33M in size. - -'--bss-plt' - Current PowerPC GCC accepts a '-msecure-plt' option that generates - code capable of using a newer PLT and GOT layout that has the - security advantage of no executable section ever needing to be - writable and no writable section ever being executable. PowerPC - 'ld' will generate this layout, including stubs to access the PLT, - if all input files (including startup and static libraries) were - compiled with '-msecure-plt'. '--bss-plt' forces the old BSS PLT - (and GOT layout) which can give slightly better performance. - -'--secure-plt' - 'ld' will use the new PLT and GOT layout if it is linking new - '-fpic' or '-fPIC' code, but does not do so automatically when - linking non-PIC code. This option requests the new PLT and GOT - layout. A warning will be given if some object file requires the - old style BSS PLT. - -'--sdata-got' - The new secure PLT and GOT are placed differently relative to other - sections compared to older BSS PLT and GOT placement. The location - of '.plt' must change because the new secure PLT is an initialized - section while the old PLT is uninitialized. The reason for the - '.got' change is more subtle: The new placement allows '.got' to be - read-only in applications linked with '-z relro -z now'. However, - this placement means that '.sdata' cannot always be used in shared - libraries, because the PowerPC ABI accesses '.sdata' in shared - libraries from the GOT pointer. '--sdata-got' forces the old GOT - placement. PowerPC GCC doesn't use '.sdata' in shared libraries, - so this option is really only useful for other compilers that may - do so. - -'--emit-stub-syms' - This option causes 'ld' to label linker stubs with a local symbol - that encodes the stub type and destination. - -'--no-tls-optimize' - PowerPC 'ld' normally performs some optimization of code sequences - used to access Thread-Local Storage. Use this option to disable - the optimization. - -4.9 'ld' and PowerPC64 64-bit ELF Support -========================================= - -'--stub-group-size' - Long branch stubs, PLT call stubs and TOC adjusting stubs are - placed by 'ld' in stub sections located between groups of input - sections. '--stub-group-size' specifies the maximum size of a - group of input sections handled by one stub section. Since branch - offsets are signed, a stub section may serve two groups of input - sections, one group before the stub section, and one group after - it. However, when using conditional branches that require stubs, - it may be better (for branch prediction) that stub sections only - serve one group of input sections. A negative value for 'N' - chooses this scheme, ensuring that branches to stubs always use a - negative offset. Two special values of 'N' are recognized, '1' and - '-1'. These both instruct 'ld' to automatically size input section - groups for the branch types detected, with the same behaviour - regarding stub placement as other positive or negative values of - 'N' respectively. - - Note that '--stub-group-size' does not split input sections. A - single input section larger than the group size specified will of - course create a larger group (of one section). If input sections - are too large, it may not be possible for a branch to reach its - stub. - -'--emit-stub-syms' - This option causes 'ld' to label linker stubs with a local symbol - that encodes the stub type and destination. - -'--dotsyms, --no-dotsyms' - These two options control how 'ld' interprets version patterns in a - version script. Older PowerPC64 compilers emitted both a function - descriptor symbol with the same name as the function, and a code - entry symbol with the name prefixed by a dot ('.'). To properly - version a function 'foo', the version script thus needs to control - both 'foo' and '.foo'. The option '--dotsyms', on by default, - automatically adds the required dot-prefixed patterns. Use - '--no-dotsyms' to disable this feature. - -'--no-tls-optimize' - PowerPC64 'ld' normally performs some optimization of code - sequences used to access Thread-Local Storage. Use this option to - disable the optimization. - -'--no-opd-optimize' - PowerPC64 'ld' normally removes '.opd' section entries - corresponding to deleted link-once functions, or functions removed - by the action of '--gc-sections' or linker scrip '/DISCARD/'. Use - this option to disable '.opd' optimization. - -'--non-overlapping-opd' - Some PowerPC64 compilers have an option to generate compressed - '.opd' entries spaced 16 bytes apart, overlapping the third word, - the static chain pointer (unused in C) with the first word of the - next entry. This option expands such entries to the full 24 bytes. - -'--no-toc-optimize' - PowerPC64 'ld' normally removes unused '.toc' section entries. - Such entries are detected by examining relocations that reference - the TOC in code sections. A reloc in a deleted code section marks - a TOC word as unneeded, while a reloc in a kept code section marks - a TOC word as needed. Since the TOC may reference itself, TOC - relocs are also examined. TOC words marked as both needed and - unneeded will of course be kept. TOC words without any referencing - reloc are assumed to be part of a multi-word entry, and are kept or - discarded as per the nearest marked preceding word. This works - reliably for compiler generated code, but may be incorrect if - assembly code is used to insert TOC entries. Use this option to - disable the optimization. - -'--no-multi-toc' - By default, PowerPC64 GCC generates code for a TOC model where TOC - entries are accessed with a 16-bit offset from r2. This limits the - total TOC size to 64K. PowerPC64 'ld' extends this limit by - grouping code sections such that each group uses less than 64K for - its TOC entries, then inserts r2 adjusting stubs between - inter-group calls. 'ld' does not split apart input sections, so - cannot help if a single input file has a '.toc' section that - exceeds 64K, most likely from linking multiple files with 'ld -r'. - Use this option to turn off this feature. - -4.10 'ld' and SPU ELF Support -============================= - -'--plugin' - This option marks an executable as a PIC plugin module. - -'--no-overlays' - Normally, 'ld' recognizes calls to functions within overlay - regions, and redirects such calls to an overlay manager via a stub. - 'ld' also provides a built-in overlay manager. This option turns - off all this special overlay handling. - -'--emit-stub-syms' - This option causes 'ld' to label overlay stubs with a local symbol - that encodes the stub type and destination. - -'--extra-overlay-stubs' - This option causes 'ld' to add overlay call stubs on all function - calls out of overlay regions. Normally stubs are not added on - calls to non-overlay regions. - -'--local-store=lo:hi' - 'ld' usually checks that a final executable for SPU fits in the - address range 0 to 256k. This option may be used to change the - range. Disable the check entirely with '--local-store=0:0'. - -'--stack-analysis' - SPU local store space is limited. Over-allocation of stack space - unnecessarily limits space available for code and data, while - under-allocation results in runtime failures. If given this - option, 'ld' will provide an estimate of maximum stack usage. 'ld' - does this by examining symbols in code sections to determine the - extents of functions, and looking at function prologues for stack - adjusting instructions. A call-graph is created by looking for - relocations on branch instructions. The graph is then searched for - the maximum stack usage path. Note that this analysis does not - find calls made via function pointers, and does not handle - recursion and other cycles in the call graph. Stack usage may be - under-estimated if your code makes such calls. Also, stack usage - for dynamic allocation, e.g. alloca, will not be detected. If a - link map is requested, detailed information about each function's - stack usage and calls will be given. - -'--emit-stack-syms' - This option, if given along with '--stack-analysis' will result in - 'ld' emitting stack sizing symbols for each function. These take - the form '__stack_<function_name>' for global functions, and - '__stack_<number>_<function_name>' for static functions. - '<number>' is the section id in hex. The value of such symbols is - the stack requirement for the corresponding function. The symbol - size will be zero, type 'STT_NOTYPE', binding 'STB_LOCAL', and - section 'SHN_ABS'. - -4.11 'ld''s Support for Various TI COFF Versions -================================================ - -The '--format' switch allows selection of one of the various TI COFF -versions. The latest of this writing is 2; versions 0 and 1 are also -supported. The TI COFF versions also vary in header byte-order format; -'ld' will read any version or byte order, but the output header format -depends on the default specified by the specific target. - -4.12 'ld' and WIN32 (cygwin/mingw) -================================== - -This section describes some of the win32 specific 'ld' issues. See -*note Command Line Options: Options. for detailed description of the -command line options mentioned here. - -_import libraries_ - The standard Windows linker creates and uses so-called import - libraries, which contains information for linking to dll's. They - are regular static archives and are handled as any other static - archive. The cygwin and mingw ports of 'ld' have specific support - for creating such libraries provided with the '--out-implib' - command line option. - -_exporting DLL symbols_ - The cygwin/mingw 'ld' has several ways to export symbols for dll's. - - _using auto-export functionality_ - By default 'ld' exports symbols with the auto-export - functionality, which is controlled by the following command - line options: - - * -export-all-symbols [This is the default] - * -exclude-symbols - * -exclude-libs - - If, however, '--export-all-symbols' is not given explicitly on - the command line, then the default auto-export behavior will - be _disabled_ if either of the following are true: - - * A DEF file is used. - * Any symbol in any object file was marked with the - __declspec(dllexport) attribute. - - _using a DEF file_ - Another way of exporting symbols is using a DEF file. A DEF - file is an ASCII file containing definitions of symbols which - should be exported when a dll is created. Usually it is named - '<dll name>.def' and is added as any other object file to the - linker's command line. The file's name must end in '.def' or - '.DEF'. - - gcc -o <output> <objectfiles> <dll name>.def - - Using a DEF file turns off the normal auto-export behavior, - unless the '--export-all-symbols' option is also used. - - Here is an example of a DEF file for a shared library called - 'xyz.dll': - - LIBRARY "xyz.dll" BASE=0x20000000 - - EXPORTS - foo - bar - _bar = bar - another_foo = abc.dll.afoo - var1 DATA - - This example defines a DLL with a non-default base address and - five symbols in the export table. The third exported symbol - '_bar' is an alias for the second. The fourth symbol, - 'another_foo' is resolved by "forwarding" to another module - and treating it as an alias for 'afoo' exported from the DLL - 'abc.dll'. The final symbol 'var1' is declared to be a data - object. - - The optional 'LIBRARY <name>' command indicates the _internal_ - name of the output DLL. If '<name>' does not include a suffix, - the default library suffix, '.DLL' is appended. - - When the .DEF file is used to build an application, rather - than a library, the 'NAME <name>' command should be used - instead of 'LIBRARY'. If '<name>' does not include a suffix, - the default executable suffix, '.EXE' is appended. - - With either 'LIBRARY <name>' or 'NAME <name>' the optional - specification 'BASE = <number>' may be used to specify a - non-default base address for the image. - - If neither 'LIBRARY <name>' nor 'NAME <name>' is specified, or - they specify an empty string, the internal name is the same as - the filename specified on the command line. - - The complete specification of an export symbol is: - - EXPORTS - ( ( ( <name1> [ = <name2> ] ) - | ( <name1> = <module-name> . <external-name>)) - [ @ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] ) * - - Declares '<name1>' as an exported symbol from the DLL, or - declares '<name1>' as an exported alias for '<name2>'; or - declares '<name1>' as a "forward" alias for the symbol - '<external-name>' in the DLL '<module-name>'. Optionally, the - symbol may be exported by the specified ordinal '<integer>' - alias. - - The optional keywords that follow the declaration indicate: - - 'NONAME': Do not put the symbol name in the DLL's export - table. It will still be exported by its ordinal alias (either - the value specified by the .def specification or, otherwise, - the value assigned by the linker). The symbol name, however, - does remain visible in the import library (if any), unless - 'PRIVATE' is also specified. - - 'DATA': The symbol is a variable or object, rather than a - function. The import lib will export only an indirect - reference to 'foo' as the symbol '_imp__foo' (ie, 'foo' must - be resolved as '*_imp__foo'). - - 'CONSTANT': Like 'DATA', but put the undecorated 'foo' as well - as '_imp__foo' into the import library. Both refer to the - read-only import address table's pointer to the variable, not - to the variable itself. This can be dangerous. If the user - code fails to add the 'dllimport' attribute and also fails to - explicitly add the extra indirection that the use of the - attribute enforces, the application will behave unexpectedly. - - 'PRIVATE': Put the symbol in the DLL's export table, but do - not put it into the static import library used to resolve - imports at link time. The symbol can still be imported using - the 'LoadLibrary/GetProcAddress' API at runtime or by by using - the GNU ld extension of linking directly to the DLL without an - import library. - - See ld/deffilep.y in the binutils sources for the full - specification of other DEF file statements - - While linking a shared dll, 'ld' is able to create a DEF file - with the '--output-def <file>' command line option. - - _Using decorations_ - Another way of marking symbols for export is to modify the - source code itself, so that when building the DLL each symbol - to be exported is declared as: - - __declspec(dllexport) int a_variable - __declspec(dllexport) void a_function(int with_args) - - All such symbols will be exported from the DLL. If, however, - any of the object files in the DLL contain symbols decorated - in this way, then the normal auto-export behavior is disabled, - unless the '--export-all-symbols' option is also used. - - Note that object files that wish to access these symbols must - _not_ decorate them with dllexport. Instead, they should use - dllimport, instead: - - __declspec(dllimport) int a_variable - __declspec(dllimport) void a_function(int with_args) - - This complicates the structure of library header files, - because when included by the library itself the header must - declare the variables and functions as dllexport, but when - included by client code the header must declare them as - dllimport. There are a number of idioms that are typically - used to do this; often client code can omit the __declspec() - declaration completely. See '--enable-auto-import' and - 'automatic data imports' for more information. - -_automatic data imports_ - The standard Windows dll format supports data imports from dlls - only by adding special decorations (dllimport/dllexport), which let - the compiler produce specific assembler instructions to deal with - this issue. This increases the effort necessary to port existing - Un*x code to these platforms, especially for large c++ libraries - and applications. The auto-import feature, which was initially - provided by Paul Sokolovsky, allows one to omit the decorations to - achieve a behavior that conforms to that on POSIX/Un*x platforms. - This feature is enabled with the '--enable-auto-import' - command-line option, although it is enabled by default on - cygwin/mingw. The '--enable-auto-import' option itself now serves - mainly to suppress any warnings that are ordinarily emitted when - linked objects trigger the feature's use. - - auto-import of variables does not always work flawlessly without - additional assistance. Sometimes, you will see this message - - "variable '<var>' can't be auto-imported. Please read the - documentation for ld's '--enable-auto-import' for details." - - The '--enable-auto-import' documentation explains why this error - occurs, and several methods that can be used to overcome this - difficulty. One of these methods is the _runtime pseudo-relocs_ - feature, described below. - - For complex variables imported from DLLs (such as structs or - classes), object files typically contain a base address for the - variable and an offset (_addend_) within the variable-to specify a - particular field or public member, for instance. Unfortunately, - the runtime loader used in win32 environments is incapable of - fixing these references at runtime without the additional - information supplied by dllimport/dllexport decorations. The - standard auto-import feature described above is unable to resolve - these references. - - The '--enable-runtime-pseudo-relocs' switch allows these references - to be resolved without error, while leaving the task of adjusting - the references themselves (with their non-zero addends) to - specialized code provided by the runtime environment. Recent - versions of the cygwin and mingw environments and compilers provide - this runtime support; older versions do not. However, the support - is only necessary on the developer's platform; the compiled result - will run without error on an older system. - - '--enable-runtime-pseudo-relocs' is not the default; it must be - explicitly enabled as needed. - -_direct linking to a dll_ - The cygwin/mingw ports of 'ld' support the direct linking, - including data symbols, to a dll without the usage of any import - libraries. This is much faster and uses much less memory than does - the traditional import library method, especially when linking - large libraries or applications. When 'ld' creates an import lib, - each function or variable exported from the dll is stored in its - own bfd, even though a single bfd could contain many exports. The - overhead involved in storing, loading, and processing so many bfd's - is quite large, and explains the tremendous time, memory, and - storage needed to link against particularly large or complex - libraries when using import libs. - - Linking directly to a dll uses no extra command-line switches other - than '-L' and '-l', because 'ld' already searches for a number of - names to match each library. All that is needed from the - developer's perspective is an understanding of this search, in - order to force ld to select the dll instead of an import library. - - For instance, when ld is called with the argument '-lxxx' it will - attempt to find, in the first directory of its search path, - - libxxx.dll.a - xxx.dll.a - libxxx.a - xxx.lib - cygxxx.dll (*) - libxxx.dll - xxx.dll - - before moving on to the next directory in the search path. - - (*) Actually, this is not 'cygxxx.dll' but in fact is - '<prefix>xxx.dll', where '<prefix>' is set by the 'ld' option - '--dll-search-prefix=<prefix>'. In the case of cygwin, the - standard gcc spec file includes '--dll-search-prefix=cyg', so in - effect we actually search for 'cygxxx.dll'. - - Other win32-based unix environments, such as mingw or pw32, may use - other '<prefix>'es, although at present only cygwin makes use of - this feature. It was originally intended to help avoid name - conflicts among dll's built for the various win32/un*x - environments, so that (for example) two versions of a zlib dll - could coexist on the same machine. - - The generic cygwin/mingw path layout uses a 'bin' directory for - applications and dll's and a 'lib' directory for the import - libraries (using cygwin nomenclature): - - bin/ - cygxxx.dll - lib/ - libxxx.dll.a (in case of dll's) - libxxx.a (in case of static archive) - - Linking directly to a dll without using the import library can be - done two ways: - - 1. Use the dll directly by adding the 'bin' path to the link line - gcc -Wl,-verbose -o a.exe -L../bin/ -lxxx - - However, as the dll's often have version numbers appended to their - names ('cygncurses-5.dll') this will often fail, unless one - specifies '-L../bin -lncurses-5' to include the version. Import - libs are generally not versioned, and do not have this difficulty. - - 2. Create a symbolic link from the dll to a file in the 'lib' - directory according to the above mentioned search pattern. This - should be used to avoid unwanted changes in the tools needed for - making the app/dll. - - ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a] - - Then you can link without any make environment changes. - - gcc -Wl,-verbose -o a.exe -L../lib/ -lxxx - - This technique also avoids the version number problems, because the - following is perfectly legal - - bin/ - cygxxx-5.dll - lib/ - libxxx.dll.a -> ../bin/cygxxx-5.dll - - Linking directly to a dll without using an import lib will work - even when auto-import features are exercised, and even when - '--enable-runtime-pseudo-relocs' is used. - - Given the improvements in speed and memory usage, one might - justifiably wonder why import libraries are used at all. There are - three reasons: - - 1. Until recently, the link-directly-to-dll functionality did - _not_ work with auto-imported data. - - 2. Sometimes it is necessary to include pure static objects within - the import library (which otherwise contains only bfd's for - indirection symbols that point to the exports of a dll). Again, - the import lib for the cygwin kernel makes use of this ability, and - it is not possible to do this without an import lib. - - 3. Symbol aliases can only be resolved using an import lib. This - is critical when linking against OS-supplied dll's (eg, the win32 - API) in which symbols are usually exported as undecorated aliases - of their stdcall-decorated assembly names. - - So, import libs are not going away. But the ability to replace - true import libs with a simple symbolic link to (or a copy of) a - dll, in many cases, is a useful addition to the suite of tools - binutils makes available to the win32 developer. Given the massive - improvements in memory requirements during linking, storage - requirements, and linking speed, we expect that many developers - will soon begin to use this feature whenever possible. - -_symbol aliasing_ - _adding additional names_ - Sometimes, it is useful to export symbols with additional - names. A symbol 'foo' will be exported as 'foo', but it can - also be exported as '_foo' by using special directives in the - DEF file when creating the dll. This will affect also the - optional created import library. Consider the following DEF - file: - - LIBRARY "xyz.dll" BASE=0x61000000 - - EXPORTS - foo - _foo = foo - - The line '_foo = foo' maps the symbol 'foo' to '_foo'. - - Another method for creating a symbol alias is to create it in - the source code using the "weak" attribute: - - void foo () { /* Do something. */; } - void _foo () __attribute__ ((weak, alias ("foo"))); - - See the gcc manual for more information about attributes and - weak symbols. - - _renaming symbols_ - Sometimes it is useful to rename exports. For instance, the - cygwin kernel does this regularly. A symbol '_foo' can be - exported as 'foo' but not as '_foo' by using special - directives in the DEF file. (This will also affect the import - library, if it is created). In the following example: - - LIBRARY "xyz.dll" BASE=0x61000000 - - EXPORTS - _foo = foo - - The line '_foo = foo' maps the exported symbol 'foo' to - '_foo'. - - Note: using a DEF file disables the default auto-export behavior, - unless the '--export-all-symbols' command line option is used. If, - however, you are trying to rename symbols, then you should list - _all_ desired exports in the DEF file, including the symbols that - are not being renamed, and do _not_ use the '--export-all-symbols' - option. If you list only the renamed symbols in the DEF file, and - use '--export-all-symbols' to handle the other symbols, then the - both the new names _and_ the original names for the renamed symbols - will be exported. In effect, you'd be aliasing those symbols, not - renaming them, which is probably not what you wanted. - -_weak externals_ - The Windows object format, PE, specifies a form of weak symbols - called weak externals. When a weak symbol is linked and the symbol - is not defined, the weak symbol becomes an alias for some other - symbol. There are three variants of weak externals: - * Definition is searched for in objects and libraries, - historically called lazy externals. - * Definition is searched for only in other objects, not in - libraries. This form is not presently implemented. - * No search; the symbol is an alias. This form is not presently - implemented. - As a GNU extension, weak symbols that do not specify an alternate - symbol are supported. If the symbol is undefined when linking, the - symbol uses a default value. - -4.13 'ld' and Xtensa Processors -=============================== - -The default 'ld' behavior for Xtensa processors is to interpret -'SECTIONS' commands so that lists of explicitly named sections in a -specification with a wildcard file will be interleaved when necessary to -keep literal pools within the range of PC-relative load offsets. For -example, with the command: - - SECTIONS - { - .text : { - *(.literal .text) - } - } - -'ld' may interleave some of the '.literal' and '.text' sections from -different object files to ensure that the literal pools are within the -range of PC-relative load offsets. A valid interleaving might place the -'.literal' sections from an initial group of files followed by the -'.text' sections of that group of files. Then, the '.literal' sections -from the rest of the files and the '.text' sections from the rest of the -files would follow. - - Relaxation is enabled by default for the Xtensa version of 'ld' and -provides two important link-time optimizations. The first optimization -is to combine identical literal values to reduce code size. A redundant -literal will be removed and all the 'L32R' instructions that use it will -be changed to reference an identical literal, as long as the location of -the replacement literal is within the offset range of all the 'L32R' -instructions. The second optimization is to remove unnecessary overhead -from assembler-generated "longcall" sequences of 'L32R'/'CALLXN' when -the target functions are within range of direct 'CALLN' instructions. - - For each of these cases where an indirect call sequence can be -optimized to a direct call, the linker will change the 'CALLXN' -instruction to a 'CALLN' instruction, remove the 'L32R' instruction, and -remove the literal referenced by the 'L32R' instruction if it is not -used for anything else. Removing the 'L32R' instruction always reduces -code size but can potentially hurt performance by changing the alignment -of subsequent branch targets. By default, the linker will always -preserve alignments, either by switching some instructions between -24-bit encodings and the equivalent density instructions or by inserting -a no-op in place of the 'L32R' instruction that was removed. If code -size is more important than performance, the '--size-opt' option can be -used to prevent the linker from widening density instructions or -inserting no-ops, except in a few cases where no-ops are required for -correctness. - - The following Xtensa-specific command-line options can be used to -control the linker: - -'--no-relax' - Since the Xtensa version of 'ld' enables the '--relax' option by - default, the '--no-relax' option is provided to disable relaxation. - -'--size-opt' - When optimizing indirect calls to direct calls, optimize for code - size more than performance. With this option, the linker will not - insert no-ops or widen density instructions to preserve branch - target alignment. There may still be some cases where no-ops are - required to preserve the correctness of the code. - -5 BFD -***** - -The linker accesses object and archive files using the BFD libraries. -These libraries allow the linker to use the same routines to operate on -object files whatever the object file format. A different object file -format can be supported simply by creating a new BFD back end and adding -it to the library. To conserve runtime memory, however, the linker and -associated tools are usually configured to support only a subset of the -object file formats available. You can use 'objdump -i' (*note objdump: -(binutils.info)objdump.) to list all the formats available for your -configuration. - - As with most implementations, BFD is a compromise between several -conflicting requirements. The major factor influencing BFD design was -efficiency: any time used converting between formats is time which would -not have been spent had BFD not been involved. This is partly offset by -abstraction payback; since BFD simplifies applications and back ends, -more time and care may be spent optimizing algorithms for a greater -speed. - - One minor artifact of the BFD solution which you should bear in mind -is the potential for information loss. There are two places where -useful information can be lost using the BFD mechanism: during -conversion and during output. *Note BFD information loss::. - -5.1 How It Works: An Outline of BFD -=================================== - -When an object file is opened, BFD subroutines automatically determine -the format of the input object file. They then build a descriptor in -memory with pointers to routines that will be used to access elements of -the object file's data structures. - - As different information from the object files is required, BFD reads -from different sections of the file and processes them. For example, a -very common operation for the linker is processing symbol tables. Each -BFD back end provides a routine for converting between the object file's -representation of symbols and an internal canonical format. When the -linker asks for the symbol table of an object file, it calls through a -memory pointer to the routine from the relevant BFD back end which reads -and converts the table into a canonical form. The linker then operates -upon the canonical form. When the link is finished and the linker -writes the output file's symbol table, another BFD back end routine is -called to take the newly created symbol table and convert it into the -chosen output format. - -5.1.1 Information Loss ----------------------- - -_Information can be lost during output._ The output formats supported -by BFD do not provide identical facilities, and information which can be -described in one form has nowhere to go in another format. One example -of this is alignment information in 'b.out'. There is nowhere in an -'a.out' format file to store alignment information on the contained -data, so when a file is linked from 'b.out' and an 'a.out' image is -produced, alignment information will not propagate to the output file. -(The linker will still use the alignment information internally, so the -link is performed correctly). - - Another example is COFF section names. COFF files may contain an -unlimited number of sections, each one with a textual section name. If -the target of the link is a format which does not have many sections -(e.g., 'a.out') or has sections without names (e.g., the Oasys format), -the link cannot be done simply. You can circumvent this problem by -describing the desired input-to-output section mapping with the linker -command language. - - _Information can be lost during canonicalization._ The BFD internal -canonical form of the external formats is not exhaustive; there are -structures in input formats for which there is no direct representation -internally. This means that the BFD back ends cannot maintain all -possible data richness through the transformation between external to -internal and back to external formats. - - This limitation is only a problem when an application reads one -format and writes another. Each BFD back end is responsible for -maintaining as much data as possible, and the internal BFD canonical -form has structures which are opaque to the BFD core, and exported only -to the back ends. When a file is read in one format, the canonical form -is generated for BFD and the application. At the same time, the back -end saves away any information which may otherwise be lost. If the data -is then written back in the same format, the back end routine will be -able to use the canonical form provided by the BFD core as well as the -information it prepared earlier. Since there is a great deal of -commonality between back ends, there is no information lost when linking -or copying big endian COFF to little endian COFF, or 'a.out' to 'b.out'. -When a mixture of formats is linked, the information is only lost from -the files whose format differs from the destination. - -5.1.2 The BFD canonical object-file format ------------------------------------------- - -The greatest potential for loss of information occurs when there is the -least overlap between the information provided by the source format, -that stored by the canonical format, and that needed by the destination -format. A brief description of the canonical form may help you -understand which kinds of data you can count on preserving across -conversions. - -_files_ - Information stored on a per-file basis includes target machine - architecture, particular implementation format type, a demand - pageable bit, and a write protected bit. Information like Unix - magic numbers is not stored here--only the magic numbers' meaning, - so a 'ZMAGIC' file would have both the demand pageable bit and the - write protected text bit set. The byte order of the target is - stored on a per-file basis, so that big- and little-endian object - files may be used with one another. - -_sections_ - Each section in the input file contains the name of the section, - the section's original address in the object file, size and - alignment information, various flags, and pointers into other BFD - data structures. - -_symbols_ - Each symbol contains a pointer to the information for the object - file which originally defined it, its name, its value, and various - flag bits. When a BFD back end reads in a symbol table, it - relocates all symbols to make them relative to the base of the - section where they were defined. Doing this ensures that each - symbol points to its containing section. Each symbol also has a - varying amount of hidden private data for the BFD back end. Since - the symbol points to the original file, the private data format for - that symbol is accessible. 'ld' can operate on a collection of - symbols of wildly different formats without problems. - - Normal global and simple local symbols are maintained on output, so - an output file (no matter its format) will retain symbols pointing - to functions and to global, static, and common variables. Some - symbol information is not worth retaining; in 'a.out', type - information is stored in the symbol table as long symbol names. - This information would be useless to most COFF debuggers; the - linker has command line switches to allow users to throw it away. - - There is one word of type information within the symbol, so if the - format supports symbol type information within symbols (for - example, COFF, IEEE, Oasys) and the type is simple enough to fit - within one word (nearly everything but aggregates), the information - will be preserved. - -_relocation level_ - Each canonical BFD relocation record contains a pointer to the - symbol to relocate to, the offset of the data to relocate, the - section the data is in, and a pointer to a relocation type - descriptor. Relocation is performed by passing messages through - the relocation type descriptor and the symbol pointer. Therefore, - relocations can be performed on output data using a relocation - method that is only available in one of the input formats. For - instance, Oasys provides a byte relocation format. A relocation - record requesting this relocation type would point indirectly to a - routine to perform this, so the relocation may be performed on a - byte being written to a 68k COFF file, even though 68k COFF has no - such relocation type. - -_line numbers_ - Object formats can contain, for debugging purposes, some form of - mapping between symbols, source line numbers, and addresses in the - output file. These addresses have to be relocated along with the - symbol information. Each symbol with an associated list of line - number records points to the first record of the list. The head of - a line number list consists of a pointer to the symbol, which - allows finding out the address of the function whose line number is - being described. The rest of the list is made up of pairs: offsets - into the section and line numbers. Any format which can simply - derive this information can pass it successfully between formats - (COFF, IEEE and Oasys). - -6 Reporting Bugs -**************** - -Your bug reports play an essential role in making 'ld' reliable. - - 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 'ld' work -better. Bug reports are your contribution to the maintenance of 'ld'. - - In order for a bug report to serve its purpose, you must include the -information that enables us to fix the bug. - -6.1 Have You Found a Bug? -========================= - -If you are not sure whether you have found a bug, here are some -guidelines: - - * If the linker gets a fatal signal, for any input whatever, that is - a 'ld' bug. Reliable linkers never crash. - - * If 'ld' produces an error message for valid input, that is a bug. - - * If 'ld' does not produce an error message for invalid input, that - may be a bug. In the general case, the linker can not verify that - object files are correct. - - * If you are an experienced user of linkers, your suggestions for - improvement of 'ld' are welcome in any case. - -6.2 How to Report Bugs -====================== - -A number of companies and individuals offer support for GNU products. -If you obtained 'ld' from a support organization, we recommend you -contact that organization first. - - You can find contact information for many support companies and -individuals in the file 'etc/SERVICE' in the GNU Emacs distribution. - - The fundamental principle of reporting bugs usefully is this: *report -all the facts*. If you are not sure whether to state a fact or leave it -out, state it! - - Often people omit facts because they think they know what causes the -problem and assume that some details do not matter. Thus, you might -assume that the name of a symbol you use in an example does not matter. -Well, probably it does not, but one cannot be sure. Perhaps the bug is -a stray memory reference which happens to fetch from the location where -that name is stored in memory; perhaps, if the name were different, the -contents of that location would fool the linker into doing the right -thing despite the bug. Play it safe and give a specific, complete -example. That is the easiest thing for you to do, and the most helpful. - - 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. - - Sometimes people give a few sketchy facts and ask, "Does this ring a -bell?" 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. - - To enable us to fix the bug, you should include all these things: - - * The version of 'ld'. 'ld' announces it if you start it with the - '--version' argument. - - Without this, we will not know whether there is any point in - looking for the bug in the current version of 'ld'. - - * Any patches you may have applied to the 'ld' source, including any - patches made to the 'BFD' library. - - * The type of machine you are using, and the operating system name - and version number. - - * What compiler (and its version) was used to compile 'ld'--e.g. - "'gcc-2.7'". - - * The command arguments you gave the linker to link your example and - observe the bug. To guarantee you will not omit something - important, list them all. A copy of the Makefile (or the output - from make) is sufficient. - - If we were to try to guess the arguments, we would probably guess - wrong and then we might not encounter the bug. - - * A complete input file, or set of input files, that will reproduce - the bug. It is generally most helpful to send the actual object - files provided that they are reasonably small. Say no more than - 10K. For bigger files you can either make them available by FTP or - HTTP or else state that you are willing to send the object file(s) - to whomever requests them. (Note - your email will be going to a - mailing list, so we do not want to clog it up with large - attachments). But small attachments are best. - - If the source files were assembled using 'gas' or compiled using - 'gcc', then it may be OK to send the source files rather than the - object files. In this case, be sure to say exactly what version of - 'gas' or 'gcc' was used to produce the object files. Also say how - 'gas' or 'gcc' were configured. - - * A description of what behavior you observe that you believe is - incorrect. For example, "It gets a fatal signal." - - Of course, if the bug is that 'ld' gets a fatal signal, then we - will certainly notice it. But if the bug is incorrect output, we - might not notice unless it is glaringly wrong. You might as well - not give us a chance to make a mistake. - - 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 'ld' is out of sync, or you have encountered - a bug in the C library on your system. (This has happened!) Your - copy might crash and ours would not. If you told us to expect a - crash, then when ours fails to crash, we would know that the bug - was not happening for us. If you had not told us to expect a - crash, then we would not be able to draw any conclusion from our - observations. - - * If you wish to suggest changes to the 'ld' source, send us context - diffs, as generated by 'diff' with the '-u', '-c', or '-p' option. - Always send diffs from the old file to the new file. If you even - discuss something in the 'ld' source, refer to it by context, not - by line number. - - The line numbers in our development sources will not match those in - your sources. Your line numbers would convey no useful information - to us. - - Here are some things that are not necessary: - - * A description of the envelope of the bug. - - 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. - - 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. - - Of course, if you can find a simpler example to report _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. - - 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. - - * A patch for the bug. - - 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. - - Sometimes with a program as complicated as 'ld' it is very hard to - construct an example that will make the program follow a certain - path through the code. If you do not send us the example, we will - not be able to construct one, so we will not be able to verify that - the bug is fixed. - - 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. - - * A guess about what the bug is or what it depends on. - - Such guesses are usually wrong. Even we cannot guess right about - such things without first using the debugger to find the facts. - -Appendix A MRI Compatible Script Files -************************************** - -To aid users making the transition to GNU 'ld' from the MRI linker, 'ld' -can use MRI compatible linker scripts as an alternative to the more -general-purpose linker scripting language described in *note Scripts::. -MRI compatible linker scripts have a much simpler command set than the -scripting language otherwise used with 'ld'. GNU 'ld' supports the most -commonly used MRI linker commands; these commands are described here. - - In general, MRI scripts aren't of much use with the 'a.out' object -file format, since it only has three sections and MRI scripts lack some -features to make use of them. - - You can specify a file containing an MRI-compatible script using the -'-c' command-line option. - - Each command in an MRI-compatible script occupies its own line; each -command line starts with the keyword that identifies the command (though -blank lines are also allowed for punctuation). If a line of an -MRI-compatible script begins with an unrecognized keyword, 'ld' issues a -warning message, but continues processing the script. - - Lines beginning with '*' are comments. - - You can write these commands using all upper-case letters, or all -lower case; for example, 'chip' is the same as 'CHIP'. The following -list shows only the upper-case form of each command. - -'ABSOLUTE SECNAME' -'ABSOLUTE SECNAME, SECNAME, ... SECNAME' - Normally, 'ld' includes in the output file all sections from all - the input files. However, in an MRI-compatible script, you can use - the 'ABSOLUTE' command to restrict the sections that will be - present in your output program. If the 'ABSOLUTE' command is used - at all in a script, then only the sections named explicitly in - 'ABSOLUTE' commands will appear in the linker output. You can - still use other input sections (whatever you select on the command - line, or using 'LOAD') to resolve addresses in the output file. - -'ALIAS OUT-SECNAME, IN-SECNAME' - Use this command to place the data from input section IN-SECNAME in - a section called OUT-SECNAME in the linker output file. - - IN-SECNAME may be an integer. - -'ALIGN SECNAME = EXPRESSION' - Align the section called SECNAME to EXPRESSION. The EXPRESSION - should be a power of two. - -'BASE EXPRESSION' - Use the value of EXPRESSION as the lowest address (other than - absolute addresses) in the output file. - -'CHIP EXPRESSION' -'CHIP EXPRESSION, EXPRESSION' - This command does nothing; it is accepted only for compatibility. - -'END' - This command does nothing whatever; it's only accepted for - compatibility. - -'FORMAT OUTPUT-FORMAT' - Similar to the 'OUTPUT_FORMAT' command in the more general linker - language, but restricted to one of these output formats: - - 1. S-records, if OUTPUT-FORMAT is 'S' - - 2. IEEE, if OUTPUT-FORMAT is 'IEEE' - - 3. COFF (the 'coff-m68k' variant in BFD), if OUTPUT-FORMAT is - 'COFF' - -'LIST ANYTHING...' - Print (to the standard output file) a link map, as produced by the - 'ld' command-line option '-M'. - - The keyword 'LIST' may be followed by anything on the same line, - with no change in its effect. - -'LOAD FILENAME' -'LOAD FILENAME, FILENAME, ... FILENAME' - Include one or more object file FILENAME in the link; this has the - same effect as specifying FILENAME directly on the 'ld' command - line. - -'NAME OUTPUT-NAME' - OUTPUT-NAME is the name for the program produced by 'ld'; the - MRI-compatible command 'NAME' is equivalent to the command-line - option '-o' or the general script language command 'OUTPUT'. - -'ORDER SECNAME, SECNAME, ... SECNAME' -'ORDER SECNAME SECNAME SECNAME' - Normally, 'ld' orders the sections in its output file in the order - in which they first appear in the input files. In an - MRI-compatible script, you can override this ordering with the - 'ORDER' command. The sections you list with 'ORDER' will appear - first in your output file, in the order specified. - -'PUBLIC NAME=EXPRESSION' -'PUBLIC NAME,EXPRESSION' -'PUBLIC NAME EXPRESSION' - Supply a value (EXPRESSION) for external symbol NAME used in the - linker input files. - -'SECT SECNAME, EXPRESSION' -'SECT SECNAME=EXPRESSION' -'SECT SECNAME EXPRESSION' - You can use any of these three forms of the 'SECT' command to - specify the start address (EXPRESSION) for section SECNAME. If you - have more than one 'SECT' statement for the same SECNAME, only the - _first_ sets the start address. - -Appendix B GNU Free Documentation License -***************************************** - - Version 1.1, March 2000 - - Copyright (C) 2000, 2003 Free Software Foundation, Inc. - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA - - Everyone is permitted to copy and distribute verbatim copies - of this license document, but changing it is not allowed. - - 0. PREAMBLE - - The purpose of this License is to make a manual, textbook, or other - written document "free" in the sense of freedom: to assure everyone - the effective freedom to copy and redistribute it, with or without - modifying it, either commercially or noncommercially. Secondarily, - this License preserves for the author and publisher a way to get - credit for their work, while not being considered responsible for - modifications made by others. - - This License is a kind of "copyleft", which means that derivative - works of the document must themselves be free in the same sense. - It complements the GNU General Public License, which is a copyleft - license designed for free software. - - 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. - - - 1. APPLICABILITY AND DEFINITIONS - - This License applies to any manual or other work that contains a - notice placed by the copyright holder saying it can be distributed - under the terms of this License. The "Document", below, refers to - any such manual or work. Any member of the public is a licensee, - and is addressed as "you." - - A "Modified Version" of the Document means any work containing the - Document or a portion of it, either copied verbatim, or with - modifications and/or translated into another language. - - A "Secondary Section" is a named appendix or a front-matter section - of the Document that deals exclusively with the relationship of the - publishers or authors of the Document to the Document's overall - subject (or to related matters) and contains nothing that could - fall directly within that overall subject. (For example, if the - Document is in part a textbook of mathematics, a Secondary Section - may not explain any mathematics.) The relationship could be a - matter of historical connection with the subject or with related - matters, or of legal, commercial, philosophical, ethical or - political position regarding them. - - The "Invariant Sections" are certain Secondary Sections whose - titles are designated, as being those of Invariant Sections, in the - notice that says that the Document is released under this License. - - The "Cover Texts" are certain short passages of text that are - listed, as Front-Cover Texts or Back-Cover Texts, in the notice - that says that the Document is released under this License. - - A "Transparent" copy of the Document means a machine-readable copy, - represented in a format whose specification is available to the - general public, whose contents can be viewed and edited directly - and straightforwardly with generic text editors or (for images - composed of pixels) generic paint programs or (for drawings) some - widely available drawing editor, and that is suitable for input to - text formatters or for automatic translation to a variety of - formats suitable for input to text formatters. A copy made in an - otherwise Transparent file format whose markup has been designed to - thwart or discourage subsequent modification by readers is not - Transparent. A copy that is not "Transparent" is called "Opaque." - - 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. - - The "Title Page" means, for a printed book, the title page itself, - plus such following pages as are needed to hold, legibly, the - material this License requires to appear in the title page. For - works in formats which do not have any title page as such, "Title - Page" means the text near the most prominent appearance of the - work's title, preceding the beginning of the body of the text. - - 2. VERBATIM COPYING - - 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. - - You may also lend copies, under the same conditions stated above, - and you may publicly display copies. - - 3. COPYING IN QUANTITY - - 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. - - 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. - - 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. - - 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. - - 4. MODIFICATIONS - - 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: - - A. Use in the Title Page (and on the covers, if any) a title - distinct from that of the Document, and from those of previous - versions (which should, if there were any, be listed in the History - section of the Document). You may use the same title as a previous - version if the original publisher of that version gives permission. - B. List on the Title Page, as authors, one or more persons or - entities responsible for authorship of the modifications in the - Modified Version, together with at least five of the principal - authors of the Document (all of its principal authors, if it has - less than five). - C. State on the Title page the name of the publisher of the - Modified Version, as the publisher. - D. Preserve all the copyright notices of the Document. - E. Add an appropriate copyright notice for your modifications - adjacent to the other copyright notices. - F. Include, immediately after the copyright notices, a license - notice giving the public permission to use the Modified Version - under the terms of this License, in the form shown in the Addendum - below. - G. Preserve in that license notice the full lists of Invariant - Sections and required Cover Texts given in the Document's license - notice. - H. Include an unaltered copy of this License. - I. Preserve the section entitled "History", and its title, and add - to it an item stating at least the title, year, new authors, and - publisher of the Modified Version as given on the Title Page. If - there is no section entitled "History" in the Document, create one - stating the title, year, authors, and publisher of the Document as - given on its Title Page, then add an item describing the Modified - Version as stated in the previous sentence. - J. Preserve the network location, if any, given in the Document for - public access to a Transparent copy of the Document, and likewise - the network locations given in the Document for previous versions - it was based on. These may be placed in the "History" section. - You may omit a network location for a work that was published at - least four years before the Document itself, or if the original - publisher of the version it refers to gives permission. - K. In any section entitled "Acknowledgements" or "Dedications", - preserve the section's title, and preserve in the section all the - substance and tone of each of the contributor acknowledgements - and/or dedications given therein. - L. Preserve all the Invariant Sections of the Document, unaltered - in their text and in their titles. Section numbers or the - equivalent are not considered part of the section titles. - M. Delete any section entitled "Endorsements." Such a section may - not be included in the Modified Version. - N. Do not retitle any existing section as "Endorsements" or to - conflict in title with any Invariant Section. - - 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. - - You may add a section entitled "Endorsements", provided it contains - nothing but endorsements of your Modified Version by various - parties-for example, statements of peer review or that the text has - been approved by an organization as the authoritative definition of - a standard. - - 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. - - 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. - - 5. COMBINING DOCUMENTS - - 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. - - 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. - - In the combination, you must combine any sections entitled - "History" in the various original documents, forming one section - entitled "History"; likewise combine any sections entitled - "Acknowledgements", and any sections entitled "Dedications." You - must delete all sections entitled "Endorsements." - - 6. COLLECTIONS OF DOCUMENTS - - 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. - - 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. - - 7. AGGREGATION WITH INDEPENDENT WORKS - - A compilation of the Document or its derivatives with other - separate and independent documents or works, in or on a volume of a - storage or distribution medium, does not as a whole count as a - Modified Version of the Document, provided no compilation copyright - is claimed for the compilation. Such a compilation is called an - "aggregate", and this License does not apply to the other - self-contained works thus compiled with the Document, on account of - their being thus compiled, if they are not themselves derivative - works of the Document. - - 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. - - 8. TRANSLATION - - 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. - - 9. TERMINATION - - 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. - - 10. FUTURE REVISIONS OF THIS LICENSE - - 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/. - - Each version of the License is given a distinguishing version - number. If the Document specifies that a particular numbered - version of this License "or any later version" applies to it, you - have the option of following the terms and conditions either of - that specified version or of any later version that has been - published (not as a draft) by the Free Software Foundation. If the - Document does not specify a version number of this License, you may - choose any version ever published (not as a draft) by the Free - Software Foundation. - -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: - - 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." - - If you have no Invariant Sections, write "with no Invariant Sections" -instead of saying which ones are invariant. If you have no Front-Cover -Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being -LIST"; likewise for Back-Cover Texts. - - 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. - -LD Index -******** - -* Menu: - -* ": Symbols. (line 3620) -* -(: Options. (line 756) -* --accept-unknown-input-arch: Options. (line 774) -* --add-needed: Options. (line 796) -* --add-stdcall-alias: Options. (line 1532) -* --allow-multiple-definition: Options. (line 1004) -* --allow-shlib-undefined: Options. (line 1010) -* --architecture=ARCH: Options. (line 227) -* --as-needed: Options. (line 784) -* --auxiliary: Options. (line 328) -* --bank-window: Options. (line 1867) -* --base-file: Options. (line 1537) -* --be8: ARM. (line 4205) -* --bss-plt: PowerPC ELF32. (line 4376) -* --check-sections: Options. (line 877) -* --cref: Options. (line 887) -* --default-imported-symver: Options. (line 1038) -* --default-script=SCRIPT: Options. (line 601) -* --default-symver: Options. (line 1034) -* --defsym SYMBOL=EXP: Options. (line 915) -* --demangle[=STYLE]: Options. (line 928) -* --disable-auto-image-base: Options. (line 1682) -* --disable-auto-import: Options. (line 1810) -* --disable-new-dtags: Options. (line 1479) -* --disable-runtime-pseudo-reloc: Options. (line 1823) -* --disable-stdcall-fixup: Options. (line 1547) -* --discard-all: Options. (line 647) -* --discard-locals: Options. (line 651) -* --dll: Options. (line 1542) -* --dll-search-prefix: Options. (line 1688) -* --dotsyms: PowerPC64 ELF64. (line 4446) -* --dynamic-linker FILE: Options. (line 941) -* --dynamic-list-cpp-new: Options. (line 869) -* --dynamic-list-cpp-typeinfo: Options. (line 873) -* --dynamic-list-data: Options. (line 866) -* --dynamic-list=DYNAMIC-LIST-FILE: Options. (line 853) -* --eh-frame-hdr: Options. (line 1475) -* --emit-relocs: Options. (line 537) -* --emit-stack-syms: SPU ELF. (line 4541) -* --emit-stub-syms: PowerPC ELF32. (line 4407) -* --emit-stub-syms <1>: PowerPC64 ELF64. (line 4442) -* --emit-stub-syms <2>: SPU ELF. (line 4510) -* --enable-auto-image-base: Options. (line 1674) -* --enable-auto-import: Options. (line 1697) -* --enable-extra-pe-debug: Options. (line 1828) -* --enable-new-dtags: Options. (line 1479) -* --enable-runtime-pseudo-reloc: Options. (line 1815) -* --enable-stdcall-fixup: Options. (line 1547) -* --entry=ENTRY: Options. (line 281) -* --error-unresolved-symbols: Options. (line 1428) -* --exclude-libs: Options. (line 291) -* --exclude-symbols: Options. (line 1588) -* --export-all-symbols: Options. (line 1564) -* --export-dynamic: Options. (line 302) -* --extra-overlay-stubs: SPU ELF. (line 4514) -* --fatal-warnings: Options. (line 947) -* --file-alignment: Options. (line 1594) -* --filter: Options. (line 349) -* --fix-v4bx: ARM. (line 4224) -* --force-dynamic: Options. (line 546) -* --force-exe-suffix: Options. (line 950) -* --format=FORMAT: Options. (line 238) -* --format=VERSION: TI COFF. (line 4554) -* --gc-sections: Options. (line 960) -* --gpsize: Options. (line 381) -* --hash-size=NUMBER: Options. (line 1488) -* --hash-style=STYLE: Options. (line 1496) -* --heap: Options. (line 1600) -* --help: Options. (line 977) -* --image-base: Options. (line 1607) -* --just-symbols=FILE: Options. (line 568) -* --kill-at: Options. (line 1616) -* --large-address-aware: Options. (line 1621) -* --library-path=DIR: Options. (line 440) -* --library=NAMESPEC: Options. (line 407) -* --local-store=lo:hi: SPU ELF. (line 4519) -* --major-image-version: Options. (line 1630) -* --major-os-version: Options. (line 1635) -* --major-subsystem-version: Options. (line 1639) -* --minor-image-version: Options. (line 1644) -* --minor-os-version: Options. (line 1649) -* --minor-subsystem-version: Options. (line 1653) -* --mri-script=MRI-CMDFILE: Options. (line 262) -* --multi-subspace: HPPA ELF32. (line 4285) -* --nmagic: Options. (line 506) -* --no-accept-unknown-input-arch: Options. (line 774) -* --no-add-needed: Options. (line 796) -* --no-allow-shlib-undefined: Options. (line 1010) -* --no-as-needed: Options. (line 784) -* --no-check-sections: Options. (line 877) -* --no-define-common: Options. (line 899) -* --no-demangle: Options. (line 928) -* --no-dotsyms: PowerPC64 ELF64. (line 4446) -* --no-enum-size-warning: ARM. (line 4275) -* --no-gc-sections: Options. (line 960) -* --no-keep-memory: Options. (line 989) -* --no-multi-toc: PowerPC64 ELF64. (line 4487) -* --no-omagic: Options. (line 520) -* --no-opd-optimize: PowerPC64 ELF64. (line 4461) -* --no-overlays: SPU ELF. (line 4504) -* --no-print-gc-sections: Options. (line 968) -* --no-relax: Xtensa. (line 5005) -* --no-tls-optimize: PowerPC ELF32. (line 4411) -* --no-tls-optimize <1>: PowerPC64 ELF64. (line 4456) -* --no-toc-optimize: PowerPC64 ELF64. (line 4473) -* --no-trampoline: Options. (line 1861) -* --no-undefined: Options. (line 996) -* --no-undefined-version: Options. (line 1029) -* --no-warn-mismatch: Options. (line 1042) -* --no-warn-search-mismatch: Options. (line 1051) -* --no-whole-archive: Options. (line 1055) -* --noinhibit-exec: Options. (line 1059) -* --non-overlapping-opd: PowerPC64 ELF64. (line 4467) -* --oformat: Options. (line 1070) -* --omagic: Options. (line 511) -* --out-implib: Options. (line 1666) -* --output-def: Options. (line 1658) -* --output=OUTPUT: Options. (line 526) -* --pic-executable: Options. (line 1083) -* --pic-veneer: M68HC11/68HC12. (line 4180) -* --plugin: SPU ELF. (line 4501) -* --print-gc-sections: Options. (line 968) -* --print-map: Options. (line 472) -* --reduce-memory-overheads: Options. (line 1502) -* --relax: Options. (line 1099) -* '--relax' on i960: i960. (line 4138) -* --relax on PowerPC: PowerPC ELF32. (line 4369) -* '--relax' on Xtensa: Xtensa. (line 4977) -* --relocatable: Options. (line 550) -* --script=SCRIPT: Options. (line 592) -* --sdata-got: PowerPC ELF32. (line 4393) -* --section-alignment: Options. (line 1833) -* --section-start SECTIONNAME=ORG: Options. (line 1265) -* --secure-plt: PowerPC ELF32. (line 4386) -* --sort-common: Options. (line 1212) -* --sort-section alignment: Options. (line 1222) -* --sort-section name: Options. (line 1218) -* --split-by-file: Options. (line 1226) -* --split-by-reloc: Options. (line 1231) -* --stack: Options. (line 1839) -* --stack-analysis: SPU ELF. (line 4524) -* --stats: Options. (line 1244) -* --strip-all: Options. (line 579) -* --strip-debug: Options. (line 583) -* --stub-group-size: PowerPC64 ELF64. (line 4419) -* --stub-group-size=N: HPPA ELF32. (line 4291) -* --subsystem: Options. (line 1846) -* --support-old-code: ARM. (line 4188) -* --sysroot: Options. (line 1248) -* --target-help: Options. (line 981) -* --target1-abs: ARM. (line 4209) -* --target1-rel: ARM. (line 4209) -* --target2=TYPE: ARM. (line 4214) -* --thumb-entry=ENTRY: ARM. (line 4199) -* --trace: Options. (line 588) -* --trace-symbol=SYMBOL: Options. (line 657) -* --traditional-format: Options. (line 1253) -* --undefined=SYMBOL: Options. (line 614) -* --unique[=SECTION]: Options. (line 632) -* --unresolved-symbols: Options. (line 1280) -* --use-blx: ARM. (line 4237) -* --verbose: Options. (line 1309) -* --version: Options. (line 641) -* --version-script=VERSION-SCRIPTFILE: Options. (line 1315) -* --vfp11-denorm-fix: ARM. (line 4246) -* --warn-common: Options. (line 1322) -* --warn-constructors: Options. (line 1390) -* --warn-multiple-gp: Options. (line 1395) -* --warn-once: Options. (line 1409) -* --warn-section-align: Options. (line 1413) -* --warn-shared-textrel: Options. (line 1420) -* --warn-unresolved-symbols: Options. (line 1423) -* --whole-archive: Options. (line 1432) -* --wrap: Options. (line 1446) -* -AARCH: Options. (line 226) -* -aKEYWORD: Options. (line 219) -* -assert KEYWORD: Options. (line 806) -* -b FORMAT: Options. (line 238) -* -Bdynamic: Options. (line 809) -* -Bgroup: Options. (line 819) -* -Bshareable: Options. (line 1204) -* -Bstatic: Options. (line 826) -* -Bsymbolic: Options. (line 840) -* -Bsymbolic-functions: Options. (line 847) -* -c MRI-CMDFILE: Options. (line 262) -* -call_shared: Options. (line 809) -* -d: Options. (line 272) -* -dc: Options. (line 272) -* -dn: Options. (line 826) -* -dp: Options. (line 272) -* -dT SCRIPT: Options. (line 601) -* -dy: Options. (line 809) -* -E: Options. (line 302) -* -e ENTRY: Options. (line 281) -* -EB: Options. (line 321) -* -EL: Options. (line 324) -* -f: Options. (line 328) -* -F: Options. (line 349) -* -fini: Options. (line 372) -* -g: Options. (line 378) -* -G: Options. (line 381) -* -hNAME: Options. (line 389) -* -i: Options. (line 398) -* -IFILE: Options. (line 941) -* -init: Options. (line 401) -* -LDIR: Options. (line 440) -* -lNAMESPEC: Options. (line 407) -* -M: Options. (line 472) -* -m EMULATION: Options. (line 462) -* -Map: Options. (line 985) -* -n: Options. (line 506) -* -N: Options. (line 511) -* -non_shared: Options. (line 826) -* -nostdlib: Options. (line 1065) -* -O LEVEL: Options. (line 532) -* -o OUTPUT: Options. (line 526) -* -pie: Options. (line 1083) -* -q: Options. (line 537) -* -qmagic: Options. (line 1093) -* -Qy: Options. (line 1096) -* -r: Options. (line 550) -* -R FILE: Options. (line 568) -* -rpath: Options. (line 1134) -* -rpath-link: Options. (line 1156) -* -s: Options. (line 579) -* -S: Options. (line 583) -* -shared: Options. (line 1204) -* -soname=NAME: Options. (line 389) -* -static: Options. (line 826) -* -t: Options. (line 588) -* -T SCRIPT: Options. (line 592) -* -Tbss ORG: Options. (line 1274) -* -Tdata ORG: Options. (line 1274) -* -Ttext ORG: Options. (line 1274) -* -u SYMBOL: Options. (line 614) -* -Ur: Options. (line 622) -* -v: Options. (line 641) -* -V: Options. (line 641) -* -x: Options. (line 647) -* -X: Options. (line 651) -* -Y PATH: Options. (line 666) -* -y SYMBOL: Options. (line 657) -* -z defs: Options. (line 996) -* -z KEYWORD: Options. (line 670) -* -z muldefs: Options. (line 1004) -* .: Location Counter. (line 3650) -* /DISCARD/: Output Section Discarding. - (line 2932) -* :PHDR: Output Section Phdr. - (line 3065) -* =FILLEXP: Output Section Fill. - (line 3079) -* >REGION: Output Section Region. - (line 3055) -* [COMMON]: Input Section Common. - (line 2744) -* 'ABSOLUTE' (MRI): MRI. (line 5391) -* absolute and relocatable symbols: Expression Section. (line 3828) -* absolute expressions: Expression Section. (line 3828) -* ABSOLUTE(EXP): Builtin Functions. (line 3864) -* ADDR(SECTION): Builtin Functions. (line 3871) -* address, section: Output Section Address. - (line 2522) -* 'ALIAS' (MRI): MRI. (line 5402) -* 'ALIGN' (MRI): MRI. (line 5408) -* align expression: Builtin Functions. (line 3890) -* align location counter: Builtin Functions. (line 3890) -* ALIGN(ALIGN): Builtin Functions. (line 3890) -* ALIGN(EXP,ALIGN): Builtin Functions. (line 3890) -* ALIGN(SECTION_ALIGN): Forced Output Alignment. - (line 3043) -* ALIGNOF(SECTION): Builtin Functions. (line 3915) -* allocating memory: MEMORY. (line 3196) -* architecture: Miscellaneous Commands. - (line 2254) -* architectures: Options. (line 226) -* archive files, from cmd line: Options. (line 407) -* archive search path in linker script: File Commands. (line 2158) -* arithmetic: Expressions. (line 3591) -* arithmetic operators: Operators. (line 3773) -* ARM interworking support: ARM. (line 4188) -* ASSERT: Miscellaneous Commands. - (line 2217) -* assertion in linker script: Miscellaneous Commands. - (line 2217) -* assignment in scripts: Assignments. (line 2262) -* AS_NEEDED(FILES): File Commands. (line 2138) -* AT(LMA): Output Section LMA. (line 2983) -* AT>LMA_REGION: Output Section LMA. (line 2983) -* automatic data imports: WIN32. (line 4723) -* back end: BFD. (line 5019) -* 'BASE' (MRI): MRI. (line 5412) -* BE8: ARM. (line 4205) -* BFD canonical format: Canonical format. (line 5114) -* BFD requirements: BFD. (line 5029) -* big-endian objects: Options. (line 321) -* binary input format: Options. (line 238) -* BLOCK(EXP): Builtin Functions. (line 3928) -* bug criteria: Bug Criteria. (line 5201) -* bug reports: Bug Reporting. (line 5219) -* bugs in 'ld': Reporting Bugs. (line 5188) -* BYTE(EXPRESSION): Output Section Data. - (line 2788) -* C++ constructors, arranging in link: Output Section Keywords. - (line 2857) -* 'CHIP' (MRI): MRI. (line 5416) -* COLLECT_NO_DEMANGLE: Environment. (line 1899) -* combining symbols, warnings on: Options. (line 1322) -* command files: Scripts. (line 1908) -* command line: Options. (line 130) -* common allocation: Options. (line 272) -* common allocation <1>: Options. (line 899) -* common allocation in linker script: Miscellaneous Commands. - (line 2228) -* common allocation in linker script <1>: Miscellaneous Commands. - (line 2233) -* common symbol placement: Input Section Common. - (line 2721) -* compatibility, MRI: Options. (line 262) -* constants in linker scripts: Constants. (line 3604) -* constructors: Options. (line 622) -* CONSTRUCTORS: Output Section Keywords. - (line 2857) -* constructors, arranging in link: Output Section Keywords. - (line 2857) -* crash of linker: Bug Criteria. (line 5204) -* CREATE_OBJECT_SYMBOLS: Output Section Keywords. - (line 2847) -* creating a DEF file: WIN32. (line 4691) -* cross reference table: Options. (line 887) -* cross references: Miscellaneous Commands. - (line 2238) -* current output location: Location Counter. (line 3650) -* data: Output Section Data. - (line 2788) -* DATA_SEGMENT_ALIGN(MAXPAGESIZE, COMMONPAGESIZE): Builtin Functions. - (line 3933) -* DATA_SEGMENT_END(EXP): Builtin Functions. (line 3954) -* DATA_SEGMENT_RELRO_END(OFFSET, EXP): Builtin Functions. (line 3960) -* dbx: Options. (line 1258) -* DEF files, creating: Options. (line 1658) -* default emulation: Environment. (line 1891) -* default input format: Environment. (line 1879) -* DEFINED(SYMBOL): Builtin Functions. (line 3971) -* deleting local symbols: Options. (line 647) -* demangling, default: Environment. (line 1899) -* demangling, from command line: Options. (line 928) -* direct linking to a dll: WIN32. (line 4771) -* discarding sections: Output Section Discarding. - (line 2917) -* discontinuous memory: MEMORY. (line 3196) -* DLLs, creating: Options. (line 1564) -* DLLs, creating <1>: Options. (line 1658) -* DLLs, creating <2>: Options. (line 1666) -* DLLs, linking to: Options. (line 1688) -* dot: Location Counter. (line 3650) -* dot inside sections: Location Counter. (line 3680) -* dot outside sections: Location Counter. (line 3710) -* dynamic linker, from command line: Options. (line 941) -* dynamic symbol table: Options. (line 302) -* ELF program headers: PHDRS. (line 3293) -* emulation: Options. (line 462) -* emulation, default: Environment. (line 1891) -* 'END' (MRI): MRI. (line 5420) -* endianness: Options. (line 321) -* entry point: Entry Point. (line 2076) -* entry point, from command line: Options. (line 281) -* entry point, thumb: ARM. (line 4199) -* ENTRY(SYMBOL): Entry Point. (line 2076) -* error on valid input: Bug Criteria. (line 5207) -* example of linker script: Simple Example. (line 2005) -* exporting DLL symbols: WIN32. (line 4576) -* expression evaluation order: Evaluation. (line 3794) -* expression sections: Expression Section. (line 3828) -* expression, absolute: Builtin Functions. (line 3864) -* expressions: Expressions. (line 3591) -* EXTERN: Miscellaneous Commands. - (line 2221) -* fatal signal: Bug Criteria. (line 5204) -* file name wildcard patterns: Input Section Wildcards. - (line 2616) -* FILEHDR: PHDRS. (line 3348) -* filename symbols: Output Section Keywords. - (line 2847) -* fill pattern, entire section: Output Section Fill. - (line 3079) -* FILL(EXPRESSION): Output Section Data. - (line 2821) -* finalization function: Options. (line 372) -* first input file: File Commands. (line 2166) -* first instruction: Entry Point. (line 2076) -* FIX_V4BX: ARM. (line 4224) -* FORCE_COMMON_ALLOCATION: Miscellaneous Commands. - (line 2228) -* forcing input section alignment: Forced Input Alignment. - (line 3048) -* forcing output section alignment: Forced Output Alignment. - (line 3043) -* forcing the creation of dynamic sections: Options. (line 546) -* 'FORMAT' (MRI): MRI. (line 5424) -* functions in expressions: Builtin Functions. (line 3860) -* garbage collection: Options. (line 960) -* garbage collection <1>: Options. (line 968) -* garbage collection <2>: Input Section Keep. (line 2750) -* generating optimized output: Options. (line 532) -* GNU linker: Overview. (line 100) -* GNUTARGET: Environment. (line 1879) -* GROUP(FILES): File Commands. (line 2131) -* grouping input files: File Commands. (line 2131) -* groups of archives: Options. (line 756) -* H8/300 support: H8/300. (line 4078) -* header size: Builtin Functions. (line 4035) -* heap size: Options. (line 1600) -* help: Options. (line 977) -* holes: Location Counter. (line 3656) -* holes, filling: Output Section Data. - (line 2821) -* HPPA multiple sub-space stubs: HPPA ELF32. (line 4285) -* HPPA stub grouping: HPPA ELF32. (line 4291) -* i960 support: i960. (line 4112) -* image base: Options. (line 1607) -* implicit linker scripts: Implicit Linker Scripts. - (line 4054) -* import libraries: WIN32. (line 4567) -* INCLUDE FILENAME: File Commands. (line 2096) -* including a linker script: File Commands. (line 2096) -* including an entire archive: Options. (line 1432) -* incremental link: Options. (line 398) -* INHIBIT_COMMON_ALLOCATION: Miscellaneous Commands. - (line 2233) -* initialization function: Options. (line 401) -* initialized data in ROM: Output Section LMA. (line 3003) -* input file format in linker script: Format Commands. (line 2204) -* input filename symbols: Output Section Keywords. - (line 2847) -* input files in linker scripts: File Commands. (line 2103) -* input files, displaying: Options. (line 588) -* input format: Options. (line 238) -* input format <1>: Options. (line 238) -* input object files in linker scripts: File Commands. (line 2103) -* input section alignment: Forced Input Alignment. - (line 3048) -* input section basics: Input Section Basics. - (line 2568) -* input section wildcards: Input Section Wildcards. - (line 2616) -* input sections: Input Section. (line 2558) -* INPUT(FILES): File Commands. (line 2103) -* integer notation: Constants. (line 3604) -* integer suffixes: Constants. (line 3610) -* internal object-file format: Canonical format. (line 5114) -* invalid input: Bug Criteria. (line 5209) -* K and M integer suffixes: Constants. (line 3610) -* KEEP: Input Section Keep. (line 2750) -* l =: MEMORY. (line 3256) -* lazy evaluation: Evaluation. (line 3794) -* 'ld' bugs, reporting: Bug Reporting. (line 5219) -* LDEMULATION: Environment. (line 1891) -* len =: MEMORY. (line 3256) -* LENGTH =: MEMORY. (line 3256) -* LENGTH(MEMORY): Builtin Functions. (line 3988) -* library search path in linker script: File Commands. (line 2158) -* link map: Options. (line 472) -* link-time runtime library search path: Options. (line 1156) -* linker crash: Bug Criteria. (line 5204) -* linker script concepts: Basic Script Concepts. - (line 1935) -* linker script example: Simple Example. (line 2005) -* linker script file commands: File Commands. (line 2093) -* linker script format: Script Format. (line 1985) -* linker script input object files: File Commands. (line 2103) -* linker script simple commands: Simple Commands. (line 2071) -* linker scripts: Scripts. (line 1908) -* 'LIST' (MRI): MRI. (line 5435) -* little-endian objects: Options. (line 324) -* 'LOAD' (MRI): MRI. (line 5442) -* load address: Output Section LMA. (line 2983) -* LOADADDR(SECTION): Builtin Functions. (line 3991) -* loading, preventing: Output Section Type. - (line 2969) -* local symbols, deleting: Options. (line 651) -* location counter: Location Counter. (line 3650) -* LONG(EXPRESSION): Output Section Data. - (line 2788) -* M and K integer suffixes: Constants. (line 3610) -* M68HC11 and 68HC12 support: M68HC11/68HC12. (line 4148) -* machine architecture: Miscellaneous Commands. - (line 2254) -* machine dependencies: Machine Dependent. (line 4071) -* mapping input sections to output sections: Input Section. (line 2558) -* MAX: Builtin Functions. (line 3995) -* MEMORY: MEMORY. (line 3196) -* memory region attributes: MEMORY. (line 3222) -* memory regions: MEMORY. (line 3196) -* memory regions and sections: Output Section Region. - (line 3055) -* memory usage: Options. (line 989) -* MIN: Builtin Functions. (line 3998) -* MRI compatibility: MRI. (line 5365) -* MSP430 extra sections: MSP430. (line 4343) -* 'NAME' (MRI): MRI. (line 5448) -* name, section: Output Section Name. - (line 2506) -* names: Symbols. (line 3620) -* naming the output file: Options. (line 526) -* NEXT(EXP): Builtin Functions. (line 4002) -* NMAGIC: Options. (line 506) -* NOCROSSREFS(SECTIONS): Miscellaneous Commands. - (line 2238) -* NOLOAD: Output Section Type. - (line 2969) -* not enough room for program headers: Builtin Functions. (line 4040) -* NO_ENUM_SIZE_WARNING: ARM. (line 4275) -* o =: MEMORY. (line 3251) -* objdump -i: BFD. (line 5019) -* object file management: BFD. (line 5019) -* object files: Options. (line 153) -* object formats available: BFD. (line 5019) -* object size: Options. (line 381) -* OMAGIC: Options. (line 511) -* OMAGIC <1>: Options. (line 520) -* opening object files: BFD outline. (line 5045) -* operators for arithmetic: Operators. (line 3773) -* options: Options. (line 130) -* 'ORDER' (MRI): MRI. (line 5453) -* org =: MEMORY. (line 3251) -* ORIGIN =: MEMORY. (line 3251) -* ORIGIN(MEMORY): Builtin Functions. (line 4008) -* orphan: Orphan Sections. (line 3635) -* output file after errors: Options. (line 1059) -* output file format in linker script: Format Commands. (line 2179) -* output file name in linker script: File Commands. (line 2148) -* output section alignment: Forced Output Alignment. - (line 3043) -* output section attributes: Output Section Attributes. - (line 2939) -* output section data: Output Section Data. - (line 2788) -* OUTPUT(FILENAME): File Commands. (line 2148) -* OUTPUT_ARCH(BFDARCH): Miscellaneous Commands. - (line 2254) -* OUTPUT_FORMAT(BFDNAME): Format Commands. (line 2179) -* OVERLAY: Overlay Description. - (line 3101) -* overlays: Overlay Description. - (line 3101) -* partial link: Options. (line 550) -* PHDRS: PHDRS. (line 3293) -* PHDRS <1>: PHDRS. (line 3348) -* PIC_VENEER: M68HC11/68HC12. (line 4180) -* position independent executables: Options. (line 1085) -* PowerPC ELF32 options: PowerPC ELF32. (line 4376) -* PowerPC GOT: PowerPC ELF32. (line 4393) -* PowerPC long branches: PowerPC ELF32. (line 4369) -* PowerPC PLT: PowerPC ELF32. (line 4376) -* PowerPC stub symbols: PowerPC ELF32. (line 4407) -* PowerPC TLS optimization: PowerPC ELF32. (line 4411) -* PowerPC64 dot symbols: PowerPC64 ELF64. (line 4446) -* PowerPC64 ELF64 options: PowerPC64 ELF64. (line 4419) -* PowerPC64 multi-TOC: PowerPC64 ELF64. (line 4487) -* PowerPC64 OPD optimization: PowerPC64 ELF64. (line 4461) -* PowerPC64 OPD spacing: PowerPC64 ELF64. (line 4467) -* PowerPC64 stub grouping: PowerPC64 ELF64. (line 4419) -* PowerPC64 stub symbols: PowerPC64 ELF64. (line 4442) -* PowerPC64 TLS optimization: PowerPC64 ELF64. (line 4456) -* PowerPC64 TOC optimization: PowerPC64 ELF64. (line 4473) -* precedence in expressions: Operators. (line 3773) -* prevent unnecessary loading: Output Section Type. - (line 2969) -* program headers: PHDRS. (line 3293) -* program headers and sections: Output Section Phdr. - (line 3065) -* program headers, not enough room: Builtin Functions. (line 4040) -* program segments: PHDRS. (line 3293) -* PROVIDE: PROVIDE. (line 2321) -* PROVIDE_HIDDEN: PROVIDE_HIDDEN. (line 2350) -* 'PUBLIC' (MRI): MRI. (line 5461) -* QUAD(EXPRESSION): Output Section Data. - (line 2788) -* quoted symbol names: Symbols. (line 3620) -* read-only text: Options. (line 506) -* read/write from cmd line: Options. (line 511) -* regions of memory: MEMORY. (line 3196) -* relative expressions: Expression Section. (line 3828) -* relaxing addressing modes: Options. (line 1099) -* relaxing on H8/300: H8/300. (line 4081) -* relaxing on i960: i960. (line 4138) -* relaxing on M68HC11: M68HC11/68HC12. (line 4155) -* relaxing on Xtensa: Xtensa. (line 4977) -* relocatable and absolute symbols: Expression Section. (line 3828) -* relocatable output: Options. (line 550) -* removing sections: Output Section Discarding. - (line 2917) -* reporting bugs in 'ld': Reporting Bugs. (line 5188) -* requirements for BFD: BFD. (line 5029) -* retain relocations in final executable: Options. (line 537) -* retaining specified symbols: Options. (line 1120) -* ROM initialized data: Output Section LMA. (line 3003) -* round up expression: Builtin Functions. (line 3890) -* round up location counter: Builtin Functions. (line 3890) -* runtime library name: Options. (line 389) -* runtime library search path: Options. (line 1134) -* runtime pseudo-relocation: WIN32. (line 4749) -* scaled integers: Constants. (line 3610) -* scommon section: Input Section Common. - (line 2735) -* script files: Options. (line 592) -* script files <1>: Options. (line 601) -* scripts: Scripts. (line 1908) -* search directory, from cmd line: Options. (line 440) -* search path in linker script: File Commands. (line 2158) -* SEARCH_DIR(PATH): File Commands. (line 2158) -* 'SECT' (MRI): MRI. (line 5467) -* section address: Output Section Address. - (line 2522) -* section address in expression: Builtin Functions. (line 3871) -* section alignment: Builtin Functions. (line 3915) -* section alignment, warnings on: Options. (line 1413) -* section data: Output Section Data. - (line 2788) -* section fill pattern: Output Section Fill. - (line 3079) -* section load address: Output Section LMA. (line 2983) -* section load address in expression: Builtin Functions. (line 3991) -* section name: Output Section Name. - (line 2506) -* section name wildcard patterns: Input Section Wildcards. - (line 2616) -* section size: Builtin Functions. (line 4019) -* section, assigning to memory region: Output Section Region. - (line 3055) -* section, assigning to program header: Output Section Phdr. - (line 3065) -* SECTIONS: SECTIONS. (line 2443) -* sections, discarding: Output Section Discarding. - (line 2917) -* segment origins, cmd line: Options. (line 1274) -* segments, ELF: PHDRS. (line 3293) -* SEGMENT_START(SEGMENT, DEFAULT): Builtin Functions. (line 4011) -* shared libraries: Options. (line 1206) -* SHORT(EXPRESSION): Output Section Data. - (line 2788) -* SIZEOF(SECTION): Builtin Functions. (line 4019) -* SIZEOF_HEADERS: Builtin Functions. (line 4035) -* small common symbols: Input Section Common. - (line 2735) -* SORT: Input Section Wildcards. - (line 2665) -* SORT_BY_ALIGNMENT: Input Section Wildcards. - (line 2661) -* SORT_BY_NAME: Input Section Wildcards. - (line 2653) -* SPU: SPU ELF. (line 4524) -* SPU <1>: SPU ELF. (line 4541) -* SPU ELF options: SPU ELF. (line 4501) -* SPU extra overlay stubs: SPU ELF. (line 4514) -* SPU local store size: SPU ELF. (line 4519) -* SPU overlay stub symbols: SPU ELF. (line 4510) -* SPU overlays: SPU ELF. (line 4504) -* SPU plugins: SPU ELF. (line 4501) -* SQUAD(EXPRESSION): Output Section Data. - (line 2788) -* stack size: Options. (line 1839) -* standard Unix system: Options. (line 131) -* start of execution: Entry Point. (line 2076) -* STARTUP(FILENAME): File Commands. (line 2166) -* strip all symbols: Options. (line 579) -* strip debugger symbols: Options. (line 583) -* stripping all but some symbols: Options. (line 1120) -* SUBALIGN(SUBSECTION_ALIGN): Forced Input Alignment. - (line 3048) -* suffixes for integers: Constants. (line 3610) -* symbol defaults: Builtin Functions. (line 3971) -* symbol definition, scripts: Assignments. (line 2262) -* symbol names: Symbols. (line 3620) -* symbol tracing: Options. (line 657) -* symbol versions: VERSION. (line 3424) -* symbol-only input: Options. (line 568) -* symbols, from command line: Options. (line 915) -* symbols, relocatable and absolute: Expression Section. (line 3828) -* symbols, retaining selectively: Options. (line 1120) -* synthesizing linker: Options. (line 1099) -* synthesizing on H8/300: H8/300. (line 4086) -* TARGET(BFDNAME): Format Commands. (line 2204) -* TARGET1: ARM. (line 4209) -* TARGET2: ARM. (line 4214) -* thumb entry point: ARM. (line 4199) -* TI COFF versions: TI COFF. (line 4554) -* traditional format: Options. (line 1253) -* trampoline generation on M68HC11: M68HC11/68HC12. (line 4173) -* trampoline generation on M68HC12: M68HC11/68HC12. (line 4173) -* unallocated address, next: Builtin Functions. (line 4002) -* undefined symbol: Options. (line 614) -* undefined symbol in linker script: Miscellaneous Commands. - (line 2221) -* undefined symbols, warnings on: Options. (line 1409) -* uninitialized data placement: Input Section Common. - (line 2721) -* unspecified memory: Output Section Data. - (line 2821) -* usage: Options. (line 977) -* USE_BLX: ARM. (line 4237) -* using a DEF file: WIN32. (line 4596) -* using auto-export functionality: WIN32. (line 4579) -* Using decorations: WIN32. (line 4695) -* variables, defining: Assignments. (line 2262) -* verbose: Options. (line 1309) -* version: Options. (line 641) -* version script: VERSION. (line 3424) -* version script, symbol versions: Options. (line 1315) -* VERSION {script text}: VERSION. (line 3424) -* versions of symbols: VERSION. (line 3424) -* VFP11_DENORM_FIX: ARM. (line 4246) -* warnings, on combining symbols: Options. (line 1322) -* warnings, on section alignment: Options. (line 1413) -* warnings, on undefined symbols: Options. (line 1409) -* weak externals: WIN32. (line 4938) -* what is this?: Overview. (line 100) -* wildcard file name patterns: Input Section Wildcards. - (line 2616) -* Xtensa options: Xtensa. (line 5005) -* Xtensa processors: Xtensa. (line 4956) - diff --git a/contrib/binutils/ld/ldint.7 b/contrib/binutils/ld/ldint.7 new file mode 100644 index 000000000000..6c17af41d8a0 --- /dev/null +++ b/contrib/binutils/ld/ldint.7 @@ -0,0 +1,1277 @@ +.Dd 2015-03-02 +.Dt LDINT 7 +.Os +.Sh NAME +.Nm ldint +.Nd GNU Linker Internals +.Sh +This file documents the internals of the GNU linker +.Li ld . +It is a collection of miscellaneous information with little form at this point. +Mostly, it is a repository into which you can put information about GNU +.Li ld +as you discover it (or as you design changes to +.Li ld ) . +.Pp +This document is distributed under the terms of the GNU Free Documentation +License. A copy of the license is included in the section entitled "GNU Free +Documentation License". +.Pp +.Sh The Pa README File +Check the +.Pa README +file; it often has useful information that does not appear anywhere else in +the directory. +.Pp +.Sh How linker emulations are generated +Each linker target has an +.Em emulation . +The emulation includes the default linker script, and certain emulations also +modify certain types of linker behaviour. +.Pp +Emulations are created during the build process by the shell script +.Pa genscripts.sh . +.Pp +The +.Pa genscripts.sh +script starts by reading a file in the +.Pa emulparams +directory. This is a shell script which sets various shell variables used +by +.Pa genscripts.sh +and the other shell scripts it invokes. +.Pp +The +.Pa genscripts.sh +script will invoke a shell script in the +.Pa scripttempl +directory in order to create default linker scripts written in the linker +command language. The +.Pa scripttempl +script will be invoked 5 (or, in some cases, 6) times, with different assignments +to shell variables, to create different default scripts. The choice of script +is made based on the command line options. +.Pp +After creating the scripts, +.Pa genscripts.sh +will invoke yet another shell script, this time in the +.Pa emultempl +directory. That shell script will create the emulation source file, which +contains C code. This C code permits the linker emulation to override various +linker behaviours. Most targets use the generic emulation code, which is in +.Pa emultempl/generic.em . +.Pp +To summarize, +.Pa genscripts.sh +reads three shell scripts: an emulation parameters script in the +.Pa emulparams +directory, a linker script generation script in the +.Pa scripttempl +directory, and an emulation source file generation script in the +.Pa emultempl +directory. +.Pp +For example, the Sun 4 linker sets up variables in +.Pa emulparams/sun4.sh , +creates linker scripts using +.Pa scripttempl/aout.sc , +and creates the emulation code using +.Pa emultempl/sunos.em . +.Pp +Note that the linker can support several emulations simultaneously, depending +upon how it is configured. An emulation can be selected with the +.Li -m +option. The +.Li -V +option will list all supported emulations. +.Pp +.Ss Pa emulparams scripts +Each target selects a particular file in the +.Pa emulparams +directory by setting the shell variable +.Li targ_emul +in +.Pa configure.tgt . +This shell variable is used by the +.Pa configure +script to control building an emulation source file. +.Pp +Certain conventions are enforced. Suppose the +.Li targ_emul +variable is set to +.Va emul +in +.Pa configure.tgt . +The name of the emulation shell script will be +.Pa emulparams/ Va emul.sh . +The +.Pa Makefile +must have a target named +.Pa e Va emul.c ; +this target must depend upon +.Pa emulparams/ Va emul.sh , +as well as the appropriate scripts in the +.Pa scripttempl +and +.Pa emultempl +directories. The +.Pa Makefile +target must invoke +.Li GENSCRIPTS +with two arguments: +.Va emul , +and the value of the make variable +.Li tdir_ Va emul . +The value of the latter variable will be set by the +.Pa configure +script, and is used to set the default target directory to search. +.Pp +By convention, the +.Pa emulparams/ Va emul.sh +shell script should only set shell variables. It may set shell variables which +are to be interpreted by the +.Pa scripttempl +and the +.Pa emultempl +scripts. Certain shell variables are interpreted directly by the +.Pa genscripts.sh +script. +.Pp +Here is a list of shell variables interpreted by +.Pa genscripts.sh , +as well as some conventional shell variables interpreted by the +.Pa scripttempl +and +.Pa emultempl +scripts. +.Pp +.Bl -tag -width Ds +.It SCRIPT_NAME +This is the name of the +.Pa scripttempl +script to use. If +.Li SCRIPT_NAME +is set to +.Va script , +.Pa genscripts.sh +will use the script +.Pa scripttempl/ Va script.sc . +.Pp +.It TEMPLATE_NAME +This is the name of the +.Pa emultempl +script to use. If +.Li TEMPLATE_NAME +is set to +.Va template , +.Pa genscripts.sh +will use the script +.Pa emultempl/ Va template.em . +If this variable is not set, the default value is +.Li generic . +.Pp +.It GENERATE_SHLIB_SCRIPT +If this is set to a nonempty string, +.Pa genscripts.sh +will invoke the +.Pa scripttempl +script an extra time to create a shared library script. linker scripts. +.Pp +.It OUTPUT_FORMAT +This is normally set to indicate the BFD output format use (e.g., +.Li "a.out-sunos-big" . +The +.Pa scripttempl +script will normally use it in an +.Li OUTPUT_FORMAT +expression in the linker script. +.Pp +.It ARCH +This is normally set to indicate the architecture to use (e.g., +.Li sparc ) . +The +.Pa scripttempl +script will normally use it in an +.Li OUTPUT_ARCH +expression in the linker script. +.Pp +.It ENTRY +Some +.Pa scripttempl +scripts use this to set the entry address, in an +.Li ENTRY +expression in the linker script. +.Pp +.It TEXT_START_ADDR +Some +.Pa scripttempl +scripts use this to set the start address of the +.Li .text +section. +.Pp +.It NONPAGED_TEXT_START_ADDR +If this is defined, the +.Pa genscripts.sh +script sets +.Li TEXT_START_ADDR +to its value before running the +.Pa scripttempl +script for the +.Li -n +and +.Li -N +options (see Section +.Dq linker scripts ) . +.Pp +.It SEGMENT_SIZE +The +.Pa genscripts.sh +script uses this to set the default value of +.Li DATA_ALIGNMENT +when running the +.Pa scripttempl +script. +.Pp +.It TARGET_PAGE_SIZE +If +.Li SEGMENT_SIZE +is not defined, the +.Pa genscripts.sh +script uses this to define it. +.Pp +.It ALIGNMENT +Some +.Pa scripttempl +scripts set this to a number to pass to +.Li ALIGN +to set the required alignment for the +.Li end +symbol. +.El +.Pp +.Ss Pa scripttempl scripts +Each linker target uses a +.Pa scripttempl +script to generate the default linker scripts. The name of the +.Pa scripttempl +script is set by the +.Li SCRIPT_NAME +variable in the +.Pa emulparams +script. If +.Li SCRIPT_NAME +is set to +.Va script , +.Li genscripts.sh +will invoke +.Pa scripttempl/ Va script.sc . +.Pp +The +.Pa genscripts.sh +script will invoke the +.Pa scripttempl +script 5 to 8 times. Each time it will set the shell variable +.Li LD_FLAG +to a different value. When the linker is run, the options used will direct +it to select a particular script. (Script selection is controlled by the +.Li get_script +emulation entry point; this describes the conventional behaviour). +.Pp +The +.Pa scripttempl +script should just write a linker script, written in the linker command language, +to standard output. If the emulation name--the name of the +.Pa emulparams +file without the +.Pa .sc +extension--is +.Va emul , +then the output will be directed to +.Pa ldscripts/ Va emul. Va extension +in the build directory, where +.Va extension +changes each time the +.Pa scripttempl +script is invoked. +.Pp +Here is the list of values assigned to +.Li LD_FLAG . +.Pp +.Bl -tag -width Ds +.It (empty) +The script generated is used by default (when none of the following cases +apply). The output has an extension of +.Pa .x . +.It n +The script generated is used when the linker is invoked with the +.Li -n +option. The output has an extension of +.Pa .xn . +.It N +The script generated is used when the linker is invoked with the +.Li -N +option. The output has an extension of +.Pa .xbn . +.It r +The script generated is used when the linker is invoked with the +.Li -r +option. The output has an extension of +.Pa .xr . +.It u +The script generated is used when the linker is invoked with the +.Li -Ur +option. The output has an extension of +.Pa .xu . +.It shared +The +.Pa scripttempl +script is only invoked with +.Li LD_FLAG +set to this value if +.Li GENERATE_SHLIB_SCRIPT +is defined in the +.Pa emulparams +file. The +.Pa emultempl +script must arrange to use this script at the appropriate time, normally when +the linker is invoked with the +.Li -shared +option. The output has an extension of +.Pa .xs . +.It c +The +.Pa scripttempl +script is only invoked with +.Li LD_FLAG +set to this value if +.Li GENERATE_COMBRELOC_SCRIPT +is defined in the +.Pa emulparams +file or if +.Li SCRIPT_NAME +is +.Li elf . +The +.Pa emultempl +script must arrange to use this script at the appropriate time, normally when +the linker is invoked with the +.Li -z combreloc +option. The output has an extension of +.Pa .xc . +.It cshared +The +.Pa scripttempl +script is only invoked with +.Li LD_FLAG +set to this value if +.Li GENERATE_COMBRELOC_SCRIPT +is defined in the +.Pa emulparams +file or if +.Li SCRIPT_NAME +is +.Li elf +and +.Li GENERATE_SHLIB_SCRIPT +is defined in the +.Pa emulparams +file. The +.Pa emultempl +script must arrange to use this script at the appropriate time, normally when +the linker is invoked with the +.Li -shared -z combreloc +option. The output has an extension of +.Pa .xsc . +.El +.Pp +Besides the shell variables set by the +.Pa emulparams +script, and the +.Li LD_FLAG +variable, the +.Pa genscripts.sh +script will set certain variables for each run of the +.Pa scripttempl +script. +.Pp +.Bl -tag -width Ds +.It RELOCATING +This will be set to a non-empty string when the linker is doing a final relocation +(e.g., all scripts other than +.Li -r +and +.Li -Ur ) . +.Pp +.It CONSTRUCTING +This will be set to a non-empty string when the linker is building global +constructor and destructor tables (e.g., all scripts other than +.Li -r ) . +.Pp +.It DATA_ALIGNMENT +This will be set to an +.Li ALIGN +expression when the output should be page aligned, or to +.Li . +when generating the +.Li -N +script. +.Pp +.It CREATE_SHLIB +This will be set to a non-empty string when generating a +.Li -shared +script. +.Pp +.It COMBRELOC +This will be set to a non-empty string when generating +.Li -z combreloc +scripts to a temporary file name which can be used during script generation. +.El +.Pp +The conventional way to write a +.Pa scripttempl +script is to first set a few shell variables, and then write out a linker +script using +.Li cat +with a here document. The linker script will use variable substitutions, based +on the above variables and those set in the +.Pa emulparams +script, to control its behaviour. +.Pp +When there are parts of the +.Pa scripttempl +script which should only be run when doing a final relocation, they should +be enclosed within a variable substitution based on +.Li RELOCATING . +For example, on many targets special symbols such as +.Li _end +should be defined when doing a final link. Naturally, those symbols should +not be defined when doing a relocatable link using +.Li -r . +The +.Pa scripttempl +script could use a construct like this to define those symbols: +.Bd -literal -offset indent + ${RELOCATING+ _end = .;} +.Ed +This will do the symbol assignment only if the +.Li RELOCATING +variable is defined. +.Pp +The basic job of the linker script is to put the sections in the correct order, +and at the correct memory addresses. For some targets, the linker script may +have to do some other operations. +.Pp +For example, on most MIPS platforms, the linker is responsible for defining +the special symbol +.Li _gp , +used to initialize the +.Li $gp +register. It must be set to the start of the small data section plus +.Li 0x8000 . +Naturally, it should only be defined when doing a final relocation. This will +typically be done like this: +.Bd -literal -offset indent + ${RELOCATING+ _gp = ALIGN(16) + 0x8000;} +.Ed +This line would appear just before the sections which compose the small data +section ( +.Li .sdata , +.Li .sbss ) . +All those sections would be contiguous in memory. +.Pp +Many COFF systems build constructor tables in the linker script. The compiler +will arrange to output the address of each global constructor in a +.Li .ctor +section, and the address of each global destructor in a +.Li .dtor +section (this is done by defining +.Li ASM_OUTPUT_CONSTRUCTOR +and +.Li ASM_OUTPUT_DESTRUCTOR +in the +.Li gcc +configuration files). The +.Li gcc +runtime support routines expect the constructor table to be named +.Li __CTOR_LIST__ . +They expect it to be a list of words, with the first word being the count +of the number of entries. There should be a trailing zero word. (Actually, +the count may be -1 if the trailing word is present, and the trailing word +may be omitted if the count is correct, but, as the +.Li gcc +behaviour has changed slightly over the years, it is safest to provide both). +Here is a typical way that might be handled in a +.Pa scripttempl +file. +.Bd -literal -offset indent + ${CONSTRUCTING+ __CTOR_LIST__ = .;} + ${CONSTRUCTING+ LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)} + ${CONSTRUCTING+ *(.ctors)} + ${CONSTRUCTING+ LONG(0)} + ${CONSTRUCTING+ __CTOR_END__ = .;} + ${CONSTRUCTING+ __DTOR_LIST__ = .;} + ${CONSTRUCTING+ LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)} + ${CONSTRUCTING+ *(.dtors)} + ${CONSTRUCTING+ LONG(0)} + ${CONSTRUCTING+ __DTOR_END__ = .;} +.Ed +The use of +.Li CONSTRUCTING +ensures that these linker script commands will only appear when the linker +is supposed to be building the constructor and destructor tables. This example +is written for a target which uses 4 byte pointers. +.Pp +Embedded systems often need to set a stack address. This is normally best +done by using the +.Li PROVIDE +construct with a default stack address. This permits the user to easily override +the stack address using the +.Li --defsym +option. Here is an example: +.Bd -literal -offset indent + ${RELOCATING+ PROVIDE (__stack = 0x80000000);} +.Ed +The value of the symbol +.Li __stack +would then be used in the startup code to initialize the stack pointer. +.Pp +.Ss Pa emultempl scripts +Each linker target uses an +.Pa emultempl +script to generate the emulation code. The name of the +.Pa emultempl +script is set by the +.Li TEMPLATE_NAME +variable in the +.Pa emulparams +script. If the +.Li TEMPLATE_NAME +variable is not set, the default is +.Li generic . +If the value of +.Li TEMPLATE_NAME +is +.Va template , +.Pa genscripts.sh +will use +.Pa emultempl/ Va template.em . +.Pp +Most targets use the generic +.Pa emultempl +script, +.Pa emultempl/generic.em . +A different +.Pa emultempl +script is only needed if the linker must support unusual actions, such as +linking against shared libraries. +.Pp +The +.Pa emultempl +script is normally written as a simple invocation of +.Li cat +with a here document. The document will use a few variable substitutions. +Typically each function names uses a substitution involving +.Li EMULATION_NAME , +for ease of debugging when the linker supports multiple emulations. +.Pp +Every function and variable in the emitted file should be static. The only +globally visible object must be named +.Li ld_ Va EMULATION_NAME_emulation , +where +.Va EMULATION_NAME +is the name of the emulation set in +.Pa configure.tgt +(this is also the name of the +.Pa emulparams +file without the +.Pa .sh +extension). The +.Pa genscripts.sh +script will set the shell variable +.Li EMULATION_NAME +before invoking the +.Pa emultempl +script. +.Pp +The +.Li ld_ Va EMULATION_NAME_emulation +variable must be a +.Li struct ld_emulation_xfer_struct , +as defined in +.Pa ldemul.h . +It defines a set of function pointers which are invoked by the linker, as +well as strings for the emulation name (normally set from the shell variable +.Li EMULATION_NAME +and the default BFD target name (normally set from the shell variable +.Li OUTPUT_FORMAT +which is normally set by the +.Pa emulparams +file). +.Pp +The +.Pa genscripts.sh +script will set the shell variable +.Li COMPILE_IN +when it invokes the +.Pa emultempl +script for the default emulation. In this case, the +.Pa emultempl +script should include the linker scripts directly, and return them from the +.Li get_scripts +entry point. When the emulation is not the default, the +.Li get_scripts +entry point should just return a file name. See +.Pa emultempl/generic.em +for an example of how this is done. +.Pp +At some point, the linker emulation entry points should be documented. +.Pp +.Sh A Walkthrough of a Typical Emulation +This chapter is to help people who are new to the way emulations interact +with the linker, or who are suddenly thrust into the position of having to +work with existing emulations. It will discuss the files you need to be aware +of. It will tell you when the given "hooks" in the emulation will be called. +It will, hopefully, give you enough information about when and how things +happen that you'll be able to get by. As always, the source is the definitive +reference to this. +.Pp +The starting point for the linker is in +.Pa ldmain.c +where +.Li main +is defined. The bulk of the code that's emulation specific will initially +be in +.Li emultempl/ Va emulation.em +but will end up in +.Li e Va emulation.c +when the build is done. Most of the work to select and interface with emulations +is in +.Li ldemul.h +and +.Li ldemul.c . +Specifically, +.Li ldemul.h +defines the +.Li ld_emulation_xfer_struct +structure your emulation exports. +.Pp +Your emulation file exports a symbol +.Li ld_ Va EMULATION_NAME_emulation . +If your emulation is selected (it usually is, since usually there's only one), +.Li ldemul.c +sets the variable +.Va ld_emulation +to point to it. +.Li ldemul.c +also defines a number of API functions that interface to your emulation, like +.Li ldemul_after_parse +which simply calls your +.Li ld_ Va EMULATION_emulation.after_parse +function. For the rest of this section, the functions will be mentioned, but +you should assume the indirect reference to your emulation also. +.Pp +We will also skip or gloss over parts of the link process that don't relate +to emulations, like setting up internationalization. +.Pp +After initialization, +.Li main +selects an emulation by pre-scanning the command line arguments. It calls +.Li ldemul_choose_target +to choose a target. If you set +.Li choose_target +to +.Li ldemul_default_target , +it picks your +.Li target_name +by default. +.Pp +.Li main +calls +.Li ldemul_before_parse , +then +.Li parse_args . +.Li parse_args +calls +.Li ldemul_parse_args +for each arg, which must update the +.Li getopt +globals if it recognizes the argument. If the emulation doesn't recognize +it, then parse_args checks to see if it recognizes it. +.Pp +Now that the emulation has had access to all its command-line options, +.Li main +calls +.Li ldemul_set_symbols . +This can be used for any initialization that may be affected by options. It +is also supposed to set up any variables needed by the emulation script. +.Pp +.Li main +now calls +.Li ldemul_get_script +to get the emulation script to use (based on arguments, no doubt,see Section +.Dq Emulations ) +and runs it. While parsing, +.Li ldgram.y +may call +.Li ldemul_hll +or +.Li ldemul_syslib +to handle the +.Li HLL +or +.Li SYSLIB +commands. It may call +.Li ldemul_unrecognized_file +if you asked the linker to link a file it doesn't recognize. It will call +.Li ldemul_recognized_file +for each file it does recognize, in case the emulation wants to handle some +files specially. All the while, it's loading the files (possibly calling +.Li ldemul_open_dynamic_archive ) +and symbols and stuff. After it's done reading the script, +.Li main +calls +.Li ldemul_after_parse . +Use the after-parse hook to set up anything that depends on stuff the script +might have set up, like the entry point. +.Pp +.Li main +next calls +.Li lang_process +in +.Li ldlang.c . +This appears to be the main core of the linking itself, as far as emulation +hooks are concerned(*). It first opens the output file's BFD, calling +.Li ldemul_set_output_arch , +and calls +.Li ldemul_create_output_section_statements +in case you need to use other means to find or create object files (i.e. shared +libraries found on a path, or fake stub objects). Despite the name, nobody +creates output sections here. +.Pp +(*) In most cases, the BFD library does the bulk of the actual linking, handling +symbol tables, symbol resolution, relocations, and building the final output +file. See the BFD reference for all the details. Your emulation is usually +concerned more with managing things at the file and section level, like "put +this here, add this section", etc. +.Pp +Next, the objects to be linked are opened and BFDs created for them, and +.Li ldemul_after_open +is called. At this point, you have all the objects and symbols loaded, but +none of the data has been placed yet. +.Pp +Next comes the Big Linking Thingy (except for the parts BFD does). All input +sections are mapped to output sections according to the script. If a section +doesn't get mapped by default, +.Li ldemul_place_orphan +will get called to figure out where it goes. Next it figures out the offsets +for each section, calling +.Li ldemul_before_allocation +before and +.Li ldemul_after_allocation +after deciding where each input section ends up in the output sections. +.Pp +The last part of +.Li lang_process +is to figure out all the symbols' values. After assigning final values to +the symbols, +.Li ldemul_finish +is called, and after that, any undefined symbols are turned into fatal errors. +.Pp +OK, back to +.Li main , +which calls +.Li ldwrite +in +.Pa ldwrite.c . +.Li ldwrite +calls BFD's final_link, which does all the relocation fixups and writes the +output bfd to disk, and we're done. +.Pp +In summary, +.Pp +.Bl -bullet +.It +.Li main() +in +.Pa ldmain.c +.It +.Pa emultempl/ Va EMULATION.em +has your code +.It +.Li ldemul_choose_target +(defaults to your +.Li target_name ) +.It +.Li ldemul_before_parse +.It +Parse argv, calls +.Li ldemul_parse_args +for each +.It +.Li ldemul_set_symbols +.It +.Li ldemul_get_script +.It +parse script +.Pp +.Bl -bullet +.It +may call +.Li ldemul_hll +or +.Li ldemul_syslib +.It +may call +.Li ldemul_open_dynamic_archive +.El +.Pp +.It +.Li ldemul_after_parse +.It +.Li lang_process() +in +.Pa ldlang.c +.Pp +.Bl -bullet +.It +create +.Li output_bfd +.It +.Li ldemul_set_output_arch +.It +.Li ldemul_create_output_section_statements +.It +read objects, create input bfds - all symbols exist, but have no values +.It +may call +.Li ldemul_unrecognized_file +.It +will call +.Li ldemul_recognized_file +.It +.Li ldemul_after_open +.It +map input sections to output sections +.It +may call +.Li ldemul_place_orphan +for remaining sections +.It +.Li ldemul_before_allocation +.It +gives input sections offsets into output sections, places output sections +.It +.Li ldemul_after_allocation +- section addresses valid +.It +assigns values to symbols +.It +.Li ldemul_finish +- symbol values valid +.El +.Pp +.It +output bfd is written to disk +.Pp +.El +.Sh Some Architecture Specific Notes +This is the place for notes on the behavior of +.Li ld +on specific platforms. Currently, only Intel x86 is documented (and of that, +only the auto-import behavior for DLLs). +.Pp +.Ss Intel x86 +.Bl -tag -width Ds +.Li ld +can create DLLs that operate with various runtimes available on a common x86 +operating system. These runtimes include native (using the mingw "platform"), +cygwin, and pw. +.Pp +.It auto-import from DLLs +.Bl -enum +.It +With this feature on, DLL clients can import variables from DLL without any +concern from their side (for example, without any source code modifications). +Auto-import can be enabled using the +.Li --enable-auto-import +flag, or disabled via the +.Li --disable-auto-import +flag. Auto-import is disabled by default. +.Pp +.It +This is done completely in bounds of the PE specification (to be fair, there's +a minor violation of the spec at one point, but in practice auto-import works +on all known variants of that common x86 operating system) So, the resulting +DLL can be used with any other PE compiler/linker. +.Pp +.It +Auto-import is fully compatible with standard import method, in which variables +are decorated using attribute modifiers. Libraries of either type may be mixed +together. +.Pp +.It +Overhead (space): 8 bytes per imported symbol, plus 20 for each reference +to it; Overhead (load time): negligible; Overhead (virtual/physical memory): +should be less than effect of DLL relocation. +.El +.Pp +Motivation +.Pp +The obvious and only way to get rid of dllimport insanity is to make client +access variable directly in the DLL, bypassing the extra dereference imposed +by ordinary DLL runtime linking. I.e., whenever client contains something +like +.Pp +.Li mov dll_var,%eax, +.Pp +address of dll_var in the command should be relocated to point into loaded +DLL. The aim is to make OS loader do so, and than make ld help with that. +Import section of PE made following way: there's a vector of structures each +describing imports from particular DLL. Each such structure points to two +other parallel vectors: one holding imported names, and one which will hold +address of corresponding imported name. So, the solution is de-vectorize these +structures, making import locations be sparse and pointing directly into code. +.Pp +Implementation +.Pp +For each reference of data symbol to be imported from DLL (to set of which +belong symbols with name <sym>, if __imp_<sym> is found in implib), the import +fixup entry is generated. That entry is of type IMAGE_IMPORT_DESCRIPTOR and +stored in .idata$3 subsection. Each fixup entry contains pointer to symbol's +address within .text section (marked with __fuN_<sym> symbol, where N is integer), +pointer to DLL name (so, DLL name is referenced by multiple entries), and +pointer to symbol name thunk. Symbol name thunk is singleton vector (__nm_th_<symbol>) +pointing to IMAGE_IMPORT_BY_NAME structure (__nm_<symbol>) directly containing +imported name. Here comes that "om the edge" problem mentioned above: PE specification +rambles that name vector (OriginalFirstThunk) should run in parallel with +addresses vector (FirstThunk), i.e. that they should have same number of elements +and terminated with zero. We violate this, since FirstThunk points directly +into machine code. But in practice, OS loader implemented the sane way: it +goes thru OriginalFirstThunk and puts addresses to FirstThunk, not something +else. It once again should be noted that dll and symbol name structures are +reused across fixup entries and should be there anyway to support standard +import stuff, so sustained overhead is 20 bytes per reference. Other question +is whether having several IMAGE_IMPORT_DESCRIPTORS for the same DLL is possible. +Answer is yes, it is done even by native compiler/linker (libth32's functions +are in fact resident in windows9x kernel32.dll, so if you use it, you have +two IMAGE_IMPORT_DESCRIPTORS for kernel32.dll). Yet other question is whether +referencing the same PE structures several times is valid. The answer is why +not, prohibiting that (detecting violation) would require more work on behalf +of loader than not doing it. +.Pp +.El +.Sh GNU Free Documentation License +GNU Free Documentation License Version 1.1, March 2000 +.Pp +Copyright (C) 2000 Free Software Foundation, Inc. 51 Franklin Street, Fifth +Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and distribute +verbatim copies of this license document, but changing it is not allowed. +.Pp +0. PREAMBLE +.Pp +The purpose of this License is to make a manual, textbook, or other written +document "free" in the sense of freedom: to assure everyone the effective +freedom to copy and redistribute it, with or without modifying it, either +commercially or noncommercially. Secondarily, this License preserves for the +author and publisher a way to get credit for their work, while not being considered +responsible for modifications made by others. +.Pp +This License is a kind of "copyleft", which means that derivative works of +the document must themselves be free in the same sense. It complements the +GNU General Public License, which is a copyleft license designed for free +software. +.Pp +We have designed this License in order to use it for manuals for free software, +because free software needs free documentation: a free program should come +with manuals providing the same freedoms that the software does. But this +License is not limited to software manuals; it can be used for any textual +work, regardless of subject matter or whether it is published as a printed +book. We recommend this License principally for works whose purpose is instruction +or reference. +.Pp +1. APPLICABILITY AND DEFINITIONS +.Pp +This License applies to any manual or other work that contains a notice placed +by the copyright holder saying it can be distributed under the terms of this +License. The "Document", below, refers to any such manual or work. Any member +of the public is a licensee, and is addressed as "you". +.Pp +A "Modified Version" of the Document means any work containing the Document +or a portion of it, either copied verbatim, or with modifications and/or translated +into another language. +.Pp +A "Secondary Section" is a named appendix or a front-matter section of the +Document that deals exclusively with the relationship of the publishers or +authors of the Document to the Document's overall subject (or to related matters) +and contains nothing that could fall directly within that overall subject. +(For example, if the Document is in part a textbook of mathematics, a Secondary +Section may not explain any mathematics.) The relationship could be a matter +of historical connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding them. +.Pp +The "Invariant Sections" are certain Secondary Sections whose titles are designated, +as being those of Invariant Sections, in the notice that says that the Document +is released under this License. +.Pp +The "Cover Texts" are certain short passages of text that are listed, as Front-Cover +Texts or Back-Cover Texts, in the notice that says that the Document is released +under this License. +.Pp +A "Transparent" copy of the Document means a machine-readable copy, represented +in a format whose specification is available to the general public, whose +contents can be viewed and edited directly and straightforwardly with generic +text editors or (for images composed of pixels) generic paint programs or +(for drawings) some widely available drawing editor, and that is suitable +for input to text formatters or for automatic translation to a variety of +formats suitable for input to text formatters. A copy made in an otherwise +Transparent file format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is not +"Transparent" is called "Opaque". +.Pp +Examples of suitable formats for Transparent copies include plain ASCII without +markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly +available DTD, and standard-conforming simple HTML designed for human modification. +Opaque formats include PostScript, PDF, proprietary formats that can be read +and edited only by proprietary word processors, SGML or XML for which the +DTD and/or processing tools are not generally available, and the machine-generated +HTML produced by some word processors for output purposes only. +.Pp +The "Title Page" means, for a printed book, the title page itself, plus such +following pages as are needed to hold, legibly, the material this License +requires to appear in the title page. For works in formats which do not have +any title page as such, "Title Page" means the text near the most prominent +appearance of the work's title, preceding the beginning of the body of the +text. +.Pp +2. VERBATIM COPYING +.Pp +You may copy and distribute the Document in any medium, either commercially +or noncommercially, provided that this License, the copyright notices, and +the license notice saying this License applies to the Document are reproduced +in all copies, and that you add no other conditions whatsoever to those of +this License. You may not use technical measures to obstruct or control the +reading or further copying of the copies you make or distribute. However, +you may accept compensation in exchange for copies. If you distribute a large +enough number of copies you must also follow the conditions in section 3. +.Pp +You may also lend copies, under the same conditions stated above, and you +may publicly display copies. +.Pp +3. COPYING IN QUANTITY +.Pp +If you publish printed copies of the Document numbering more than 100, and +the Document's license notice requires Cover Texts, you must enclose the copies +in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover +Texts on the front cover, and Back-Cover Texts on the back cover. Both covers +must also clearly and legibly identify you as the publisher of these copies. +The front cover must present the full title with all words of the title equally +prominent and visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve the title +of the Document and satisfy these conditions, can be treated as verbatim copying +in other respects. +.Pp +If the required texts for either cover are too voluminous to fit legibly, +you should put the first ones listed (as many as fit reasonably) on the actual +cover, and continue the rest onto adjacent pages. +.Pp +If you publish or distribute Opaque copies of the Document numbering more +than 100, you must either include a machine-readable Transparent copy along +with each Opaque copy, or state in or with each Opaque copy a publicly-accessible +computer-network location containing a complete Transparent copy of the Document, +free of added material, which the general network-using public has access +to download anonymously at no charge using public-standard network protocols. +If you use the latter option, you must take reasonably prudent steps, when +you begin distribution of Opaque copies in quantity, to ensure that this Transparent +copy will remain thus accessible at the stated location until at least one +year after the last time you distribute an Opaque copy (directly or through +your agents or retailers) of that edition to the public. +.Pp +It is requested, but not required, that you contact the authors of the Document +well before redistributing any large number of copies, to give them a chance +to provide you with an updated version of the Document. +.Pp +4. MODIFICATIONS +.Pp +You may copy and distribute a Modified Version of the Document under the conditions +of sections 2 and 3 above, provided that you release the Modified Version +under precisely this License, with the Modified Version filling the role of +the Document, thus licensing distribution and modification of the Modified +Version to whoever possesses a copy of it. In addition, you must do these +things in the Modified Version: +.Pp +A. Use in the Title Page (and on the covers, if any) a title distinct from +that of the Document, and from those of previous versions (which should, if +there were any, be listed in the History section of the Document). You may +use the same title as a previous version if the original publisher of that +version gives permission. B. List on the Title Page, as authors, one or more +persons or entities responsible for authorship of the modifications in the +Modified Version, together with at least five of the principal authors of +the Document (all of its principal authors, if it has less than five). C. +State on the Title page the name of the publisher of the Modified Version, +as the publisher. D. Preserve all the copyright notices of the Document. E. +Add an appropriate copyright notice for your modifications adjacent to the +other copyright notices. F. Include, immediately after the copyright notices, +a license notice giving the public permission to use the Modified Version +under the terms of this License, in the form shown in the Addendum below. +G. Preserve in that license notice the full lists of Invariant Sections and +required Cover Texts given in the Document's license notice. H. Include an +unaltered copy of this License. I. Preserve the section entitled "History", +and its title, and add to it an item stating at least the title, year, new +authors, and publisher of the Modified Version as given on the Title Page. +If there is no section entitled "History" in the Document, create one stating +the title, year, authors, and publisher of the Document as given on its Title +Page, then add an item describing the Modified Version as stated in the previous +sentence. J. Preserve the network location, if any, given in the Document +for public access to a Transparent copy of the Document, and likewise the +network locations given in the Document for previous versions it was based +on. These may be placed in the "History" section. You may omit a network location +for a work that was published at least four years before the Document itself, +or if the original publisher of the version it refers to gives permission. +K. In any section entitled "Acknowledgements" or "Dedications", preserve the +section's title, and preserve in the section all the substance and tone of +each of the contributor acknowledgements and/or dedications given therein. +L. Preserve all the Invariant Sections of the Document, unaltered in their +text and in their titles. Section numbers or the equivalent are not considered +part of the section titles. M. Delete any section entitled "Endorsements". +Such a section may not be included in the Modified Version. N. Do not retitle +any existing section as "Endorsements" or to conflict in title with any Invariant +Section. +.Pp +If the Modified Version includes new front-matter sections or appendices that +qualify as Secondary Sections and contain no material copied from the Document, +you may at your option designate some or all of these sections as invariant. +To do this, add their titles to the list of Invariant Sections in the Modified +Version's license notice. These titles must be distinct from any other section +titles. +.Pp +You may add a section entitled "Endorsements", provided it contains nothing +but endorsements of your Modified Version by various parties--for example, +statements of peer review or that the text has been approved by an organization +as the authoritative definition of a standard. +.Pp +You may add a passage of up to five words as a Front-Cover Text, and a passage +of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts +in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover +Text may be added by (or through arrangements made by) any one entity. If +the Document already includes a cover text for the same cover, previously +added by you or by arrangement made by the same entity you are acting on behalf +of, you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. +.Pp +The author(s) and publisher(s) of the Document do not by this License give +permission to use their names for publicity for or to assert or imply endorsement +of any Modified Version. +.Pp +5. COMBINING DOCUMENTS +.Pp +You may combine the Document with other documents released under this License, +under the terms defined in section 4 above for modified versions, provided +that you include in the combination all of the Invariant Sections of all of +the original documents, unmodified, and list them all as Invariant Sections +of your combined work in its license notice. +.Pp +The combined work need only contain one copy of this License, and multiple +identical Invariant Sections may be replaced with a single copy. If there +are multiple Invariant Sections with the same name but different contents, +make the title of each such section unique by adding at the end of it, in +parentheses, the name of the original author or publisher of that section +if known, or else a unique number. Make the same adjustment to the section +titles in the list of Invariant Sections in the license notice of the combined +work. +.Pp +In the combination, you must combine any sections entitled "History" in the +various original documents, forming one section entitled "History"; likewise +combine any sections entitled "Acknowledgements", and any sections entitled +"Dedications". You must delete all sections entitled "Endorsements." +.Pp +6. COLLECTIONS OF DOCUMENTS +.Pp +You may make a collection consisting of the Document and other documents released +under this License, and replace the individual copies of this License in the +various documents with a single copy that is included in the collection, provided +that you follow the rules of this License for verbatim copying of each of +the documents in all other respects. +.Pp +You may extract a single document from such a collection, and distribute it +individually under this License, provided you insert a copy of this License +into the extracted document, and follow this License in all other respects +regarding verbatim copying of that document. +.Pp +7. AGGREGATION WITH INDEPENDENT WORKS +.Pp +A compilation of the Document or its derivatives with other separate and independent +documents or works, in or on a volume of a storage or distribution medium, +does not as a whole count as a Modified Version of the Document, provided +no compilation copyright is claimed for the compilation. Such a compilation +is called an "aggregate", and this License does not apply to the other self-contained +works thus compiled with the Document, on account of their being thus compiled, +if they are not themselves derivative works of the Document. +.Pp +If the Cover Text requirement of section 3 is applicable to these copies of +the Document, then if the Document is less than one quarter of the entire +aggregate, the Document's Cover Texts may be placed on covers that surround +only the Document within the aggregate. Otherwise they must appear on covers +around the whole aggregate. +.Pp +8. TRANSLATION +.Pp +Translation is considered a kind of modification, so you may distribute translations +of the Document under the terms of section 4. Replacing Invariant Sections +with translations requires special permission from their copyright holders, +but you may include translations of some or all Invariant Sections in addition +to the original versions of these Invariant Sections. You may include a translation +of this License provided that you also include the original English version +of this License. In case of a disagreement between the translation and the +original English version of this License, the original English version will +prevail. +.Pp +9. TERMINATION +.Pp +You may not copy, modify, sublicense, or distribute the Document except as +expressly provided for under this License. Any other attempt to copy, modify, +sublicense or distribute the Document is void, and will automatically terminate +your rights under this License. However, parties who have received copies, +or rights, from you under this License will not have their licenses terminated +so long as such parties remain in full compliance. +.Pp +10. FUTURE REVISIONS OF THIS LICENSE +.Pp +The Free Software Foundation may publish new, revised versions of the GNU +Free Documentation License from time to time. Such new versions will be similar +in spirit to the present version, but may differ in detail to address new +problems or concerns. See http://www.gnu.org/copyleft/. +.Pp +Each version of the License is given a distinguishing version number. If the +Document specifies that a particular numbered version of this License "or +any later version" applies to it, you have the option of following the terms +and conditions either of that specified version or of any later version that +has been published (not as a draft) by the Free Software Foundation. If the +Document does not specify a version number of this License, you may choose +any version ever published (not as a draft) by the Free Software Foundation. +.Pp +ADDENDUM: How to use this License for your documents +.Pp +To use this License in a document you have written, include a copy of the +License in the document and put the following copyright and license notices +just after the title page: +.Pp +.Bd -literal -offset indent + Copyright (c) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + A copy of the license is included in the section entitled "GNU + Free Documentation License". +.Ed +.Pp +If you have no Invariant Sections, write "with no Invariant Sections" instead +of saying which ones are invariant. If you have no Front-Cover Texts, write +"no Front-Cover Texts" instead of "Front-Cover Texts being LIST"; likewise +for Back-Cover Texts. +.Pp +If your document contains nontrivial examples of program code, we recommend +releasing these examples in parallel under your choice of free software license, +such as the GNU General Public License, to permit their use in free software. +.Pp diff --git a/contrib/diff/doc/diff.7 b/contrib/diff/doc/diff.7 new file mode 100644 index 000000000000..e973c1215a62 --- /dev/null +++ b/contrib/diff/doc/diff.7 @@ -0,0 +1,6287 @@ +.Dd 2015-03-02 +.Dt DIFF 7 +.Os +.Sh NAME +.Nm diff +.Nd Comparing and Merging Files +.Sh Comparing and Merging Files +.Sh Overview +Computer users often find occasion to ask how two files differ. Perhaps one +file is a newer version of the other file. Or maybe the two files started +out as identical copies but were changed by different people. +.Pp +You can use the +.Xr diff +command to show differences between two files, or each corresponding file +in two directories. +.Xr diff +outputs differences between files line by line in any of several formats, +selectable by command line options. This set of differences is often called +a +.Em diff +or +.Em patch . +For files that are identical, +.Xr diff +normally produces no output; for binary (non-text) files, +.Xr diff +normally reports only that they are different. +.Pp +You can use the +.Xr cmp +command to show the byte and line numbers where two files differ. +.Xr cmp +can also show all the bytes that differ between the two files, side by side. +A way to compare two files character by character is the Emacs command +.Li M-x compare-windows . +See Section.Dq Other Window , +for more information on that command. +.Pp +You can use the +.Xr diff3 +command to show differences among three files. When two people have made independent +changes to a common original, +.Xr diff3 +can report the differences between the original and the two changed versions, +and can produce a merged file that contains both persons' changes together +with warnings about conflicts. +.Pp +You can use the +.Xr sdiff +command to merge two files interactively. +.Pp +You can use the set of differences produced by +.Xr diff +to distribute updates to text files (such as program source code) to other +people. This method is especially useful when the differences are small compared +to the complete files. Given +.Xr diff +output, you can use the +.Xr patch +program to update, or +.Em patch , +a copy of the file. If you think of +.Xr diff +as subtracting one file from another to produce their difference, you can +think of +.Xr patch +as adding the difference to one file to reproduce the other. +.Pp +This manual first concentrates on making diffs, and later shows how to use +diffs to update files. +.Pp +GNU +.Xr diff +was written by Paul Eggert, Mike Haertel, David Hayes, Richard Stallman, and +Len Tower. Wayne Davison designed and implemented the unified output format. +The basic algorithm is described by Eugene W. Myers in \(lqAn O(ND) Difference +Algorithm and its Variations\(rq, +.Em Algorithmica +Vol. 1 No. 2, 1986, pp. 251--266; and in \(lqA File Comparison Program\(rq, Webb Miller +and Eugene W. Myers, +.Em Software---Practice and Experience +Vol. 15 No. 11, 1985, pp. 1025--1040. The algorithm was independently discovered +as described by E. Ukkonen in \(lqAlgorithms for Approximate String Matching\(rq, +.Em Information and Control +Vol. 64, 1985, pp. 100--118. Unless the +.Op --minimal +option is used, +.Xr diff +uses a heuristic by Paul Eggert that limits the cost to O(N^1.5 log N) at +the price of producing suboptimal output for large inputs with many differences. +Related algorithms are surveyed by Alfred V. Aho in section 6.3 of \(lqAlgorithms +for Finding Patterns in Strings\(rq, +.Em Handbook of Theoretical Computer Science +(Jan Van Leeuwen, ed.), Vol. A, +.Em Algorithms and Complexity , +Elsevier/MIT Press, 1990, pp. 255--300. +.Pp +GNU +.Xr diff3 +was written by Randy Smith. GNU +.Xr sdiff +was written by Thomas Lord. GNU +.Xr cmp +was written by Torbj\(:orn Granlund and David MacKenzie. +.Pp +GNU +.Xr patch +was written mainly by Larry Wall and Paul Eggert; several GNU enhancements +were contributed by Wayne Davison and David MacKenzie. Parts of this manual +are adapted from a manual page written by Larry Wall, with his permission. +.Pp +.Sh What Comparison Means +There are several ways to think about the differences between two files. One +way to think of the differences is as a series of lines that were deleted +from, inserted in, or changed in one file to produce the other file. +.Xr diff +compares two files line by line, finds groups of lines that differ, and reports +each group of differing lines. It can report the differing lines in several +formats, which have different purposes. +.Pp +GNU +.Xr diff +can show whether files are different without detailing the differences. It +also provides ways to suppress certain kinds of differences that are not important +to you. Most commonly, such differences are changes in the amount of white +space between words or lines. +.Xr diff +also provides ways to suppress differences in alphabetic case or in lines +that match a regular expression that you provide. These options can accumulate; +for example, you can ignore changes in both white space and alphabetic case. +.Pp +Another way to think of the differences between two files is as a sequence +of pairs of bytes that can be either identical or different. +.Xr cmp +reports the differences between two files byte by byte, instead of line by +line. As a result, it is often more useful than +.Xr diff +for comparing binary files. For text files, +.Xr cmp +is useful mainly when you want to know only whether two files are identical, +or whether one file is a prefix of the other. +.Pp +To illustrate the effect that considering changes byte by byte can have compared +with considering them line by line, think of what happens if a single newline +character is added to the beginning of a file. If that file is then compared +with an otherwise identical file that lacks the newline at the beginning, +.Xr diff +will report that a blank line has been added to the file, while +.Xr cmp +will report that almost every byte of the two files differs. +.Pp +.Xr diff3 +normally compares three input files line by line, finds groups of lines that +differ, and reports each group of differing lines. Its output is designed +to make it easy to inspect two different sets of changes to the same file. +.Pp +.Ss Hunks +When comparing two files, +.Xr diff +finds sequences of lines common to both files, interspersed with groups of +differing lines called +.Em hunks . +Comparing two identical files yields one sequence of common lines and no hunks, +because no lines differ. Comparing two entirely different files yields no +common lines and one large hunk that contains all lines of both files. In +general, there are many ways to match up lines between two given files. +.Xr diff +tries to minimize the total hunk size by finding large sequences of common +lines interspersed with small hunks of differing lines. +.Pp +For example, suppose the file +.Pa F +contains the three lines +.Li a , +.Li b , +.Li c , +and the file +.Pa G +contains the same three lines in reverse order +.Li c , +.Li b , +.Li a . +If +.Xr diff +finds the line +.Li c +as common, then the command +.Li diff F G +produces this output: +.Pp +.Bd -literal -offset indent +1,2d0 +< a +< b +3a2,3 +> b +> a +.Ed +.Pp +But if +.Xr diff +notices the common line +.Li b +instead, it produces this output: +.Pp +.Bd -literal -offset indent +1c1 +< a +--- +> c +3c3 +< c +--- +> a +.Ed +.Pp +It is also possible to find +.Li a +as the common line. +.Xr diff +does not always find an optimal matching between the files; it takes shortcuts +to run faster. But its output is usually close to the shortest possible. You +can adjust this tradeoff with the +.Op -d +or +.Op --minimal +option (see Section +.Dq diff Performance ) . +.Pp +.Ss Suppressing Differences in Blank and Tab Spacing +The +.Op -E +or +.Op --ignore-tab-expansion +option ignores the distinction between tabs and spaces on input. A tab is +considered to be equivalent to the number of spaces to the next tab stop (see Section +.Dq Tabs ) . +.Pp +The +.Op -b +or +.Op --ignore-space-change +option is stronger. It ignores white space at line end, and considers all +other sequences of one or more white space characters within a line to be +equivalent. With this option, +.Xr diff +considers the following two lines to be equivalent, where +.Li $ +denotes the line end: +.Pp +.Bd -literal -offset indent +Here lyeth muche rychnesse in lytell space. -- John Heywood$ +Here lyeth muche rychnesse in lytell space. -- John Heywood $ +.Ed +.Pp +The +.Op -w +or +.Op --ignore-all-space +option is stronger still. It ignores differences even if one line has white +space where the other line has none. +.Em White space +characters include tab, newline, vertical tab, form feed, carriage return, +and space; some locales may define additional characters to be white space. +With this option, +.Xr diff +considers the following two lines to be equivalent, where +.Li $ +denotes the line end and +.Li ^M +denotes a carriage return: +.Pp +.Bd -literal -offset indent +Here lyeth muche rychnesse in lytell space.-- John Heywood$ + He relyeth much erychnes seinly tells pace. --John Heywood ^M$ +.Ed +.Pp +.Ss Suppressing Differences Whose Lines Are All Blank +The +.Op -B +or +.Op --ignore-blank-lines +option ignores changes that consist entirely of blank lines. With this option, +for example, a file containing +.Bd -literal -offset indent +1. A point is that which has no part. + +2. A line is breadthless length. +-- Euclid, The Elements, I +.Ed +is considered identical to a file containing +.Bd -literal -offset indent +1. A point is that which has no part. +2. A line is breadthless length. + + +-- Euclid, The Elements, I +.Ed +.Pp +Normally this option affects only lines that are completely empty, but if +you also specify the +.Op -b +or +.Op --ignore-space-change +option, or the +.Op -w +or +.Op --ignore-all-space +option, lines are also affected if they look empty but contain white space. +In other words, +.Op -B +is equivalent to +.Li -I '^$' +by default, but it is equivalent to +.Op -I '^[[:space:]]*$' +if +.Op -b +or +.Op -w +is also specified. +.Pp +.Ss Suppressing Differences Whose Lines All Match a Regular Expression +To ignore insertions and deletions of lines that match a +.Xr grep +-style regular expression, use the +.Op -I Va regexp +or +.Op --ignore-matching-lines= Va regexp +option. You should escape regular expressions that contain shell metacharacters +to prevent the shell from expanding them. For example, +.Li diff -I '^[[:digit:]]' +ignores all changes to lines beginning with a digit. +.Pp +However, +.Op -I +only ignores the insertion or deletion of lines that contain the regular expression +if every changed line in the hunk---every insertion and every deletion---matches +the regular expression. In other words, for each nonignorable change, +.Xr diff +prints the complete set of changes in its vicinity, including the ignorable +ones. +.Pp +You can specify more than one regular expression for lines to ignore by using +more than one +.Op -I +option. +.Xr diff +tries to match each line against each regular expression. +.Pp +.Ss Suppressing Case Differences +GNU +.Xr diff +can treat lower case letters as equivalent to their upper case counterparts, +so that, for example, it considers +.Li Funky Stuff , +.Li funky STUFF , +and +.Li fUNKy stuFf +to all be the same. To request this, use the +.Op -i +or +.Op --ignore-case +option. +.Pp +.Ss Summarizing Which Files Differ +When you only want to find out whether files are different, and you don't +care what the differences are, you can use the summary output format. In this +format, instead of showing the differences between the files, +.Xr diff +simply reports whether files differ. The +.Op -q +or +.Op --brief +option selects this output format. +.Pp +This format is especially useful when comparing the contents of two directories. +It is also much faster than doing the normal line by line comparisons, because +.Xr diff +can stop analyzing the files as soon as it knows that there are any differences. +.Pp +You can also get a brief indication of whether two files differ by using +.Xr cmp . +For files that are identical, +.Xr cmp +produces no output. When the files differ, by default, +.Xr cmp +outputs the byte and line number where the first difference occurs, or reports +that one file is a prefix of the other. You can use the +.Op -s , +.Op --quiet , +or +.Op --silent +option to suppress that information, so that +.Xr cmp +produces no output and reports whether the files differ using only its exit +status (see Section +.Dq Invoking cmp ) . +.Pp +Unlike +.Xr diff , +.Xr cmp +cannot compare directories; it can only compare two files. +.Pp +.Ss Binary Files and Forcing Text Comparisons +If +.Xr diff +thinks that either of the two files it is comparing is binary (a non-text +file), it normally treats that pair of files much as if the summary output +format had been selected (see Section +.Dq Brief ) , +and reports only that the binary files are different. This is because line +by line comparisons are usually not meaningful for binary files. +.Pp +.Xr diff +determines whether a file is text or binary by checking the first few bytes +in the file; the exact number of bytes is system dependent, but it is typically +several thousand. If every byte in that part of the file is non-null, +.Xr diff +considers the file to be text; otherwise it considers the file to be binary. +.Pp +Sometimes you might want to force +.Xr diff +to consider files to be text. For example, you might be comparing text files +that contain null characters; +.Xr diff +would erroneously decide that those are non-text files. Or you might be comparing +documents that are in a format used by a word processing system that uses +null characters to indicate special formatting. You can force +.Xr diff +to consider all files to be text files, and compare them line by line, by +using the +.Op -a +or +.Op --text +option. If the files you compare using this option do not in fact contain +text, they will probably contain few newline characters, and the +.Xr diff +output will consist of hunks showing differences between long lines of whatever +characters the files contain. +.Pp +You can also force +.Xr diff +to report only whether files differ (but not how). Use the +.Op -q +or +.Op --brief +option for this. +.Pp +Normally, differing binary files count as trouble because the resulting +.Xr diff +output does not capture all the differences. This trouble causes +.Xr diff +to exit with status 2. However, this trouble cannot occur with the +.Op -a +or +.Op --text +option, or with the +.Op -q +or +.Op --brief +option, as these options both cause +.Xr diff +to generate a form of output that represents differences as requested. +.Pp +In operating systems that distinguish between text and binary files, +.Xr diff +normally reads and writes all data as text. Use the +.Op --binary +option to force +.Xr diff +to read and write binary data instead. This option has no effect on a POSIX-compliant +system like GNU or traditional Unix. However, many personal computer operating +systems represent the end of a line with a carriage return followed by a newline. +On such systems, +.Xr diff +normally ignores these carriage returns on input and generates them at the +end of each output line, but with the +.Op --binary +option +.Xr diff +treats each carriage return as just another input character, and does not +generate a carriage return at the end of each output line. This can be useful +when dealing with non-text files that are meant to be interchanged with POSIX-compliant +systems. +.Pp +The +.Op --strip-trailing-cr +causes +.Xr diff +to treat input lines that end in carriage return followed by newline as if +they end in plain newline. This can be useful when comparing text that is +imperfectly imported from many personal computer operating systems. This option +affects how lines are read, which in turn affects how they are compared and +output. +.Pp +If you want to compare two files byte by byte, you can use the +.Xr cmp +program with the +.Op -l +or +.Op --verbose +option to show the values of each differing byte in the two files. With GNU +.Xr cmp , +you can also use the +.Op -b +or +.Op --print-bytes +option to show the ASCII representation of those bytes.See Section +.Dq Invoking cmp , +for more information. +.Pp +If +.Xr diff3 +thinks that any of the files it is comparing is binary (a non-text file), +it normally reports an error, because such comparisons are usually not useful. +.Xr diff3 +uses the same test as +.Xr diff +to decide whether a file is binary. As with +.Xr diff , +if the input files contain a few non-text bytes but otherwise are like text +files, you can force +.Xr diff3 +to consider all files to be text files and compare them line by line by using +the +.Op -a +or +.Op --text +option. +.Pp +.Sh Xr diff Output Formats +.Xr diff +has several mutually exclusive options for output format. The following sections +describe each format, illustrating how +.Xr diff +reports the differences between two sample input files. +.Pp +.Ss Two Sample Input Files +Here are two sample files that we will use in numerous examples to illustrate +the output of +.Xr diff +and how various options can change it. +.Pp +This is the file +.Pa lao : +.Pp +.Bd -literal -offset indent +The Way that can be told of is not the eternal Way; +The name that can be named is not the eternal name. +The Nameless is the origin of Heaven and Earth; +The Named is the mother of all things. +Therefore let there always be non-being, + so we may see their subtlety, +And let there always be being, + so we may see their outcome. +The two are the same, +But after they are produced, + they have different names. +.Ed +.Pp +This is the file +.Pa tzu : +.Pp +.Bd -literal -offset indent +The Nameless is the origin of Heaven and Earth; +The named is the mother of all things. + +Therefore let there always be non-being, + so we may see their subtlety, +And let there always be being, + so we may see their outcome. +The two are the same, +But after they are produced, + they have different names. +They both may be called deep and profound. +Deeper and more profound, +The door of all subtleties! +.Ed +.Pp +In this example, the first hunk contains just the first two lines of +.Pa lao , +the second hunk contains the fourth line of +.Pa lao +opposing the second and third lines of +.Pa tzu , +and the last hunk contains just the last three lines of +.Pa tzu . +.Pp +.Ss Showing Differences in Their Context +Usually, when you are looking at the differences between files, you will also +want to see the parts of the files near the lines that differ, to help you +understand exactly what has changed. These nearby parts of the files are called +the +.Em context . +.Pp +GNU +.Xr diff +provides two output formats that show context around the differing lines: +.Em context format +and +.Em unified format . +It can optionally show in which function or section of the file the differing +lines are found. +.Pp +If you are distributing new versions of files to other people in the form +of +.Xr diff +output, you should use one of the output formats that show context so that +they can apply the diffs even if they have made small changes of their own +to the files. +.Xr patch +can apply the diffs in this case by searching in the files for the lines of +context around the differing lines; if those lines are actually a few lines +away from where the diff says they are, +.Xr patch +can adjust the line numbers accordingly and still apply the diff correctly.See Section +.Dq Imperfect , +for more information on using +.Xr patch +to apply imperfect diffs. +.Pp +.Em Context Format +.Pp +The context output format shows several lines of context around the lines +that differ. It is the standard format for distributing updates to source +code. +.Pp +To select this output format, use the +.Op -C Va lines , +.Op --context[= Va lines] , +or +.Op -c +option. The argument +.Va lines +that some of these options take is the number of lines of context to show. +If you do not specify +.Va lines , +it defaults to three. For proper operation, +.Xr patch +typically needs at least two lines of context. +.Pp +.No An Example of Context Format +.Pp +Here is the output of +.Li diff -c lao tzu +(see Section +.Dq Sample diff Input , +for the complete contents of the two files). Notice that up to three lines +that are not different are shown around each line that is different; they +are the context lines. Also notice that the first two hunks have run together, +because their contents overlap. +.Pp +.Bd -literal -offset indent +*** lao 2002-02-21 23:30:39.942229878 -0800 +--- tzu 2002-02-21 23:30:50.442260588 -0800 +*************** +*** 1,7 **** +- The Way that can be told of is not the eternal Way; +- The name that can be named is not the eternal name. + The Nameless is the origin of Heaven and Earth; +! The Named is the mother of all things. + Therefore let there always be non-being, + so we may see their subtlety, + And let there always be being, +--- 1,6 ---- + The Nameless is the origin of Heaven and Earth; +! The named is the mother of all things. +! + Therefore let there always be non-being, + so we may see their subtlety, + And let there always be being, +*************** +*** 9,11 **** +--- 8,13 ---- + The two are the same, + But after they are produced, + they have different names. ++ They both may be called deep and profound. ++ Deeper and more profound, ++ The door of all subtleties! +.Ed +.Pp +.No An Example of Context Format with Less Context +.Pp +Here is the output of +.Li diff -C 1 lao tzu +(see Section +.Dq Sample diff Input , +for the complete contents of the two files). Notice that at most one context +line is reported here. +.Pp +.Bd -literal -offset indent +*** lao 2002-02-21 23:30:39.942229878 -0800 +--- tzu 2002-02-21 23:30:50.442260588 -0800 +*************** +*** 1,5 **** +- The Way that can be told of is not the eternal Way; +- The name that can be named is not the eternal name. + The Nameless is the origin of Heaven and Earth; +! The Named is the mother of all things. + Therefore let there always be non-being, +--- 1,4 ---- + The Nameless is the origin of Heaven and Earth; +! The named is the mother of all things. +! + Therefore let there always be non-being, +*************** +*** 11 **** +--- 10,13 ---- + they have different names. ++ They both may be called deep and profound. ++ Deeper and more profound, ++ The door of all subtleties! +.Ed +.Pp +.No Detailed Description of Context Format +.Pp +The context output format starts with a two-line header, which looks like +this: +.Pp +.Bd -literal -offset indent +*** from-file from-file-modification-time +--- to-file to-file-modification time +.Ed +.Pp +The time stamp normally looks like +.Li 2002-02-21 23:30:39.942229878 -0800 +to indicate the date, time with fractional seconds, and time zone in +.Lk ftp://ftp.isi.edu/in-notes/rfc2822.txt . +(The fractional seconds are omitted on hosts that do not support fractional +time stamps.) However, a traditional time stamp like +.Li Thu Feb 21 23:30:39 2002 +is used if the +.Ev LC_TIME +locale category is either +.Li C +or +.Li POSIX . +.Pp +You can change the header's content with the +.Op --label= Va label +option; see Alternate Names. +.Pp +Next come one or more hunks of differences; each hunk shows one area where +the files differ. Context format hunks look like this: +.Pp +.Bd -literal -offset indent +*************** +*** from-file-line-numbers **** + from-file-line + from-file-line... +--- to-file-line-numbers ---- + to-file-line + to-file-line... +.Ed +.Pp +If a hunk contains two or more lines, its line numbers look like +.Li Va start, Va end . +Otherwise only its end line number appears. An empty hunk is considered to +end at the line that precedes the hunk. +.Pp +The lines of context around the lines that differ start with two space characters. +The lines that differ between the two files start with one of the following +indicator characters, followed by a space character: +.Pp +.Bl -tag -width Ds +.It ! +A line that is part of a group of one or more lines that changed between the +two files. There is a corresponding group of lines marked with +.Li ! +in the part of this hunk for the other file. +.Pp +.It + +An \(lqinserted\(rq line in the second file that corresponds to nothing in the first +file. +.Pp +.It - +A \(lqdeleted\(rq line in the first file that corresponds to nothing in the second +file. +.El +.Pp +If all of the changes in a hunk are insertions, the lines of +.Va from-file +are omitted. If all of the changes are deletions, the lines of +.Va to-file +are omitted. +.Pp +.Em Unified Format +.Pp +The unified output format is a variation on the context format that is more +compact because it omits redundant context lines. To select this output format, +use the +.Op -U Va lines , +.Op --unified[= Va lines] , +or +.Op -u +option. The argument +.Va lines +is the number of lines of context to show. When it is not given, it defaults +to three. +.Pp +At present, only GNU +.Xr diff +can produce this format and only GNU +.Xr patch +can automatically apply diffs in this format. For proper operation, +.Xr patch +typically needs at least three lines of context. +.Pp +.No An Example of Unified Format +.Pp +Here is the output of the command +.Li diff -u lao tzu +(see Section +.Dq Sample diff Input , +for the complete contents of the two files): +.Pp +.Bd -literal -offset indent +--- lao 2002-02-21 23:30:39.942229878 -0800 ++++ tzu 2002-02-21 23:30:50.442260588 -0800 +@@ -1,7 +1,6 @@ +-The Way that can be told of is not the eternal Way; +-The name that can be named is not the eternal name. + The Nameless is the origin of Heaven and Earth; +-The Named is the mother of all things. ++The named is the mother of all things. ++ + Therefore let there always be non-being, + so we may see their subtlety, + And let there always be being, +@@ -9,3 +8,6 @@ + The two are the same, + But after they are produced, + they have different names. ++They both may be called deep and profound. ++Deeper and more profound, ++The door of all subtleties! +.Ed +.Pp +.No Detailed Description of Unified Format +.Pp +The unified output format starts with a two-line header, which looks like +this: +.Pp +.Bd -literal -offset indent +--- from-file from-file-modification-time ++++ to-file to-file-modification-time +.Ed +.Pp +The time stamp looks like +.Li 2002-02-21 23:30:39.942229878 -0800 +to indicate the date, time with fractional seconds, and time zone. The fractional +seconds are omitted on hosts that do not support fractional time stamps. +.Pp +You can change the header's content with the +.Op --label= Va label +option; seeSee Section +.Dq Alternate Names . +.Pp +Next come one or more hunks of differences; each hunk shows one area where +the files differ. Unified format hunks look like this: +.Pp +.Bd -literal -offset indent +@@ from-file-line-numbers to-file-line-numbers @@ + line-from-either-file + line-from-either-file... +.Ed +.Pp +If a hunk contains just one line, only its start line number appears. Otherwise +its line numbers look like +.Li Va start, Va count . +An empty hunk is considered to start at the line that follows the hunk. +.Pp +If a hunk and its context contain two or more lines, its line numbers look +like +.Li Va start, Va count . +Otherwise only its end line number appears. An empty hunk is considered to +end at the line that precedes the hunk. +.Pp +The lines common to both files begin with a space character. The lines that +actually differ between the two files have one of the following indicator +characters in the left print column: +.Pp +.Bl -tag -width Ds +.It + +A line was added here to the first file. +.Pp +.It - +A line was removed here from the first file. +.El +.Pp +.Em Showing Which Sections Differences Are in +.Pp +Sometimes you might want to know which part of the files each change falls +in. If the files are source code, this could mean which function was changed. +If the files are documents, it could mean which chapter or appendix was changed. +GNU +.Xr diff +can show this by displaying the nearest section heading line that precedes +the differing lines. Which lines are \(lqsection headings\(rq is determined by a regular +expression. +.Pp +.No Showing Lines That Match Regular Expressions +.Pp +To show in which sections differences occur for files that are not source +code for C or similar languages, use the +.Op -F Va regexp +or +.Op --show-function-line= Va regexp +option. +.Xr diff +considers lines that match the +.Xr grep +-style regular expression +.Va regexp +to be the beginning of a section of the file. Here are suggested regular expressions +for some common languages: +.Pp +.Bl -tag -width Ds +.It ^[[:alpha:]$_] +C, C++, Prolog +.It ^( +Lisp +.It ^@node +Texinfo +.El +.Pp +This option does not automatically select an output format; in order to use +it, you must select the context format (see Section +.Dq Context Format ) +or unified format (see Section +.Dq Unified Format ) . +In other output formats it has no effect. +.Pp +The +.Op -F +or +.Op --show-function-line +option finds the nearest unchanged line that precedes each hunk of differences +and matches the given regular expression. Then it adds that line to the end +of the line of asterisks in the context format, or to the +.Li @@ +line in unified format. If no matching line exists, this option leaves the +output for that hunk unchanged. If that line is more than 40 characters long, +it outputs only the first 40 characters. You can specify more than one regular +expression for such lines; +.Xr diff +tries to match each line against each regular expression, starting with the +last one given. This means that you can use +.Op -p +and +.Op -F +together, if you wish. +.Pp +.No Showing C Function Headings +.Pp +To show in which functions differences occur for C and similar languages, +you can use the +.Op -p +or +.Op --show-c-function +option. This option automatically defaults to the context output format (see Section +.Dq Context Format ) , +with the default number of lines of context. You can override that number +with +.Op -C Va lines +elsewhere in the command line. You can override both the format and the number +with +.Op -U Va lines +elsewhere in the command line. +.Pp +The +.Op -p +or +.Op --show-c-function +option is equivalent to +.Op -F '^[[:alpha:]$_]' +if the unified format is specified, otherwise +.Op -c -F '^[[:alpha:]$_]' +(see Section +.Dq Specified Headings ) . +GNU +.Xr diff +provides this option for the sake of convenience. +.Pp +.Em Showing Alternate File Names +.Pp +If you are comparing two files that have meaningless or uninformative names, +you might want +.Xr diff +to show alternate names in the header of the context and unified output formats. +To do this, use the +.Op --label= Va label +option. The first time you give this option, its argument replaces the name +and date of the first file in the header; the second time, its argument replaces +the name and date of the second file. If you give this option more than twice, +.Xr diff +reports an error. The +.Op --label +option does not affect the file names in the +.Xr pr +header when the +.Op -l +or +.Op --paginate +option is used (see Section +.Dq Pagination ) . +.Pp +Here are the first two lines of the output from +.Li diff -C 2 --label=original --label=modified lao tzu : +.Pp +.Bd -literal -offset indent +*** original +--- modified +.Ed +.Pp +.Ss Showing Differences Side by Side +.Xr diff +can produce a side by side difference listing of two files. The files are +listed in two columns with a gutter between them. The gutter contains one +of the following markers: +.Pp +.Bl -tag -width Ds +.It white space +The corresponding lines are in common. That is, either the lines are identical, +or the difference is ignored because of one of the +.Op --ignore +options (see Section +.Dq White Space ) . +.Pp +.It Li | +The corresponding lines differ, and they are either both complete or both +incomplete. +.Pp +.It Li < +The files differ and only the first file contains the line. +.Pp +.It Li > +The files differ and only the second file contains the line. +.Pp +.It Li ( +Only the first file contains the line, but the difference is ignored. +.Pp +.It Li ) +Only the second file contains the line, but the difference is ignored. +.Pp +.It Li \e +The corresponding lines differ, and only the first line is incomplete. +.Pp +.It Li / +The corresponding lines differ, and only the second line is incomplete. +.El +.Pp +Normally, an output line is incomplete if and only if the lines that it contains +are incomplete;See Section +.Dq Incomplete Lines . +However, when an output line represents two differing lines, one might be +incomplete while the other is not. In this case, the output line is complete, +but its the gutter is marked +.Li \e +if the first line is incomplete, +.Li / +if the second line is. +.Pp +Side by side format is sometimes easiest to read, but it has limitations. +It generates much wider output than usual, and truncates lines that are too +long to fit. Also, it relies on lining up output more heavily than usual, +so its output looks particularly bad if you use varying width fonts, nonstandard +tab stops, or nonprinting characters. +.Pp +You can use the +.Xr sdiff +command to interactively merge side by side differences.See Section +.Dq Interactive Merging , +for more information on merging files. +.Pp +.Em Controlling Side by Side Format +.Pp +The +.Op -y +or +.Op --side-by-side +option selects side by side format. Because side by side output lines contain +two input lines, the output is wider than usual: normally 130 print columns, +which can fit onto a traditional printer line. You can set the width of the +output with the +.Op -W Va columns +or +.Op --width= Va columns +option. The output is split into two halves of equal width, separated by a +small gutter to mark differences; the right half is aligned to a tab stop +so that tabs line up. Input lines that are too long to fit in half of an output +line are truncated for output. +.Pp +The +.Op --left-column +option prints only the left column of two common lines. The +.Op --suppress-common-lines +option suppresses common lines entirely. +.Pp +.Em An Example of Side by Side Format +.Pp +Here is the output of the command +.Li diff -y -W 72 lao tzu +(see Section +.Dq Sample diff Input , +for the complete contents of the two files). +.Pp +.Bd -literal -offset indent +The Way that can be told of is n < +The name that can be named is no < +The Nameless is the origin of He The Nameless is the origin of He +The Named is the mother of all t | The named is the mother of all t + > +Therefore let there always be no Therefore let there always be no + so we may see their subtlety, so we may see their subtlety, +And let there always be being, And let there always be being, + so we may see their outcome. so we may see their outcome. +The two are the same, The two are the same, +But after they are produced, But after they are produced, + they have different names. they have different names. + > They both may be called deep and + > Deeper and more profound, + > The door of all subtleties! +.Ed +.Pp +.Ss Showing Differences Without Context +The \(lqnormal\(rq +.Xr diff +output format shows each hunk of differences without any surrounding context. +Sometimes such output is the clearest way to see how lines have changed, without +the clutter of nearby unchanged lines (although you can get similar results +with the context or unified formats by using 0 lines of context). However, +this format is no longer widely used for sending out patches; for that purpose, +the context format (see Section +.Dq Context Format ) +and the unified format (see Section +.Dq Unified Format ) +are superior. Normal format is the default for compatibility with older versions +of +.Xr diff +and the POSIX standard. Use the +.Op --normal +option to select this output format explicitly. +.Pp +.Em An Example of Normal Format +.Pp +Here is the output of the command +.Li diff lao tzu +(see Section +.Dq Sample diff Input , +for the complete contents of the two files). Notice that it shows only the +lines that are different between the two files. +.Pp +.Bd -literal -offset indent +1,2d0 +< The Way that can be told of is not the eternal Way; +< The name that can be named is not the eternal name. +4c2,3 +< The Named is the mother of all things. +--- +> The named is the mother of all things. +> +11a11,13 +> They both may be called deep and profound. +> Deeper and more profound, +> The door of all subtleties! +.Ed +.Pp +.Em Detailed Description of Normal Format +.Pp +The normal output format consists of one or more hunks of differences; each +hunk shows one area where the files differ. Normal format hunks look like +this: +.Pp +.Bd -literal -offset indent +change-command +< from-file-line +< from-file-line... +--- +> to-file-line +> to-file-line... +.Ed +.Pp +There are three types of change commands. Each consists of a line number or +comma-separated range of lines in the first file, a single character indicating +the kind of change to make, and a line number or comma-separated range of +lines in the second file. All line numbers are the original line numbers in +each file. The types of change commands are: +.Pp +.Bl -tag -width Ds +.It Va la Va r +Add the lines in range +.Va r +of the second file after line +.Va l +of the first file. For example, +.Li 8a12,15 +means append lines 12--15 of file 2 after line 8 of file 1; or, if changing +file 2 into file 1, delete lines 12--15 of file 2. +.Pp +.It Va fc Va t +Replace the lines in range +.Va f +of the first file with lines in range +.Va t +of the second file. This is like a combined add and delete, but more compact. +For example, +.Li 5,7c8,10 +means change lines 5--7 of file 1 to read as lines 8--10 of file 2; or, if +changing file 2 into file 1, change lines 8--10 of file 2 to read as lines +5--7 of file 1. +.Pp +.It Va rd Va l +Delete the lines in range +.Va r +from the first file; line +.Va l +is where they would have appeared in the second file had they not been deleted. +For example, +.Li 5,7d3 +means delete lines 5--7 of file 1; or, if changing file 2 into file 1, append +lines 5--7 of file 1 after line 3 of file 2. +.El +.Pp +.Ss Making Edit Scripts +Several output modes produce command scripts for editing +.Va from-file +to produce +.Va to-file . +.Pp +.Em Xr ed Scripts +.Pp +.Xr diff +can produce commands that direct the +.Xr ed +text editor to change the first file into the second file. Long ago, this +was the only output mode that was suitable for editing one file into another +automatically; today, with +.Xr patch , +it is almost obsolete. Use the +.Op -e +or +.Op --ed +option to select this output format. +.Pp +Like the normal format (see Section +.Dq Normal ) , +this output format does not show any context; unlike the normal format, it +does not include the information necessary to apply the diff in reverse (to +produce the first file if all you have is the second file and the diff). +.Pp +If the file +.Pa d +contains the output of +.Li diff -e old new , +then the command +.Li (cat d && echo w) | ed - old +edits +.Pa old +to make it a copy of +.Pa new . +More generally, if +.Pa d1 , +.Pa d2 , +\&..., +.Pa dN +contain the outputs of +.Li diff -e old new1 , +.Li diff -e new1 new2 , +\&..., +.Li diff -e newN-1 newN , +respectively, then the command +.Li (cat d1 d2 ... dN && echo w) | ed - old +edits +.Pa old +to make it a copy of +.Pa newN . +.Pp +.No Example Xr ed Script +.Pp +Here is the output of +.Li diff -e lao tzu +(see Section +.Dq Sample diff Input , +for the complete contents of the two files): +.Pp +.Bd -literal -offset indent +11a +They both may be called deep and profound. +Deeper and more profound, +The door of all subtleties! +\&. +4c +The named is the mother of all things. + +\&. +1,2d +.Ed +.Pp +.No Detailed Description of Xr ed Format +.Pp +The +.Xr ed +output format consists of one or more hunks of differences. The changes closest +to the ends of the files come first so that commands that change the number +of lines do not affect how +.Xr ed +interprets line numbers in succeeding commands. +.Xr ed +format hunks look like this: +.Pp +.Bd -literal -offset indent +change-command +to-file-line +to-file-line... +\&. +.Ed +.Pp +Because +.Xr ed +uses a single period on a line to indicate the end of input, GNU +.Xr diff +protects lines of changes that contain a single period on a line by writing +two periods instead, then writing a subsequent +.Xr ed +command to change the two periods into one. The +.Xr ed +format cannot represent an incomplete line, so if the second file ends in +a changed incomplete line, +.Xr diff +reports an error and then pretends that a newline was appended. +.Pp +There are three types of change commands. Each consists of a line number or +comma-separated range of lines in the first file and a single character indicating +the kind of change to make. All line numbers are the original line numbers +in the file. The types of change commands are: +.Pp +.Bl -tag -width Ds +.It Va la +Add text from the second file after line +.Va l +in the first file. For example, +.Li 8a +means to add the following lines after line 8 of file 1. +.Pp +.It Va rc +Replace the lines in range +.Va r +in the first file with the following lines. Like a combined add and delete, +but more compact. For example, +.Li 5,7c +means change lines 5--7 of file 1 to read as the text file 2. +.Pp +.It Va rd +Delete the lines in range +.Va r +from the first file. For example, +.Li 5,7d +means delete lines 5--7 of file 1. +.El +.Pp +.Em Forward Xr ed Scripts +.Pp +.Xr diff +can produce output that is like an +.Xr ed +script, but with hunks in forward (front to back) order. The format of the +commands is also changed slightly: command characters precede the lines they +modify, spaces separate line numbers in ranges, and no attempt is made to +disambiguate hunk lines consisting of a single period. Like +.Xr ed +format, forward +.Xr ed +format cannot represent incomplete lines. +.Pp +Forward +.Xr ed +format is not very useful, because neither +.Xr ed +nor +.Xr patch +can apply diffs in this format. It exists mainly for compatibility with older +versions of +.Xr diff . +Use the +.Op -f +or +.Op --forward-ed +option to select it. +.Pp +.Em RCS Scripts +.Pp +The RCS output format is designed specifically for use by the Revision Control +System, which is a set of free programs used for organizing different versions +and systems of files. Use the +.Op -n +or +.Op --rcs +option to select this output format. It is like the forward +.Xr ed +format (see Section +.Dq Forward ed ) , +but it can represent arbitrary changes to the contents of a file because it +avoids the forward +.Xr ed +format's problems with lines consisting of a single period and with incomplete +lines. Instead of ending text sections with a line consisting of a single +period, each command specifies the number of lines it affects; a combination +of the +.Li a +and +.Li d +commands are used instead of +.Li c . +Also, if the second file ends in a changed incomplete line, then the output +also ends in an incomplete line. +.Pp +Here is the output of +.Li diff -n lao tzu +(see Section +.Dq Sample diff Input , +for the complete contents of the two files): +.Pp +.Bd -literal -offset indent +d1 2 +d4 1 +a4 2 +The named is the mother of all things. + +a11 3 +They both may be called deep and profound. +Deeper and more profound, +The door of all subtleties! +.Ed +.Pp +.Ss Merging Files with If-then-else +You can use +.Xr diff +to merge two files of C source code. The output of +.Xr diff +in this format contains all the lines of both files. Lines common to both +files are output just once; the differing parts are separated by the C preprocessor +directives +.Li #ifdef Va name +or +.Li #ifndef Va name , +.Li #else , +and +.Li #endif . +When compiling the output, you select which version to use by either defining +or leaving undefined the macro +.Va name . +.Pp +To merge two files, use +.Xr diff +with the +.Op -D Va name +or +.Op --ifdef= Va name +option. The argument +.Va name +is the C preprocessor identifier to use in the +.Li #ifdef +and +.Li #ifndef +directives. +.Pp +For example, if you change an instance of +.Li wait (&s) +to +.Li waitpid (-1, &s, 0) +and then merge the old and new files with the +.Op --ifdef=HAVE_WAITPID +option, then the affected part of your code might look like this: +.Pp +.Bd -literal -offset indent + do { +#ifndef HAVE_WAITPID + if ((w = wait (&s)) < 0 && errno != EINTR) +#else /* HAVE_WAITPID */ + if ((w = waitpid (-1, &s, 0)) < 0 && errno != EINTR) +#endif /* HAVE_WAITPID */ + return w; + } while (w != child); +.Ed +.Pp +You can specify formats for languages other than C by using line group formats +and line formats, as described in the next sections. +.Pp +.Em Line Group Formats +.Pp +Line group formats let you specify formats suitable for many applications +that allow if-then-else input, including programming languages and text formatting +languages. A line group format specifies the output format for a contiguous +group of similar lines. +.Pp +For example, the following command compares the TeX files +.Pa old +and +.Pa new , +and outputs a merged file in which old regions are surrounded by +.Li \ebegin{em} +- +.Li \eend{em} +lines, and new regions are surrounded by +.Li \ebegin{bf} +- +.Li \eend{bf} +lines. +.Pp +.Bd -literal -offset indent +diff \e + --old-group-format='\ebegin{em} +%<\eend{em} +\&' \e + --new-group-format='\ebegin{bf} +%>\eend{bf} +\&' \e + old new +.Ed +.Pp +The following command is equivalent to the above example, but it is a little +more verbose, because it spells out the default line group formats. +.Pp +.Bd -literal -offset indent +diff \e + --old-group-format='\ebegin{em} +%<\eend{em} +\&' \e + --new-group-format='\ebegin{bf} +%>\eend{bf} +\&' \e + --unchanged-group-format='%=' \e + --changed-group-format='\ebegin{em} +%<\eend{em} +\ebegin{bf} +%>\eend{bf} +\&' \e + old new +.Ed +.Pp +Here is a more advanced example, which outputs a diff listing with headers +containing line numbers in a \(lqplain English\(rq style. +.Pp +.Bd -literal -offset indent +diff \e + --unchanged-group-format=\(rq \e + --old-group-format='-------- %dn line%(n=1?:s) deleted at %df: +%<' \e + --new-group-format='-------- %dN line%(N=1?:s) added after %de: +%>' \e + --changed-group-format='-------- %dn line%(n=1?:s) changed at %df: +%<-------- to: +%>' \e + old new +.Ed +.Pp +To specify a line group format, use +.Xr diff +with one of the options listed below. You can specify up to four line group +formats, one for each kind of line group. You should quote +.Va format , +because it typically contains shell metacharacters. +.Pp +.Bl -tag -width Ds +.It --old-group-format= Va format +These line groups are hunks containing only lines from the first file. The +default old group format is the same as the changed group format if it is +specified; otherwise it is a format that outputs the line group as-is. +.Pp +.It --new-group-format= Va format +These line groups are hunks containing only lines from the second file. The +default new group format is same as the changed group format if it is specified; +otherwise it is a format that outputs the line group as-is. +.Pp +.It --changed-group-format= Va format +These line groups are hunks containing lines from both files. The default +changed group format is the concatenation of the old and new group formats. +.Pp +.It --unchanged-group-format= Va format +These line groups contain lines common to both files. The default unchanged +group format is a format that outputs the line group as-is. +.El +.Pp +In a line group format, ordinary characters represent themselves; conversion +specifications start with +.Li % +and have one of the following forms. +.Pp +.Bl -tag -width Ds +.It %< +stands for the lines from the first file, including the trailing newline. +Each line is formatted according to the old line format (see Section +.Dq Line Formats ) . +.Pp +.It %> +stands for the lines from the second file, including the trailing newline. +Each line is formatted according to the new line format. +.Pp +.It %= +stands for the lines common to both files, including the trailing newline. +Each line is formatted according to the unchanged line format. +.Pp +.It %% +stands for +.Li % . +.Pp +.It %c' Va C' +where +.Va C +is a single character, stands for +.Va C . +.Va C +may not be a backslash or an apostrophe. For example, +.Li %c':' +stands for a colon, even inside the then-part of an if-then-else format, which +a colon would normally terminate. +.Pp +.It %c'\e Va O' +where +.Va O +is a string of 1, 2, or 3 octal digits, stands for the character with octal +code +.Va O . +For example, +.Li %c'\e0' +stands for a null character. +.Pp +.It Va F Va n +where +.Va F +is a +.Li printf +conversion specification and +.Va n +is one of the following letters, stands for +.Va n +\&'s value formatted with +.Va F . +.Pp +.Bl -tag -width Ds +.It e +The line number of the line just before the group in the old file. +.Pp +.It f +The line number of the first line in the group in the old file; equals +.Va e ++ 1. +.Pp +.It l +The line number of the last line in the group in the old file. +.Pp +.It m +The line number of the line just after the group in the old file; equals +.Va l ++ 1. +.Pp +.It n +The number of lines in the group in the old file; equals +.Va l +- +.Va f ++ 1. +.Pp +.It E, F, L, M, N +Likewise, for lines in the new file. +.Pp +.El +The +.Li printf +conversion specification can be +.Li %d , +.Li %o , +.Li %x , +or +.Li %X , +specifying decimal, octal, lower case hexadecimal, or upper case hexadecimal +output respectively. After the +.Li % +the following options can appear in sequence: a series of zero or more flags; +an integer specifying the minimum field width; and a period followed by an +optional integer specifying the minimum number of digits. The flags are +.Li - +for left-justification, +.Li ' +for separating the digit into groups as specified by the +.Ev LC_NUMERIC +locale category, and +.Li 0 +for padding with zeros instead of spaces. For example, +.Li %5dN +prints the number of new lines in the group in a field of width 5 characters, +using the +.Li printf +format +.Li "%5d" . +.Pp +.It ( Va A= Va B? Va T: Va E) +If +.Va A +equals +.Va B +then +.Va T +else +.Va E . +.Va A +and +.Va B +are each either a decimal constant or a single letter interpreted as above. +This format spec is equivalent to +.Va T +if +.Va A +\&'s value equals +.Va B +\&'s; otherwise it is equivalent to +.Va E . +.Pp +For example, +.Li %(N=0?no:%dN) line%(N=1?:s) +is equivalent to +.Li no lines +if +.Va N +(the number of lines in the group in the new file) is 0, to +.Li 1 line +if +.Va N +is 1, and to +.Li %dN lines +otherwise. +.El +.Pp +.Em Line Formats +.Pp +Line formats control how each line taken from an input file is output as part +of a line group in if-then-else format. +.Pp +For example, the following command outputs text with a one-character change +indicator to the left of the text. The first character of output is +.Li - +for deleted lines, +.Li | +for added lines, and a space for unchanged lines. The formats contain newline +characters where newlines are desired on output. +.Pp +.Bd -literal -offset indent +diff \e + --old-line-format='-%l +\&' \e + --new-line-format='|%l +\&' \e + --unchanged-line-format=' %l +\&' \e + old new +.Ed +.Pp +To specify a line format, use one of the following options. You should quote +.Va format , +since it often contains shell metacharacters. +.Pp +.Bl -tag -width Ds +.It --old-line-format= Va format +formats lines just from the first file. +.Pp +.It --new-line-format= Va format +formats lines just from the second file. +.Pp +.It --unchanged-line-format= Va format +formats lines common to both files. +.Pp +.It --line-format= Va format +formats all lines; in effect, it sets all three above options simultaneously. +.El +.Pp +In a line format, ordinary characters represent themselves; conversion specifications +start with +.Li % +and have one of the following forms. +.Pp +.Bl -tag -width Ds +.It %l +stands for the contents of the line, not counting its trailing newline (if +any). This format ignores whether the line is incomplete;See Section +.Dq Incomplete Lines . +.Pp +.It %L +stands for the contents of the line, including its trailing newline (if any). +If a line is incomplete, this format preserves its incompleteness. +.Pp +.It %% +stands for +.Li % . +.Pp +.It %c' Va C' +where +.Va C +is a single character, stands for +.Va C . +.Va C +may not be a backslash or an apostrophe. For example, +.Li %c':' +stands for a colon. +.Pp +.It %c'\e Va O' +where +.Va O +is a string of 1, 2, or 3 octal digits, stands for the character with octal +code +.Va O . +For example, +.Li %c'\e0' +stands for a null character. +.Pp +.It Va Fn +where +.Va F +is a +.Li printf +conversion specification, stands for the line number formatted with +.Va F . +For example, +.Li %.5dn +prints the line number using the +.Li printf +format +.Li "%.5d" . +See Section.Dq Line Group Formats , +for more about printf conversion specifications. +.Pp +.El +The default line format is +.Li %l +followed by a newline character. +.Pp +If the input contains tab characters and it is important that they line up +on output, you should ensure that +.Li %l +or +.Li %L +in a line format is just after a tab stop (e.g. by preceding +.Li %l +or +.Li %L +with a tab character), or you should use the +.Op -t +or +.Op --expand-tabs +option. +.Pp +Taken together, the line and line group formats let you specify many different +formats. For example, the following command uses a format similar to normal +.Xr diff +format. You can tailor this command to get fine control over +.Xr diff +output. +.Pp +.Bd -literal -offset indent +diff \e + --old-line-format='< %l +\&' \e + --new-line-format='> %l +\&' \e + --old-group-format='%df%(f=l?:,%dl)d%dE +%<' \e + --new-group-format='%dea%dF%(F=L?:,%dL) +%>' \e + --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL) +%<--- +%>' \e + --unchanged-group-format=\(rq \e + old new +.Ed +.Pp +.Em An Example of If-then-else Format +.Pp +Here is the output of +.Li diff -DTWO lao tzu +(see Section +.Dq Sample diff Input , +for the complete contents of the two files): +.Pp +.Bd -literal -offset indent +#ifndef TWO +The Way that can be told of is not the eternal Way; +The name that can be named is not the eternal name. +#endif /* ! TWO */ +The Nameless is the origin of Heaven and Earth; +#ifndef TWO +The Named is the mother of all things. +#else /* TWO */ +The named is the mother of all things. + +#endif /* TWO */ +Therefore let there always be non-being, + so we may see their subtlety, +And let there always be being, + so we may see their outcome. +The two are the same, +But after they are produced, + they have different names. +#ifdef TWO +They both may be called deep and profound. +Deeper and more profound, +The door of all subtleties! +#endif /* TWO */ +.Ed +.Pp +.Em Detailed Description of If-then-else Format +.Pp +For lines common to both files, +.Xr diff +uses the unchanged line group format. For each hunk of differences in the +merged output format, if the hunk contains only lines from the first file, +.Xr diff +uses the old line group format; if the hunk contains only lines from the second +file, +.Xr diff +uses the new group format; otherwise, +.Xr diff +uses the changed group format. +.Pp +The old, new, and unchanged line formats specify the output format of lines +from the first file, lines from the second file, and lines common to both +files, respectively. +.Pp +The option +.Op --ifdef= Va name +is equivalent to the following sequence of options using shell syntax: +.Pp +.Bd -literal -offset indent +--old-group-format='#ifndef name +%<#endif /* ! name */ +\&' \e +--new-group-format='#ifdef name +%>#endif /* name */ +\&' \e +--unchanged-group-format='%=' \e +--changed-group-format='#ifndef name +%<#else /* name */ +%>#endif /* name */ +\&' +.Ed +.Pp +You should carefully check the +.Xr diff +output for proper nesting. For example, when using the +.Op -D Va name +or +.Op --ifdef= Va name +option, you should check that if the differing lines contain any of the C +preprocessor directives +.Li #ifdef , +.Li #ifndef , +.Li #else , +.Li #elif , +or +.Li #endif , +they are nested properly and match. If they don't, you must make corrections +manually. It is a good idea to carefully check the resulting code anyway to +make sure that it really does what you want it to; depending on how the input +files were produced, the output might contain duplicate or otherwise incorrect +code. +.Pp +The +.Xr patch +.Op -D Va name +option behaves like the +.Xr diff +.Op -D Va name +option, except it operates on a file and a diff to produce a merged file;See Section +.Dq patch Options . +.Pp +.Sh Incomplete Lines +When an input file ends in a non-newline character, its last line is called +an +.Em incomplete line +because its last character is not a newline. All other lines are called +.Em full lines +and end in a newline character. Incomplete lines do not match full lines unless +differences in white space are ignored (see Section +.Dq White Space ) . +.Pp +An incomplete line is normally distinguished on output from a full line by +a following line that starts with +.Li \e . +However, the RCS format (see Section +.Dq RCS ) +outputs the incomplete line as-is, without any trailing newline or following +line. The side by side format normally represents incomplete lines as-is, +but in some cases uses a +.Li \e +or +.Li / +gutter marker;See Section +.Dq Side by Side . +The if-then-else line format preserves a line's incompleteness with +.Li %L , +and discards the newline with +.Li %l +;See Section +.Dq Line Formats . +Finally, with the +.Xr ed +and forward +.Xr ed +output formats (see Section +.Dq Output Formats ) +.Xr diff +cannot represent an incomplete line, so it pretends there was a newline and +reports an error. +.Pp +For example, suppose +.Pa F +and +.Pa G +are one-byte files that contain just +.Li f +and +.Li g , +respectively. Then +.Li diff F G +outputs +.Pp +.Bd -literal -offset indent +1c1 +< f +\e No newline at end of file +--- +> g +\e No newline at end of file +.Ed +.Pp +(The exact message may differ in non-English locales.) +.Li diff -n F G +outputs the following without a trailing newline: +.Pp +.Bd -literal -offset indent +d1 1 +a1 1 +g +.Ed +.Pp +.Li diff -e F G +reports two errors and outputs the following: +.Pp +.Bd -literal -offset indent +1c +g +\&. +.Ed +.Pp +.Sh Comparing Directories +You can use +.Xr diff +to compare some or all of the files in two directory trees. When both file +name arguments to +.Xr diff +are directories, it compares each file that is contained in both directories, +examining file names in alphabetical order as specified by the +.Ev LC_COLLATE +locale category. Normally +.Xr diff +is silent about pairs of files that contain no differences, but if you use +the +.Op -s +or +.Op --report-identical-files +option, it reports pairs of identical files. Normally +.Xr diff +reports subdirectories common to both directories without comparing subdirectories' +files, but if you use the +.Op -r +or +.Op --recursive +option, it compares every corresponding pair of files in the directory trees, +as many levels deep as they go. +.Pp +For file names that are in only one of the directories, +.Xr diff +normally does not show the contents of the file that exists; it reports only +that the file exists in that directory and not in the other. You can make +.Xr diff +act as though the file existed but was empty in the other directory, so that +it outputs the entire contents of the file that actually exists. (It is output +as either an insertion or a deletion, depending on whether it is in the first +or the second directory given.) To do this, use the +.Op -N +or +.Op --new-file +option. +.Pp +If the older directory contains one or more large files that are not in the +newer directory, you can make the patch smaller by using the +.Op --unidirectional-new-file +option instead of +.Op -N . +This option is like +.Op -N +except that it only inserts the contents of files that appear in the second +directory but not the first (that is, files that were added). At the top of +the patch, write instructions for the user applying the patch to remove the +files that were deleted before applying the patch.See Section +.Dq Making Patches , +for more discussion of making patches for distribution. +.Pp +To ignore some files while comparing directories, use the +.Op -x Va pattern +or +.Op --exclude= Va pattern +option. This option ignores any files or subdirectories whose base names match +the shell pattern +.Va pattern . +Unlike in the shell, a period at the start of the base of a file name matches +a wildcard at the start of a pattern. You should enclose +.Va pattern +in quotes so that the shell does not expand it. For example, the option +.Op -x '*.[ao]' +ignores any file whose name ends with +.Li .a +or +.Li .o . +.Pp +This option accumulates if you specify it more than once. For example, using +the options +.Op -x 'RCS' -x '*,v' +ignores any file or subdirectory whose base name is +.Li RCS +or ends with +.Li ,v . +.Pp +If you need to give this option many times, you can instead put the patterns +in a file, one pattern per line, and use the +.Op -X Va file +or +.Op --exclude-from= Va file +option. Trailing white space and empty lines are ignored in the pattern file. +.Pp +If you have been comparing two directories and stopped partway through, later +you might want to continue where you left off. You can do this by using the +.Op -S Va file +or +.Op --starting-file= Va file +option. This compares only the file +.Va file +and all alphabetically later files in the topmost directory level. +.Pp +If two directories differ only in that file names are lower case in one directory +and upper case in the upper, +.Xr diff +normally reports many differences because it compares file names in a case +sensitive way. With the +.Op --ignore-file-name-case +option, +.Xr diff +ignores case differences in file names, so that for example the contents of +the file +.Pa Tao +in one directory are compared to the contents of the file +.Pa TAO +in the other. The +.Op --no-ignore-file-name-case +option cancels the effect of the +.Op --ignore-file-name-case +option, reverting to the default behavior. +.Pp +If an +.Op -x Va pattern +or +.Op --exclude= Va pattern +option, or an +.Op -X Va file +or +.Op --exclude-from= Va file +option, is specified while the +.Op --ignore-file-name-case +option is in effect, case is ignored when excluding file names matching the +specified patterns. +.Pp +.Sh Making Xr diff Output Prettier +.Xr diff +provides several ways to adjust the appearance of its output. These adjustments +can be applied to any output format. +.Pp +.Ss Preserving Tab Stop Alignment +The lines of text in some of the +.Xr diff +output formats are preceded by one or two characters that indicate whether +the text is inserted, deleted, or changed. The addition of those characters +can cause tabs to move to the next tab stop, throwing off the alignment of +columns in the line. GNU +.Xr diff +provides two ways to make tab-aligned columns line up correctly. +.Pp +The first way is to have +.Xr diff +convert all tabs into the correct number of spaces before outputting them; +select this method with the +.Op -t +or +.Op --expand-tabs +option. To use this form of output with +.Xr patch , +you must give +.Xr patch +the +.Op -l +or +.Op --ignore-white-space +option (see Section +.Dq Changed White Space , +for more information). +.Xr diff +normally assumes that tab stops are set every 8 print columns, but this can +be altered by the +.Op --tabsize= Va columns +option. +.Pp +The other method for making tabs line up correctly is to add a tab character +instead of a space after the indicator character at the beginning of the line. +This ensures that all following tab characters are in the same position relative +to tab stops that they were in the original files, so that the output is aligned +correctly. Its disadvantage is that it can make long lines too long to fit +on one line of the screen or the paper. It also does not work with the unified +output format, which does not have a space character after the change type +indicator character. Select this method with the +.Op -T +or +.Op --initial-tab +option. +.Pp +.Ss Paginating Xr diff Output +It can be convenient to have long output page-numbered and time-stamped. The +.Op -l +or +.Op --paginate +option does this by sending the +.Xr diff +output through the +.Xr pr +program. Here is what the page header might look like for +.Li diff -lc lao tzu : +.Pp +.Bd -literal -offset indent +2002-02-22 14:20 diff -lc lao tzu Page 1 +.Ed +.Pp +.Sh Xr diff Performance Tradeoffs +GNU +.Xr diff +runs quite efficiently; however, in some circumstances you can cause it to +run faster or produce a more compact set of changes. +.Pp +One way to improve +.Xr diff +performance is to use hard or symbolic links to files instead of copies. This +improves performance because +.Xr diff +normally does not need to read two hard or symbolic links to the same file, +since their contents must be identical. For example, suppose you copy a large +directory hierarchy, make a few changes to the copy, and then often use +.Li diff -r +to compare the original to the copy. If the original files are read-only, +you can greatly improve performance by creating the copy using hard or symbolic +links (e.g., with GNU +.Li cp -lR +or +.Li cp -sR ) . +Before editing a file in the copy for the first time, you should break the +link and replace it with a regular copy. +.Pp +You can also affect the performance of GNU +.Xr diff +by giving it options that change the way it compares files. Performance has +more than one dimension. These options improve one aspect of performance at +the cost of another, or they improve performance in some cases while hurting +it in others. +.Pp +The way that GNU +.Xr diff +determines which lines have changed always comes up with a near-minimal set +of differences. Usually it is good enough for practical purposes. If the +.Xr diff +output is large, you might want +.Xr diff +to use a modified algorithm that sometimes produces a smaller set of differences. +The +.Op -d +or +.Op --minimal +option does this; however, it can also cause +.Xr diff +to run more slowly than usual, so it is not the default behavior. +.Pp +When the files you are comparing are large and have small groups of changes +scattered throughout them, you can use the +.Op --speed-large-files +option to make a different modification to the algorithm that +.Xr diff +uses. If the input files have a constant small density of changes, this option +speeds up the comparisons without changing the output. If not, +.Xr diff +might produce a larger set of differences; however, the output will still +be correct. +.Pp +Normally +.Xr diff +discards the prefix and suffix that is common to both files before it attempts +to find a minimal set of differences. This makes +.Xr diff +run faster, but occasionally it may produce non-minimal output. The +.Op --horizon-lines= Va lines +option prevents +.Xr diff +from discarding the last +.Va lines +lines of the prefix and the first +.Va lines +lines of the suffix. This gives +.Xr diff +further opportunities to find a minimal output. +.Pp +Suppose a run of changed lines includes a sequence of lines at one end and +there is an identical sequence of lines just outside the other end. The +.Xr diff +command is free to choose which identical sequence is included in the hunk. +In this case, +.Xr diff +normally shifts the hunk's boundaries when this merges adjacent hunks, or +shifts a hunk's lines towards the end of the file. Merging hunks can make +the output look nicer in some cases. +.Pp +.Sh Comparing Three Files +Use the program +.Xr diff3 +to compare three files and show any differences among them. ( +.Xr diff3 +can also merge files; see diff3 Merging). +.Pp +The \(lqnormal\(rq +.Xr diff3 +output format shows each hunk of differences without surrounding context. +Hunks are labeled depending on whether they are two-way or three-way, and +lines are annotated by their location in the input files. +.Pp +See Section.Dq Invoking diff3 , +for more information on how to run +.Xr diff3 . +.Pp +.Ss A Third Sample Input File +Here is a third sample file that will be used in examples to illustrate the +output of +.Xr diff3 +and how various options can change it. The first two files are the same that +we used for +.Xr diff +(see Section +.Dq Sample diff Input ) . +This is the third sample file, called +.Pa tao : +.Pp +.Bd -literal -offset indent +The Way that can be told of is not the eternal Way; +The name that can be named is not the eternal name. +The Nameless is the origin of Heaven and Earth; +The named is the mother of all things. + +Therefore let there always be non-being, + so we may see their subtlety, +And let there always be being, + so we may see their result. +The two are the same, +But after they are produced, + they have different names. + + -- The Way of Lao-Tzu, tr. Wing-tsit Chan +.Ed +.Pp +.Ss An Example of Xr diff3 Normal Format +Here is the output of the command +.Li diff3 lao tzu tao +(see Section +.Dq Sample diff3 Input , +for the complete contents of the files). Notice that it shows only the lines +that are different among the three files. +.Pp +.Bd -literal -offset indent +====2 +1:1,2c +3:1,2c + The Way that can be told of is not the eternal Way; + The name that can be named is not the eternal name. +2:0a +====1 +1:4c + The Named is the mother of all things. +2:2,3c +3:4,5c + The named is the mother of all things. + +====3 +1:8c +2:7c + so we may see their outcome. +3:9c + so we may see their result. +==== +1:11a +2:11,13c + They both may be called deep and profound. + Deeper and more profound, + The door of all subtleties! +3:13,14c + + -- The Way of Lao-Tzu, tr. Wing-tsit Chan +.Ed +.Pp +.Ss Detailed Description of Xr diff3 Normal Format +Each hunk begins with a line marked +.Li ==== . +Three-way hunks have plain +.Li ==== +lines, and two-way hunks have +.Li 1 , +.Li 2 , +or +.Li 3 +appended to specify which of the three input files differ in that hunk. The +hunks contain copies of two or three sets of input lines each preceded by +one or two commands identifying where the lines came from. +.Pp +Normally, two spaces precede each copy of an input line to distinguish it +from the commands. But with the +.Op -T +or +.Op --initial-tab +option, +.Xr diff3 +uses a tab instead of two spaces; this lines up tabs correctly.See Section +.Dq Tabs , +for more information. +.Pp +Commands take the following forms: +.Pp +.Bl -tag -width Ds +.It Va file: Va la +This hunk appears after line +.Va l +of file +.Va file , +and contains no lines in that file. To edit this file to yield the other files, +one must append hunk lines taken from the other files. For example, +.Li 1:11a +means that the hunk follows line 11 in the first file and contains no lines +from that file. +.Pp +.It Va file: Va rc +This hunk contains the lines in the range +.Va r +of file +.Va file . +The range +.Va r +is a comma-separated pair of line numbers, or just one number if the range +is a singleton. To edit this file to yield the other files, one must change +the specified lines to be the lines taken from the other files. For example, +.Li 2:11,13c +means that the hunk contains lines 11 through 13 from the second file. +.El +.Pp +If the last line in a set of input lines is incomplete (see Section +.Dq Incomplete Lines ) , +it is distinguished on output from a full line by a following line that starts +with +.Li \e . +.Pp +.Ss Xr diff3 Hunks +Groups of lines that differ in two or three of the input files are called +.Em diff3 hunks , +by analogy with +.Xr diff +hunks (see Section +.Dq Hunks ) . +If all three input files differ in a +.Xr diff3 +hunk, the hunk is called a +.Em three-way hunk +; if just two input files differ, it is a +.Em two-way hunk . +.Pp +As with +.Xr diff , +several solutions are possible. When comparing the files +.Li A , +.Li B , +and +.Li C , +.Xr diff3 +normally finds +.Xr diff3 +hunks by merging the two-way hunks output by the two commands +.Li diff A B +and +.Li diff A C . +This does not necessarily minimize the size of the output, but exceptions +should be rare. +.Pp +For example, suppose +.Pa F +contains the three lines +.Li a , +.Li b , +.Li f , +.Pa G +contains the lines +.Li g , +.Li b , +.Li g , +and +.Pa H +contains the lines +.Li a , +.Li b , +.Li h . +.Li diff3 F G H +might output the following: +.Pp +.Bd -literal -offset indent +====2 +1:1c +3:1c + a +2:1c + g +==== +1:3c + f +2:3c + g +3:3c + h +.Ed +.Pp +because it found a two-way hunk containing +.Li a +in the first and third files and +.Li g +in the second file, then the single line +.Li b +common to all three files, then a three-way hunk containing the last line +of each file. +.Pp +.Sh Merging From a Common Ancestor +When two people have made changes to copies of the same file, +.Xr diff3 +can produce a merged output that contains both sets of changes together with +warnings about conflicts. +.Pp +One might imagine programs with names like +.Xr diff4 +and +.Xr diff5 +to compare more than three files simultaneously, but in practice the need +rarely arises. You can use +.Xr diff3 +to merge three or more sets of changes to a file by merging two change sets +at a time. +.Pp +.Xr diff3 +can incorporate changes from two modified versions into a common preceding +version. This lets you merge the sets of changes represented by the two newer +files. Specify the common ancestor version as the second argument and the +two newer versions as the first and third arguments, like this: +.Pp +.Bd -literal -offset indent +diff3 mine older yours +.Ed +.Pp +You can remember the order of the arguments by noting that they are in alphabetical +order. +.Pp +You can think of this as subtracting +.Va older +from +.Va yours +and adding the result to +.Va mine , +or as merging into +.Va mine +the changes that would turn +.Va older +into +.Va yours . +This merging is well-defined as long as +.Va mine +and +.Va older +match in the neighborhood of each such change. This fails to be true when +all three input files differ or when only +.Va older +differs; we call this a +.Em conflict . +When all three input files differ, we call the conflict an +.Em overlap . +.Pp +.Xr diff3 +gives you several ways to handle overlaps and conflicts. You can omit overlaps +or conflicts, or select only overlaps, or mark conflicts with special +.Li <<<<<<< +and +.Li >>>>>>> +lines. +.Pp +.Xr diff3 +can output the merge results as an +.Xr ed +script that that can be applied to the first file to yield the merged output. +However, it is usually better to have +.Xr diff3 +generate the merged output directly; this bypasses some problems with +.Xr ed . +.Pp +.Ss Selecting Which Changes to Incorporate +You can select all unmerged changes from +.Va older +to +.Va yours +for merging into +.Va mine +with the +.Op -e +or +.Op --ed +option. You can select only the nonoverlapping unmerged changes with +.Op -3 +or +.Op --easy-only , +and you can select only the overlapping changes with +.Op -x +or +.Op --overlap-only . +.Pp +The +.Op -e , +.Op -3 +and +.Op -x +options select only +.Em unmerged changes , +i.e. changes where +.Va mine +and +.Va yours +differ; they ignore changes from +.Va older +to +.Va yours +where +.Va mine +and +.Va yours +are identical, because they assume that such changes have already been merged. +If this assumption is not a safe one, you can use the +.Op -A +or +.Op --show-all +option (see Section +.Dq Marking Conflicts ) . +.Pp +Here is the output of the command +.Xr diff3 +with each of these three options (see Section +.Dq Sample diff3 Input , +for the complete contents of the files). Notice that +.Op -e +outputs the union of the disjoint sets of changes output by +.Op -3 +and +.Op -x . +.Pp +Output of +.Li diff3 -e lao tzu tao : +.Bd -literal -offset indent +11a + + -- The Way of Lao-Tzu, tr. Wing-tsit Chan +\&. +8c + so we may see their result. +\&. +.Ed +.Pp +Output of +.Li diff3 -3 lao tzu tao : +.Bd -literal -offset indent +8c + so we may see their result. +\&. +.Ed +.Pp +Output of +.Li diff3 -x lao tzu tao : +.Bd -literal -offset indent +11a + + -- The Way of Lao-Tzu, tr. Wing-tsit Chan +\&. +.Ed +.Pp +.Ss Marking Conflicts +.Xr diff3 +can mark conflicts in the merged output by bracketing them with special marker +lines. A conflict that comes from two files +.Va A +and +.Va B +is marked as follows: +.Pp +.Bd -literal -offset indent +<<<<<<< A +lines from A +======= +lines from B +>>>>>>> B +.Ed +.Pp +A conflict that comes from three files +.Va A , +.Va B +and +.Va C +is marked as follows: +.Pp +.Bd -literal -offset indent +<<<<<<< A +lines from A +||||||| B +lines from B +======= +lines from C +>>>>>>> C +.Ed +.Pp +The +.Op -A +or +.Op --show-all +option acts like the +.Op -e +option, except that it brackets conflicts, and it outputs all changes from +.Va older +to +.Va yours , +not just the unmerged changes. Thus, given the sample input files (see Section +.Dq Sample diff3 Input ) , +.Li diff3 -A lao tzu tao +puts brackets around the conflict where only +.Pa tzu +differs: +.Pp +.Bd -literal -offset indent +<<<<<<< tzu +======= +The Way that can be told of is not the eternal Way; +The name that can be named is not the eternal name. +>>>>>>> tao +.Ed +.Pp +And it outputs the three-way conflict as follows: +.Pp +.Bd -literal -offset indent +<<<<<<< lao +||||||| tzu +They both may be called deep and profound. +Deeper and more profound, +The door of all subtleties! +======= + + -- The Way of Lao-Tzu, tr. Wing-tsit Chan +>>>>>>> tao +.Ed +.Pp +The +.Op -E +or +.Op --show-overlap +option outputs less information than the +.Op -A +or +.Op --show-all +option, because it outputs only unmerged changes, and it never outputs the +contents of the second file. Thus the +.Op -E +option acts like the +.Op -e +option, except that it brackets the first and third files from three-way overlapping +changes. Similarly, +.Op -X +acts like +.Op -x , +except it brackets all its (necessarily overlapping) changes. For example, +for the three-way overlapping change above, the +.Op -E +and +.Op -X +options output the following: +.Pp +.Bd -literal -offset indent +<<<<<<< lao +======= + + -- The Way of Lao-Tzu, tr. Wing-tsit Chan +>>>>>>> tao +.Ed +.Pp +If you are comparing files that have meaningless or uninformative names, you +can use the +.Op --label= Va label +option to show alternate names in the +.Li <<<<<<< , +.Li ||||||| +and +.Li >>>>>>> +brackets. This option can be given up to three times, once for each input +file. Thus +.Li diff3 -A --label X --label Y --label Z A B C +acts like +.Li diff3 -A A B C , +except that the output looks like it came from files named +.Li X , +.Li Y +and +.Li Z +rather than from files named +.Li A , +.Li B +and +.Li C . +.Pp +.Ss Generating the Merged Output Directly +With the +.Op -m +or +.Op --merge +option, +.Xr diff3 +outputs the merged file directly. This is more efficient than using +.Xr ed +to generate it, and works even with non-text files that +.Xr ed +would reject. If you specify +.Op -m +without an +.Xr ed +script option, +.Op -A +is assumed. +.Pp +For example, the command +.Li diff3 -m lao tzu tao +(see Section +.Dq Sample diff3 Input +for a copy of the input files) would output the following: +.Pp +.Bd -literal -offset indent +<<<<<<< tzu +======= +The Way that can be told of is not the eternal Way; +The name that can be named is not the eternal name. +>>>>>>> tao +The Nameless is the origin of Heaven and Earth; +The Named is the mother of all things. +Therefore let there always be non-being, + so we may see their subtlety, +And let there always be being, + so we may see their result. +The two are the same, +But after they are produced, + they have different names. +<<<<<<< lao +||||||| tzu +They both may be called deep and profound. +Deeper and more profound, +The door of all subtleties! +======= + + -- The Way of Lao-Tzu, tr. Wing-tsit Chan +>>>>>>> tao +.Ed +.Pp +.Ss How Xr diff3 Merges Incomplete Lines +With +.Op -m , +incomplete lines (see Section +.Dq Incomplete Lines ) +are simply copied to the output as they are found; if the merged output ends +in an conflict and one of the input files ends in an incomplete line, succeeding +.Li ||||||| , +.Li ======= +or +.Li >>>>>>> +brackets appear somewhere other than the start of a line because they are +appended to the incomplete line. +.Pp +Without +.Op -m , +if an +.Xr ed +script option is specified and an incomplete line is found, +.Xr diff3 +generates a warning and acts as if a newline had been present. +.Pp +.Ss Saving the Changed File +Traditional Unix +.Xr diff3 +generates an +.Xr ed +script without the trailing +.Li w +and +.Li q +commands that save the changes. System V +.Xr diff3 +generates these extra commands. GNU +.Xr diff3 +normally behaves like traditional Unix +.Xr diff3 , +but with the +.Op -i +option it behaves like System V +.Xr diff3 +and appends the +.Li w +and +.Li q +commands. +.Pp +The +.Op -i +option requires one of the +.Xr ed +script options +.Op -AeExX3 , +and is incompatible with the merged output option +.Op -m . +.Pp +.Sh Interactive Merging with Xr sdiff +With +.Xr sdiff , +you can merge two files interactively based on a side-by-side +.Op -y +format comparison (see Section +.Dq Side by Side ) . +Use +.Op -o Va file +or +.Op --output= Va file +to specify where to put the merged text.See Section +.Dq Invoking sdiff , +for more details on the options to +.Xr sdiff . +.Pp +Another way to merge files interactively is to use the Emacs Lisp package +.Xr emerge . +See Section.Dq emerge , +for more information. +.Pp +.Ss Specifying Xr diff Options to Xr sdiff +The following +.Xr sdiff +options have the same meaning as for +.Xr diff . +See Section.Dq diff Options , +for the use of these options. +.Pp +.Bd -literal -offset indent +-a -b -d -i -t -v +-B -E -I regexp + +--expand-tabs +--ignore-blank-lines --ignore-case +--ignore-matching-lines=regexp --ignore-space-change +--ignore-tab-expansion +--left-column --minimal --speed-large-files +--strip-trailing-cr --suppress-common-lines +--tabsize=columns --text --version --width=columns +.Ed +.Pp +For historical reasons, +.Xr sdiff +has alternate names for some options. The +.Op -l +option is equivalent to the +.Op --left-column +option, and similarly +.Op -s +is equivalent to +.Op --suppress-common-lines . +The meaning of the +.Xr sdiff +.Op -w +and +.Op -W +options is interchanged from that of +.Xr diff : +with +.Xr sdiff , +.Op -w Va columns +is equivalent to +.Op --width= Va columns , +and +.Op -W +is equivalent to +.Op --ignore-all-space . +.Xr sdiff +without the +.Op -o +option is equivalent to +.Xr diff +with the +.Op -y +or +.Op --side-by-side +option (see Section +.Dq Side by Side ) . +.Pp +.Ss Merge Commands +Groups of common lines, with a blank gutter, are copied from the first file +to the output. After each group of differing lines, +.Xr sdiff +prompts with +.Li % +and pauses, waiting for one of the following commands. Follow each command +with RET. +.Pp +.Bl -tag -width Ds +.It e +Discard both versions. Invoke a text editor on an empty temporary file, then +copy the resulting file to the output. +.Pp +.It eb +Concatenate the two versions, edit the result in a temporary file, then copy +the edited result to the output. +.Pp +.It ed +Like +.Li eb , +except precede each version with a header that shows what file and lines the +version came from. +.Pp +.It el +.It e1 +Edit a copy of the left version, then copy the result to the output. +.Pp +.It er +.It e2 +Edit a copy of the right version, then copy the result to the output. +.Pp +.It l +.It 1 +Copy the left version to the output. +.Pp +.It q +Quit. +.Pp +.It r +.It 2 +Copy the right version to the output. +.Pp +.It s +Silently copy common lines. +.Pp +.It v +Verbosely copy common lines. This is the default. +.El +.Pp +The text editor invoked is specified by the +.Ev EDITOR +environment variable if it is set. The default is system-dependent. +.Pp +.Sh Merging with Xr patch +.Xr patch +takes comparison output produced by +.Xr diff +and applies the differences to a copy of the original file, producing a patched +version. With +.Xr patch , +you can distribute just the changes to a set of files instead of distributing +the entire file set; your correspondents can apply +.Xr patch +to update their copy of the files with your changes. +.Xr patch +automatically determines the diff format, skips any leading or trailing headers, +and uses the headers to determine which file to patch. This lets your correspondents +feed a mail message containing a difference listing directly to +.Xr patch . +.Pp +.Xr patch +detects and warns about common problems like forward patches. It saves any +patches that it could not apply. It can also maintain a +.Li patchlevel.h +file to ensure that your correspondents apply diffs in the proper order. +.Pp +.Xr patch +accepts a series of diffs in its standard input, usually separated by headers +that specify which file to patch. It applies +.Xr diff +hunks (see Section +.Dq Hunks ) +one by one. If a hunk does not exactly match the original file, +.Xr patch +uses heuristics to try to patch the file as well as it can. If no approximate +match can be found, +.Xr patch +rejects the hunk and skips to the next hunk. +.Xr patch +normally replaces each file +.Va f +with its new version, putting reject hunks (if any) into +.Li Va f.rej . +.Pp +See Section.Dq Invoking patch , +for detailed information on the options to +.Xr patch . +.Pp +.Ss Selecting the Xr patch Input Format +.Xr patch +normally determines which +.Xr diff +format the patch file uses by examining its contents. For patch files that +contain particularly confusing leading text, you might need to use one of +the following options to force +.Xr patch +to interpret the patch file as a certain format of diff. The output formats +listed here are the only ones that +.Xr patch +can understand. +.Pp +.Bl -tag -width Ds +.It -c +.It --context +context diff. +.Pp +.It -e +.It --ed +.Xr ed +script. +.Pp +.It -n +.It --normal +normal diff. +.Pp +.It -u +.It --unified +unified diff. +.El +.Pp +.Ss Revision Control +If a nonexistent input file is under a revision control system supported by +.Xr patch , +.Xr patch +normally asks the user whether to get (or check out) the file from the revision +control system. Patch currently supports RCS, ClearCase and SCCS. Under RCS +and SCCS, +.Xr patch +also asks when the input file is read-only and matches the default version +in the revision control system. +.Pp +The +.Op -g Va num +or +.Op --get= Va num +option affects access to files under supported revision control systems. If +.Va num +is positive, +.Xr patch +gets the file without asking the user; if zero, +.Xr patch +neither asks the user nor gets the file; and if negative, +.Xr patch +asks the user before getting the file. The default value of +.Va num +is given by the value of the +.Ev PATCH_GET +environment variable if it is set; if not, the default value is zero if +.Xr patch +is conforming to POSIX, negative otherwise.See Section +.Dq patch and POSIX . +.Pp +The choice of revision control system is unaffected by the +.Ev VERSION_CONTROL +environment variable (see Section +.Dq Backup Names ) . +.Pp +.Ss Applying Imperfect Patches +.Xr patch +tries to skip any leading text in the patch file, apply the diff, and then +skip any trailing text. Thus you can feed a mail message directly to +.Xr patch , +and it should work. If the entire diff is indented by a constant amount of +white space, +.Xr patch +automatically ignores the indentation. If a context diff contains trailing +carriage return on each line, +.Xr patch +automatically ignores the carriage return. If a context diff has been encapsulated +by prepending +.Li - +to lines beginning with +.Li - +as per +.Lk ftp://ftp.isi.edu/in-notes/rfc934.txt , +.Xr patch +automatically unencapsulates the input. +.Pp +However, certain other types of imperfect input require user intervention +or testing. +.Pp +.Em Applying Patches with Changed White Space +.Pp +Sometimes mailers, editors, or other programs change spaces into tabs, or +vice versa. If this happens to a patch file or an input file, the files might +look the same, but +.Xr patch +will not be able to match them properly. If this problem occurs, use the +.Op -l +or +.Op --ignore-white-space +option, which makes +.Xr patch +compare blank characters (i.e. spaces and tabs) loosely so that any nonempty +sequence of blanks in the patch file matches any nonempty sequence of blanks +in the input files. Non-blank characters must still match exactly. Each line +of the context must still match a line in the input file. +.Pp +.Em Applying Reversed Patches +.Pp +Sometimes people run +.Xr diff +with the new file first instead of second. This creates a diff that is \(lqreversed\(rq. +To apply such patches, give +.Xr patch +the +.Op -R +or +.Op --reverse +option. +.Xr patch +then attempts to swap each hunk around before applying it. Rejects come out +in the swapped format. +.Pp +Often +.Xr patch +can guess that the patch is reversed. If the first hunk of a patch fails, +.Xr patch +reverses the hunk to see if it can apply it that way. If it can, +.Xr patch +asks you if you want to have the +.Op -R +option set; if it can't, +.Xr patch +continues to apply the patch normally. This method cannot detect a reversed +patch if it is a normal diff and the first command is an append (which should +have been a delete) since appends always succeed, because a null context matches +anywhere. But most patches add or change lines rather than delete them, so +most reversed normal diffs begin with a delete, which fails, and +.Xr patch +notices. +.Pp +If you apply a patch that you have already applied, +.Xr patch +thinks it is a reversed patch and offers to un-apply the patch. This could +be construed as a feature. If you did this inadvertently and you don't want +to un-apply the patch, just answer +.Li n +to this offer and to the subsequent \(lqapply anyway\(rq question---or type +.Li C-c +to kill the +.Xr patch +process. +.Pp +.Em Helping Xr patch Find Inexact Matches +.Pp +For context diffs, and to a lesser extent normal diffs, +.Xr patch +can detect when the line numbers mentioned in the patch are incorrect, and +it attempts to find the correct place to apply each hunk of the patch. As +a first guess, it takes the line number mentioned in the hunk, plus or minus +any offset used in applying the previous hunk. If that is not the correct +place, +.Xr patch +scans both forward and backward for a set of lines matching the context given +in the hunk. +.Pp +First +.Xr patch +looks for a place where all lines of the context match. If it cannot find +such a place, and it is reading a context or unified diff, and the maximum +fuzz factor is set to 1 or more, then +.Xr patch +makes another scan, ignoring the first and last line of context. If that fails, +and the maximum fuzz factor is set to 2 or more, it makes another scan, ignoring +the first two and last two lines of context are ignored. It continues similarly +if the maximum fuzz factor is larger. +.Pp +The +.Op -F Va lines +or +.Op --fuzz= Va lines +option sets the maximum fuzz factor to +.Va lines . +This option only applies to context and unified diffs; it ignores up to +.Va lines +lines while looking for the place to install a hunk. Note that a larger fuzz +factor increases the odds of making a faulty patch. The default fuzz factor +is 2; there is no point to setting it to more than the number of lines of +context in the diff, ordinarily 3. +.Pp +If +.Xr patch +cannot find a place to install a hunk of the patch, it writes the hunk out +to a reject file (see Section +.Dq Reject Names , +for information on how reject files are named). It writes out rejected hunks +in context format no matter what form the input patch is in. If the input +is a normal or +.Xr ed +diff, many of the contexts are simply null. The line numbers on the hunks +in the reject file may be different from those in the patch file: they show +the approximate location where +.Xr patch +thinks the failed hunks belong in the new file rather than in the old one. +.Pp +If the +.Op --verbose +option is given, then as it completes each hunk +.Xr patch +tells you whether the hunk succeeded or failed, and if it failed, on which +line (in the new file) +.Xr patch +thinks the hunk should go. If this is different from the line number specified +in the diff, it tells you the offset. A single large offset +.Em may +indicate that +.Xr patch +installed a hunk in the wrong place. +.Xr patch +also tells you if it used a fuzz factor to make the match, in which case you +should also be slightly suspicious. +.Pp +.Xr patch +cannot tell if the line numbers are off in an +.Xr ed +script, and can only detect wrong line numbers in a normal diff when it finds +a change or delete command. It may have the same problem with a context diff +using a fuzz factor equal to or greater than the number of lines of context +shown in the diff (typically 3). In these cases, you should probably look +at a context diff between your original and patched input files to see if +the changes make sense. Compiling without errors is a pretty good indication +that the patch worked, but not a guarantee. +.Pp +A patch against an empty file applies to a nonexistent file, and vice versa.See Section +.Dq Creating and Removing . +.Pp +.Xr patch +usually produces the correct results, even when it must make many guesses. +However, the results are guaranteed only when the patch is applied to an exact +copy of the file that the patch was generated from. +.Pp +.Em Predicting what Xr patch will do +.Pp +It may not be obvious in advance what +.Xr patch +will do with a complicated or poorly formatted patch. If you are concerned +that the input might cause +.Xr patch +to modify the wrong files, you can use the +.Op --dry-run +option, which causes +.Xr patch +to print the results of applying patches without actually changing any files. +You can then inspect the diagnostics generated by the dry run to see whether +.Xr patch +will modify the files that you expect. If the patch does not do what you want, +you can modify the patch (or the other options to +.Xr patch ) +and try another dry run. Once you are satisfied with the proposed patch you +can apply it by invoking +.Xr patch +as before, but this time without the +.Op --dry-run +option. +.Pp +.Ss Creating and Removing Files +Sometimes when comparing two directories, a file may exist in one directory +but not the other. If you give +.Xr diff +the +.Op -N +or +.Op --new-file +option, or if you supply an old or new file that is named +.Pa /dev/null +or is empty and is dated the Epoch (1970-01-01 00:00:00 UTC), +.Xr diff +outputs a patch that adds or deletes the contents of this file. When given +such a patch, +.Xr patch +normally creates a new file or removes the old file. However, when conforming +to POSIX (see Section +.Dq patch and POSIX ) , +.Xr patch +does not remove the old file, but leaves it empty. The +.Op -E +or +.Op --remove-empty-files +option causes +.Xr patch +to remove output files that are empty after applying a patch, even if the +patch does not appear to be one that removed the file. +.Pp +If the patch appears to create a file that already exists, +.Xr patch +asks for confirmation before applying the patch. +.Pp +.Ss Updating Time Stamps on Patched Files +When +.Xr patch +updates a file, it normally sets the file's last-modified time stamp to the +current time of day. If you are using +.Xr patch +to track a software distribution, this can cause +.Xr make +to incorrectly conclude that a patched file is out of date. For example, if +.Pa syntax.c +depends on +.Pa syntax.y , +and +.Xr patch +updates +.Pa syntax.c +and then +.Pa syntax.y , +then +.Pa syntax.c +will normally appear to be out of date with respect to +.Pa syntax.y +even though its contents are actually up to date. +.Pp +The +.Op -Z +or +.Op --set-utc +option causes +.Xr patch +to set a patched file's modification and access times to the time stamps given +in context diff headers. If the context diff headers do not specify a time +zone, they are assumed to use Coordinated Universal Time (UTC, often known +as GMT). +.Pp +The +.Op -T +or +.Op --set-time +option acts like +.Op -Z +or +.Op --set-utc , +except that it assumes that the context diff headers' time stamps use local +time instead of UTC. This option is not recommended, because patches using +local time cannot easily be used by people in other time zones, and because +local time stamps are ambiguous when local clocks move backwards during daylight-saving +time adjustments. If the context diff headers specify a time zone, this option +is equivalent to +.Op -Z +or +.Op --set-utc . +.Pp +.Xr patch +normally refrains from setting a file's time stamps if the file's original +last-modified time stamp does not match the time given in the diff header, +of if the file's contents do not exactly match the patch. However, if the +.Op -f +or +.Op --force +option is given, the file's time stamps are set regardless. +.Pp +Due to the limitations of the current +.Xr diff +format, +.Xr patch +cannot update the times of files whose contents have not changed. Also, if +you set file time stamps to values other than the current time of day, you +should also remove (e.g., with +.Li make clean ) +all files that depend on the patched files, so that later invocations of +.Xr make +do not get confused by the patched files' times. +.Pp +.Ss Multiple Patches in a File +If the patch file contains more than one patch, and if you do not specify +an input file on the command line, +.Xr patch +tries to apply each patch as if they came from separate patch files. This +means that it determines the name of the file to patch for each patch, and +that it examines the leading text before each patch for file names and prerequisite +revision level (see Section +.Dq Making Patches , +for more on that topic). +.Pp +.Xr patch +uses the following rules to intuit a file name from the leading text before +a patch. First, +.Xr patch +takes an ordered list of candidate file names as follows: +.Pp +.Bl -bullet +.It +If the header is that of a context diff, +.Xr patch +takes the old and new file names in the header. A name is ignored if it does +not have enough slashes to satisfy the +.Op -p Va num +or +.Op --strip= Va num +option. The name +.Pa /dev/null +is also ignored. +.Pp +.It +If there is an +.Li Index: +line in the leading garbage and if either the old and new names are both absent +or if +.Xr patch +is conforming to POSIX, +.Xr patch +takes the name in the +.Li Index: +line. +.Pp +.It +For the purpose of the following rules, the candidate file names are considered +to be in the order (old, new, index), regardless of the order that they appear +in the header. +.El +.Pp +Then +.Xr patch +selects a file name from the candidate list as follows: +.Pp +.Bl -bullet +.It +If some of the named files exist, +.Xr patch +selects the first name if conforming to POSIX, and the best name otherwise. +.Pp +.It +If +.Xr patch +is not ignoring RCS, ClearCase, and SCCS (see Section +.Dq Revision Control ) , +and no named files exist but an RCS, ClearCase, or SCCS master is found, +.Xr patch +selects the first named file with an RCS, ClearCase, or SCCS master. +.Pp +.It +If no named files exist, no RCS, ClearCase, or SCCS master was found, some +names are given, +.Xr patch +is not conforming to POSIX, and the patch appears to create a file, +.Xr patch +selects the best name requiring the creation of the fewest directories. +.Pp +.It +If no file name results from the above heuristics, you are asked for the name +of the file to patch, and +.Xr patch +selects that name. +.El +.Pp +To determine the +.Em best +of a nonempty list of file names, +.Xr patch +first takes all the names with the fewest path name components; of those, +it then takes all the names with the shortest basename; of those, it then +takes all the shortest names; finally, it takes the first remaining name. +.Pp +See Section.Dq patch and POSIX , +to see whether +.Xr patch +is conforming to POSIX. +.Pp +.Ss Applying Patches in Other Directories +The +.Op -d Va directory +or +.Op --directory= Va directory +option to +.Xr patch +makes directory +.Va directory +the current directory for interpreting both file names in the patch file, +and file names given as arguments to other options (such as +.Op -B +and +.Op -o ) . +For example, while in a mail reading program, you can patch a file in the +.Pa /usr/src/emacs +directory directly from a message containing the patch like this: +.Pp +.Bd -literal -offset indent +| patch -d /usr/src/emacs +.Ed +.Pp +Sometimes the file names given in a patch contain leading directories, but +you keep your files in a directory different from the one given in the patch. +In those cases, you can use the +.Op -p Va number +or +.Op --strip= Va number +option to set the file name strip count to +.Va number . +The strip count tells +.Xr patch +how many slashes, along with the directory names between them, to strip from +the front of file names. A sequence of one or more adjacent slashes is counted +as a single slash. By default, +.Xr patch +strips off all leading directories, leaving just the base file names. +.Pp +For example, suppose the file name in the patch file is +.Pa /gnu/src/emacs/etc/NEWS . +Using +.Op -p0 +gives the entire file name unmodified, +.Op -p1 +gives +.Pa gnu/src/emacs/etc/NEWS +(no leading slash), +.Op -p4 +gives +.Pa etc/NEWS , +and not specifying +.Op -p +at all gives +.Pa NEWS . +.Pp +.Xr patch +looks for each file (after any slashes have been stripped) in the current +directory, or if you used the +.Op -d Va directory +option, in that directory. +.Pp +.Ss Backup Files +Normally, +.Xr patch +creates a backup file if the patch does not exactly match the original input +file, because in that case the original data might not be recovered if you +undo the patch with +.Li patch -R +(see Section +.Dq Reversed Patches ) . +However, when conforming to POSIX, +.Xr patch +does not create backup files by default.See Section +.Dq patch and POSIX . +.Pp +The +.Op -b +or +.Op --backup +option causes +.Xr patch +to make a backup file regardless of whether the patch matches the original +input. The +.Op --backup-if-mismatch +option causes +.Xr patch +to create backup files for mismatches files; this is the default when not +conforming to POSIX. The +.Op --no-backup-if-mismatch +option causes +.Xr patch +to not create backup files, even for mismatched patches; this is the default +when conforming to POSIX. +.Pp +When backing up a file that does not exist, an empty, unreadable backup file +is created as a placeholder to represent the nonexistent file. +.Pp +.Ss Backup File Names +Normally, +.Xr patch +renames an original input file into a backup file by appending to its name +the extension +.Li .orig , +or +.Li ~ +if using +.Li .orig +would make the backup file name too long. The +.Op -z Va backup-suffix +or +.Op --suffix= Va backup-suffix +option causes +.Xr patch +to use +.Va backup-suffix +as the backup extension instead. +.Pp +Alternately, you can specify the extension for backup files with the +.Ev SIMPLE_BACKUP_SUFFIX +environment variable, which the options override. +.Pp +.Xr patch +can also create numbered backup files the way GNU Emacs does. With this method, +instead of having a single backup of each file, +.Xr patch +makes a new backup file name each time it patches a file. For example, the +backups of a file named +.Pa sink +would be called, successively, +.Pa sink.~1~ , +.Pa sink.~2~ , +.Pa sink.~3~ , +etc. +.Pp +The +.Op -V Va backup-style +or +.Op --version-control= Va backup-style +option takes as an argument a method for creating backup file names. You can +alternately control the type of backups that +.Xr patch +makes with the +.Ev PATCH_VERSION_CONTROL +environment variable, which the +.Op -V +option overrides. If +.Ev PATCH_VERSION_CONTROL +is not set, the +.Ev VERSION_CONTROL +environment variable is used instead. Please note that these options and variables +control backup file names; they do not affect the choice of revision control +system (see Section +.Dq Revision Control ) . +.Pp +The values of these environment variables and the argument to the +.Op -V +option are like the GNU Emacs +.Li version-control +variable (see Section +.Dq Backup Names , +for more information on backup versions in Emacs). They also recognize synonyms +that are more descriptive. The valid values are listed below; unique abbreviations +are acceptable. +.Pp +.Bl -tag -width Ds +.It t +.It numbered +Always make numbered backups. +.Pp +.It nil +.It existing +Make numbered backups of files that already have them, simple backups of the +others. This is the default. +.Pp +.It never +.It simple +Always make simple backups. +.El +.Pp +You can also tell +.Xr patch +to prepend a prefix, such as a directory name, to produce backup file names. +The +.Op -B Va prefix +or +.Op --prefix= Va prefix +option makes backup files by prepending +.Va prefix +to them. The +.Op -Y Va prefix +or +.Op --basename-prefix= Va prefix +prepends +.Va prefix +to the last file name component of backup file names instead; for example, +.Op -Y ~ +causes the backup name for +.Pa dir/file.c +to be +.Pa dir/~file.c . +If you use either of these prefix options, the suffix-based options are ignored. +.Pp +If you specify the output file with the +.Op -o +option, that file is the one that is backed up, not the input file. +.Pp +Options that affect the names of backup files do not affect whether backups +are made. For example, if you specify the +.Op --no-backup-if-mismatch +option, none of the options described in this section have any affect, because +no backups are made. +.Pp +.Ss Reject File Names +The names for reject files (files containing patches that +.Xr patch +could not find a place to apply) are normally the name of the output file +with +.Li .rej +appended (or +.Li # +if using +.Li .rej +would make the backup file name too long). +.Pp +Alternatively, you can tell +.Xr patch +to place all of the rejected patches in a single file. The +.Op -r Va reject-file +or +.Op --reject-file= Va reject-file +option uses +.Va reject-file +as the reject file name. +.Pp +.Ss Messages and Questions from Xr patch +.Xr patch +can produce a variety of messages, especially if it has trouble decoding its +input. In a few situations where it's not sure how to proceed, +.Xr patch +normally prompts you for more information from the keyboard. There are options +to produce more or fewer messages, to have it not ask for keyboard input, +and to affect the way that file names are quoted in messages. +.Pp +.Xr patch +exits with status 0 if all hunks are applied successfully, 1 if some hunks +cannot be applied, and 2 if there is more serious trouble. When applying a +set of patches in a loop, you should check the exit status, so you don't apply +a later patch to a partially patched file. +.Pp +.Em Controlling the Verbosity of Xr patch +.Pp +You can cause +.Xr patch +to produce more messages by using the +.Op --verbose +option. For example, when you give this option, the message +.Li Hmm... +indicates that +.Xr patch +is reading text in the patch file, attempting to determine whether there is +a patch in that text, and if so, what kind of patch it is. +.Pp +You can inhibit all terminal output from +.Xr patch , +unless an error occurs, by using the +.Op -s , +.Op --quiet , +or +.Op --silent +option. +.Pp +.Em Inhibiting Keyboard Input +.Pp +There are two ways you can prevent +.Xr patch +from asking you any questions. The +.Op -f +or +.Op --force +option assumes that you know what you are doing. It causes +.Xr patch +to do the following: +.Pp +.Bl -bullet +.It +Skip patches that do not contain file names in their headers. +.Pp +.It +Patch files even though they have the wrong version for the +.Li Prereq: +line in the patch; +.Pp +.It +Assume that patches are not reversed even if they look like they are. +.El +.Pp +The +.Op -t +or +.Op --batch +option is similar to +.Op -f , +in that it suppresses questions, but it makes somewhat different assumptions: +.Pp +.Bl -bullet +.It +Skip patches that do not contain file names in their headers (the same as +.Op -f ) . +.Pp +.It +Skip patches for which the file has the wrong version for the +.Li Prereq: +line in the patch; +.Pp +.It +Assume that patches are reversed if they look like they are. +.El +.Pp +.Em Xr patch Quoting Style +.Pp +When +.Xr patch +outputs a file name in a diagnostic message, it can format the name in any +of several ways. This can be useful to output file names unambiguously, even +if they contain punctuation or special characters like newlines. The +.Op --quoting-style= Va word +option controls how names are output. The +.Va word +should be one of the following: +.Pp +.Bl -tag -width Ds +.It literal +Output names as-is. +.It shell +Quote names for the shell if they contain shell metacharacters or would cause +ambiguous output. +.It shell-always +Quote names for the shell, even if they would normally not require quoting. +.It c +Quote names as for a C language string. +.It escape +Quote as with +.Li c +except omit the surrounding double-quote characters. +.El +.Pp +You can specify the default value of the +.Op --quoting-style +option with the environment variable +.Ev QUOTING_STYLE . +If that environment variable is not set, the default value is +.Li shell , +but this default may change in a future version of +.Xr patch . +.Pp +.Ss Xr patch and the POSIX Standard +If you specify the +.Op --posix +option, or set the +.Ev POSIXLY_CORRECT +environment variable, +.Xr patch +conforms more strictly to the POSIX standard, as follows: +.Pp +.Bl -bullet +.It +Take the first existing file from the list (old, new, index) when intuiting +file names from diff headers.See Section +.Dq Multiple Patches . +.Pp +.It +Do not remove files that are removed by a diff.See Section +.Dq Creating and Removing . +.Pp +.It +Do not ask whether to get files from RCS, ClearCase, or SCCS.See Section +.Dq Revision Control . +.Pp +.It +Require that all options precede the files in the command line. +.Pp +.It +Do not backup files, even when there is a mismatch.See Section +.Dq Backups . +.Pp +.El +.Ss GNU Xr patch and Traditional Xr patch +The current version of GNU +.Xr patch +normally follows the POSIX standard.See Section +.Dq patch and POSIX , +for the few exceptions to this general rule. +.Pp +Unfortunately, POSIX redefined the behavior of +.Xr patch +in several important ways. You should be aware of the following differences +if you must interoperate with traditional +.Xr patch , +or with GNU +.Xr patch +version 2.1 and earlier. +.Pp +.Bl -bullet +.It +In traditional +.Xr patch , +the +.Op -p +option's operand was optional, and a bare +.Op -p +was equivalent to +.Op -p0 . +The +.Op -p +option now requires an operand, and +.Op -p 0 +is now equivalent to +.Op -p0 . +For maximum compatibility, use options like +.Op -p0 +and +.Op -p1 . +.Pp +Also, traditional +.Xr patch +simply counted slashes when stripping path prefixes; +.Xr patch +now counts pathname components. That is, a sequence of one or more adjacent +slashes now counts as a single slash. For maximum portability, avoid sending +patches containing +.Pa // +in file names. +.Pp +.It +In traditional +.Xr patch , +backups were enabled by default. This behavior is now enabled with the +.Op -b +or +.Op --backup +option. +.Pp +Conversely, in POSIX +.Xr patch , +backups are never made, even when there is a mismatch. In GNU +.Xr patch , +this behavior is enabled with the +.Op --no-backup-if-mismatch +option, or by conforming to POSIX. +.Pp +The +.Op -b Va suffix +option of traditional +.Xr patch +is equivalent to the +.Li -b -z Va suffix +options of GNU +.Xr patch . +.Pp +.It +Traditional +.Xr patch +used a complicated (and incompletely documented) method to intuit the name +of the file to be patched from the patch header. This method did not conform +to POSIX, and had a few gotchas. Now +.Xr patch +uses a different, equally complicated (but better documented) method that +is optionally POSIX-conforming; we hope it has fewer gotchas. The two methods +are compatible if the file names in the context diff header and the +.Li Index: +line are all identical after prefix-stripping. Your patch is normally compatible +if each header's file names all contain the same number of slashes. +.Pp +.It +When traditional +.Xr patch +asked the user a question, it sent the question to standard error and looked +for an answer from the first file in the following list that was a terminal: +standard error, standard output, +.Pa /dev/tty , +and standard input. Now +.Xr patch +sends questions to standard output and gets answers from +.Pa /dev/tty . +Defaults for some answers have been changed so that +.Xr patch +never goes into an infinite loop when using default answers. +.Pp +.It +Traditional +.Xr patch +exited with a status value that counted the number of bad hunks, or with status +1 if there was real trouble. Now +.Xr patch +exits with status 1 if some hunks failed, or with 2 if there was real trouble. +.Pp +.It +Limit yourself to the following options when sending instructions meant to +be executed by anyone running GNU +.Xr patch , +traditional +.Xr patch , +or a +.Xr patch +that conforms to POSIX. Spaces are significant in the following list, and +operands are required. +.Pp +.Bd -literal -offset indent +-c +-d dir +-D define +-e +-l +-n +-N +-o outfile +-pnum +-R +-r rejectfile +.Ed +.Pp +.El +.Sh Tips for Making and Using Patches +Use some common sense when making and using patches. For example, when sending +bug fixes to a program's maintainer, send several small patches, one per independent +subject, instead of one large, harder-to-digest patch that covers all the +subjects. +.Pp +Here are some other things you should keep in mind if you are going to distribute +patches for updating a software package. +.Pp +.Ss Tips for Patch Producers +To create a patch that changes an older version of a package into a newer +version, first make a copy of the older and newer versions in adjacent subdirectories. +It is common to do that by unpacking +.Xr tar +archives of the two versions. +.Pp +To generate the patch, use the command +.Li diff -Naur Va old Va new +where +.Va old +and +.Va new +identify the old and new directories. The names +.Va old +and +.Va new +should not contain any slashes. The +.Op -N +option lets the patch create and remove files; +.Op -a +lets the patch update non-text files; +.Op -u +generates useful time stamps and enough context; and +.Op -r +lets the patch update subdirectories. Here is an example command, using Bourne +shell syntax: +.Pp +.Bd -literal -offset indent +diff -Naur gcc-3.0.3 gcc-3.0.4 +.Ed +.Pp +Tell your recipients how to apply the patches. This should include which working +directory to use, and which +.Xr patch +options to use; the option +.Li -p1 +is recommended. Test your procedure by pretending to be a recipient and applying +your patches to a copy of the original files. +.Pp +See Section.Dq Avoiding Common Mistakes , +for how to avoid common mistakes when generating a patch. +.Pp +.Ss Tips for Patch Consumers +A patch producer should tell recipients how to apply the patches, so the first +rule of thumb for a patch consumer is to follow the instructions supplied +with the patch. +.Pp +GNU +.Xr diff +can analyze files with arbitrarily long lines and files that end in incomplete +lines. However, older versions of +.Xr patch +cannot patch such files. If you are having trouble applying such patches, +try upgrading to a recent version of GNU +.Xr patch . +.Pp +.Ss Avoiding Common Mistakes +When producing a patch for multiple files, apply +.Xr diff +to directories whose names do not have slashes. This reduces confusion when +the patch consumer specifies the +.Op -p Va number +option, since this option can have surprising results when the old and new +file names have different numbers of slashes. For example, do not send a patch +with a header that looks like this: +.Pp +.Bd -literal -offset indent +diff -Naur v2.0.29/prog/README prog/README +--- v2.0.29/prog/README 2002-03-10 23:30:39.942229878 -0800 ++++ prog/README 2002-03-17 20:49:32.442260588 -0800 +.Ed +.Pp +because the two file names have different numbers of slashes, and different +versions of +.Xr patch +interpret the file names differently. To avoid confusion, send output that +looks like this instead: +.Pp +.Bd -literal -offset indent +diff -Naur v2.0.29/prog/README v2.0.30/prog/README +--- v2.0.29/prog/README 2002-03-10 23:30:39.942229878 -0800 ++++ v2.0.30/prog/README 2002-03-17 20:49:32.442260588 -0800 +.Ed +.Pp +Make sure you have specified the file names correctly, either in a context +diff header or with an +.Li Index: +line. Take care to not send out reversed patches, since these make people +wonder whether they have already applied the patch. +.Pp +Avoid sending patches that compare backup file names like +.Pa README.orig +or +.Pa README~ , +since this might confuse +.Xr patch +into patching a backup file instead of the real file. Instead, send patches +that compare the same base file names in different directories, e.g. +.Pa old/README +and +.Pa new/README . +.Pp +To save people from partially applying a patch before other patches that should +have gone before it, you can make the first patch in the patch file update +a file with a name like +.Pa patchlevel.h +or +.Pa version.c , +which contains a patch level or version number. If the input file contains +the wrong version number, +.Xr patch +will complain immediately. +.Pp +An even clearer way to prevent this problem is to put a +.Li Prereq: +line before the patch. If the leading text in the patch file contains a line +that starts with +.Li Prereq: , +.Xr patch +takes the next word from that line (normally a version number) and checks +whether the next input file contains that word, preceded and followed by either +white space or a newline. If not, +.Xr patch +prompts you for confirmation before proceeding. This makes it difficult to +accidentally apply patches in the wrong order. +.Pp +.Ss Generating Smaller Patches +The simplest way to generate a patch is to use +.Li diff -Naur +(see Section +.Dq Tips for Patch Producers ) , +but you might be able to reduce the size of the patch by renaming or removing +some files before making the patch. If the older version of the package contains +any files that the newer version does not, or if any files have been renamed +between the two versions, make a list of +.Xr rm +and +.Xr mv +commands for the user to execute in the old version directory before applying +the patch. Then run those commands yourself in the scratch directory. +.Pp +If there are any files that you don't need to include in the patch because +they can easily be rebuilt from other files (for example, +.Pa TAGS +and output from +.Xr yacc +and +.Xr makeinfo ) , +exclude them from the patch by giving +.Xr diff +the +.Op -x Va pattern +option (see Section +.Dq Comparing Directories ) . +If you want your patch to modify a derived file because your recipients lack +tools to build it, make sure that the patch for the derived file follows any +patches for files that it depends on, so that the recipients' time stamps +will not confuse +.Xr make . +.Pp +Now you can create the patch using +.Li diff -Naur . +Make sure to specify the scratch directory first and the newer directory second. +.Pp +Add to the top of the patch a note telling the user any +.Xr rm +and +.Xr mv +commands to run before applying the patch. Then you can remove the scratch +directory. +.Pp +You can also shrink the patch size by using fewer lines of context, but bear +in mind that +.Xr patch +typically needs at least two lines for proper operation when patches do not +exactly match the input files. +.Pp +.Sh Invoking Xr cmp +The +.Xr cmp +command compares two files, and if they differ, tells the first byte and line +number where they differ or reports that one file is a prefix of the other. +Bytes and lines are numbered starting with 1. The arguments of +.Xr cmp +are as follows: +.Pp +.Bd -literal -offset indent +cmp options... from-file [to-file [from-skip [to-skip]]] +.Ed +.Pp +The file name +.Pa - +is always the standard input. +.Xr cmp +also uses the standard input if one file name is omitted. The +.Va from-skip +and +.Va to-skip +operands specify how many bytes to ignore at the start of each file; they +are equivalent to the +.Op --ignore-initial= Va from-skip: Va to-skip +option. +.Pp +By default, +.Xr cmp +outputs nothing if the two files have the same contents. If one file is a +prefix of the other, +.Xr cmp +prints to standard error a message of the following form: +.Pp +.Bd -literal -offset indent +cmp: EOF on shorter-file +.Ed +.Pp +Otherwise, +.Xr cmp +prints to standard output a message of the following form: +.Pp +.Bd -literal -offset indent +from-file to-file differ: char byte-number, line line-number +.Ed +.Pp +The message formats can differ outside the POSIX locale. Also, POSIX allows +the EOF message to be followed by a blank and some additional information. +.Pp +An exit status of 0 means no differences were found, 1 means some differences +were found, and 2 means trouble. +.Pp +.Ss Options to Xr cmp +Below is a summary of all of the options that GNU +.Xr cmp +accepts. Most options have two equivalent names, one of which is a single +letter preceded by +.Li - , +and the other of which is a long name preceded by +.Li -- . +Multiple single letter options (unless they take an argument) can be combined +into a single command line word: +.Op -bl +is equivalent to +.Op -b -l . +.Pp +.Bl -tag -width Ds +.It -b +.It --print-bytes +Print the differing bytes. Display control bytes as a +.Li ^ +followed by a letter of the alphabet and precede bytes that have the high +bit set with +.Li M- +(which stands for \(lqmeta\(rq). +.Pp +.It --help +Output a summary of usage and then exit. +.Pp +.It -i Va skip +.It --ignore-initial= Va skip +Ignore any differences in the first +.Va skip +bytes of the input files. Treat files with fewer than +.Va skip +bytes as if they are empty. If +.Va skip +is of the form +.Op Va from-skip: Va to-skip , +skip the first +.Va from-skip +bytes of the first input file and the first +.Va to-skip +bytes of the second. +.Pp +.It -l +.It --verbose +Output the (decimal) byte numbers and (octal) values of all differing bytes, +instead of the default standard output. +.Pp +.It -n Va count +.It --bytes= Va count +Compare at most +.Va count +input bytes. +.Pp +.It -s +.It --quiet +.It --silent +Do not print anything; only return an exit status indicating whether the files +differ. +.Pp +.It -v +.It --version +Output version information and then exit. +.El +.Pp +In the above table, operands that are byte counts are normally decimal, but +may be preceded by +.Li 0 +for octal and +.Li 0x +for hexadecimal. +.Pp +A byte count can be followed by a suffix to specify a multiple of that count; +in this case an omitted integer is understood to be 1. A bare size letter, +or one followed by +.Li iB , +specifies a multiple using powers of 1024. A size letter followed by +.Li B +specifies powers of 1000 instead. For example, +.Op -n 4M +and +.Op -n 4MiB +are equivalent to +.Op -n 4194304 , +whereas +.Op -n 4MB +is equivalent to +.Op -n 4000000 . +This notation is upward compatible with the +.Lk http://www.bipm.fr/enus/3_SI/si-prefixes.html +for decimal multiples and with the +.Lk http://physics.nist.gov/cuu/Units/binary.html . +.Pp +The following suffixes are defined. Large sizes like +.Li 1Y +may be rejected by your computer due to limitations of its arithmetic. +.Pp +.Bl -tag -width Ds +.It kB +kilobyte: 10^3 = 1000. +.It k +.It K +.It KiB +kibibyte: 2^10 = 1024. +.Li K +is special: the SI prefix is +.Li k +and the IEC 60027-2 prefix is +.Li Ki , +but tradition and POSIX use +.Li k +to mean +.Li KiB . +.It MB +megabyte: 10^6 = 1,000,000. +.It M +.It MiB +mebibyte: 2^20 = 1,048,576. +.It GB +gigabyte: 10^9 = 1,000,000,000. +.It G +.It GiB +gibibyte: 2^30 = 1,073,741,824. +.It TB +terabyte: 10^12 = 1,000,000,000,000. +.It T +.It TiB +tebibyte: 2^40 = 1,099,511,627,776. +.It PB +petabyte: 10^15 = 1,000,000,000,000,000. +.It P +.It PiB +pebibyte: 2^50 = 1,125,899,906,842,624. +.It EB +exabyte: 10^18 = 1,000,000,000,000,000,000. +.It E +.It EiB +exbibyte: 2^60 = 1,152,921,504,606,846,976. +.It ZB +zettabyte: 10^21 = 1,000,000,000,000,000,000,000 +.It Z +.It ZiB +2^70 = 1,180,591,620,717,411,303,424. ( +.Li Zi +is a GNU extension to IEC 60027-2.) +.It YB +yottabyte: 10^24 = 1,000,000,000,000,000,000,000,000. +.It Y +.It YiB +2^80 = 1,208,925,819,614,629,174,706,176. ( +.Li Yi +is a GNU extension to IEC 60027-2.) +.El +.Pp +.Sh Invoking Xr diff +The format for running the +.Xr diff +command is: +.Pp +.Bd -literal -offset indent +diff options... files... +.Ed +.Pp +In the simplest case, two file names +.Va from-file +and +.Va to-file +are given, and +.Xr diff +compares the contents of +.Va from-file +and +.Va to-file . +A file name of +.Pa - +stands for text read from the standard input. As a special case, +.Li diff - - +compares a copy of standard input to itself. +.Pp +If one file is a directory and the other is not, +.Xr diff +compares the file in the directory whose name is that of the non-directory. +The non-directory file must not be +.Pa - . +.Pp +If two file names are given and both are directories, +.Xr diff +compares corresponding files in both directories, in alphabetical order; this +comparison is not recursive unless the +.Op -r +or +.Op --recursive +option is given. +.Xr diff +never compares the actual contents of a directory as if it were a file. The +file that is fully specified may not be standard input, because standard input +is nameless and the notion of \(lqfile with the same name\(rq does not apply. +.Pp +If the +.Op --from-file= Va file +option is given, the number of file names is arbitrary, and +.Va file +is compared to each named file. Similarly, if the +.Op --to-file= Va file +option is given, each named file is compared to +.Va file . +.Pp +.Xr diff +options begin with +.Li - , +so normally file names may not begin with +.Li - . +However, +.Op -- +as an argument by itself treats the remaining arguments as file names even +if they begin with +.Li - . +.Pp +An exit status of 0 means no differences were found, 1 means some differences +were found, and 2 means trouble. Normally, differing binary files count as +trouble, but this can be altered by using the +.Op -a +or +.Op --text +option, or the +.Op -q +or +.Op --brief +option. +.Pp +.Ss Options to Xr diff +Below is a summary of all of the options that GNU +.Xr diff +accepts. Most options have two equivalent names, one of which is a single +letter preceded by +.Li - , +and the other of which is a long name preceded by +.Li -- . +Multiple single letter options (unless they take an argument) can be combined +into a single command line word: +.Op -ac +is equivalent to +.Op -a -c . +Long named options can be abbreviated to any unique prefix of their name. +Brackets ([ and ]) indicate that an option takes an optional argument. +.Pp +.Bl -tag -width Ds +.It -a +.It --text +Treat all files as text and compare them line-by-line, even if they do not +seem to be text.See Section +.Dq Binary . +.Pp +.It -b +.It --ignore-space-change +Ignore changes in amount of white space.See Section +.Dq White Space . +.Pp +.It -B +.It --ignore-blank-lines +Ignore changes that just insert or delete blank lines.See Section +.Dq Blank Lines . +.Pp +.It --binary +Read and write data in binary mode.See Section +.Dq Binary . +.Pp +.It -c +Use the context output format, showing three lines of context.See Section +.Dq Context Format . +.Pp +.It -C Va lines +.It --context[= Va lines] +Use the context output format, showing +.Va lines +(an integer) lines of context, or three if +.Va lines +is not given.See Section +.Dq Context Format . +For proper operation, +.Xr patch +typically needs at least two lines of context. +.Pp +On older systems, +.Xr diff +supports an obsolete option +.Op - Va lines +that has effect when combined with +.Op -c +or +.Op -p . +POSIX 1003.1-2001 (see Section +.Dq Standards conformance ) +does not allow this; use +.Op -C Va lines +instead. +.Pp +.It --changed-group-format= Va format +Use +.Va format +to output a line group containing differing lines from both files in if-then-else +format.See Section +.Dq Line Group Formats . +.Pp +.It -d +.It --minimal +Change the algorithm perhaps find a smaller set of changes. This makes +.Xr diff +slower (sometimes much slower).See Section +.Dq diff Performance . +.Pp +.It -D Va name +.It --ifdef= Va name +Make merged +.Li #ifdef +format output, conditional on the preprocessor macro +.Va name . +See Section.Dq If-then-else . +.Pp +.It -e +.It --ed +Make output that is a valid +.Xr ed +script.See Section +.Dq ed Scripts . +.Pp +.It -E +.It --ignore-tab-expansion +Ignore changes due to tab expansion.See Section +.Dq White Space . +.Pp +.It -f +.It --forward-ed +Make output that looks vaguely like an +.Xr ed +script but has changes in the order they appear in the file.See Section +.Dq Forward ed . +.Pp +.It -F Va regexp +.It --show-function-line= Va regexp +In context and unified format, for each hunk of differences, show some of +the last preceding line that matches +.Va regexp . +See Section.Dq Specified Headings . +.Pp +.It --from-file= Va file +Compare +.Va file +to each operand; +.Va file +may be a directory. +.Pp +.It --help +Output a summary of usage and then exit. +.Pp +.It --horizon-lines= Va lines +Do not discard the last +.Va lines +lines of the common prefix and the first +.Va lines +lines of the common suffix.See Section +.Dq diff Performance . +.Pp +.It -i +.It --ignore-case +Ignore changes in case; consider upper- and lower-case letters equivalent.See Section +.Dq Case Folding . +.Pp +.It -I Va regexp +.It --ignore-matching-lines= Va regexp +Ignore changes that just insert or delete lines that match +.Va regexp . +See Section.Dq Specified Lines . +.Pp +.It --ignore-file-name-case +Ignore case when comparing file names during recursive comparison.See Section +.Dq Comparing Directories . +.Pp +.It -l +.It --paginate +Pass the output through +.Xr pr +to paginate it.See Section +.Dq Pagination . +.Pp +.It --label= Va label +Use +.Va label +instead of the file name in the context format (see Section +.Dq Context Format ) +and unified format (see Section +.Dq Unified Format ) +headers.See Section +.Dq RCS . +.Pp +.It --left-column +Print only the left column of two common lines in side by side format.See Section +.Dq Side by Side Format . +.Pp +.It --line-format= Va format +Use +.Va format +to output all input lines in if-then-else format.See Section +.Dq Line Formats . +.Pp +.It -n +.It --rcs +Output RCS-format diffs; like +.Op -f +except that each command specifies the number of lines affected.See Section +.Dq RCS . +.Pp +.It -N +.It --new-file +In directory comparison, if a file is found in only one directory, treat it +as present but empty in the other directory.See Section +.Dq Comparing Directories . +.Pp +.It --new-group-format= Va format +Use +.Va format +to output a group of lines taken from just the second file in if-then-else +format.See Section +.Dq Line Group Formats . +.Pp +.It --new-line-format= Va format +Use +.Va format +to output a line taken from just the second file in if-then-else format.See Section +.Dq Line Formats . +.Pp +.It --old-group-format= Va format +Use +.Va format +to output a group of lines taken from just the first file in if-then-else +format.See Section +.Dq Line Group Formats . +.Pp +.It --old-line-format= Va format +Use +.Va format +to output a line taken from just the first file in if-then-else format.See Section +.Dq Line Formats . +.Pp +.It -p +.It --show-c-function +Show which C function each change is in.See Section +.Dq C Function Headings . +.Pp +.It -q +.It --brief +Report only whether the files differ, not the details of the differences.See Section +.Dq Brief . +.Pp +.It -r +.It --recursive +When comparing directories, recursively compare any subdirectories found.See Section +.Dq Comparing Directories . +.Pp +.It -s +.It --report-identical-files +Report when two files are the same.See Section +.Dq Comparing Directories . +.Pp +.It -S Va file +.It --starting-file= Va file +When comparing directories, start with the file +.Va file . +This is used for resuming an aborted comparison.See Section +.Dq Comparing Directories . +.Pp +.It --speed-large-files +Use heuristics to speed handling of large files that have numerous scattered +small changes.See Section +.Dq diff Performance . +.Pp +.It --strip-trailing-cr +Strip any trailing carriage return at the end of an input line.See Section +.Dq Binary . +.Pp +.It --suppress-common-lines +Do not print common lines in side by side format.See Section +.Dq Side by Side Format . +.Pp +.It -t +.It --expand-tabs +Expand tabs to spaces in the output, to preserve the alignment of tabs in +the input files.See Section +.Dq Tabs . +.Pp +.It -T +.It --initial-tab +Output a tab rather than a space before the text of a line in normal or context +format. This causes the alignment of tabs in the line to look normal.See Section +.Dq Tabs . +.Pp +.It --tabsize= Va columns +Assume that tab stops are set every +.Va columns +(default 8) print columns.See Section +.Dq Tabs . +.Pp +.It --to-file= Va file +Compare each operand to +.Va file +; +.Va file +may be a directory. +.Pp +.It -u +Use the unified output format, showing three lines of context.See Section +.Dq Unified Format . +.Pp +.It --unchanged-group-format= Va format +Use +.Va format +to output a group of common lines taken from both files in if-then-else format.See Section +.Dq Line Group Formats . +.Pp +.It --unchanged-line-format= Va format +Use +.Va format +to output a line common to both files in if-then-else format.See Section +.Dq Line Formats . +.Pp +.It --unidirectional-new-file +When comparing directories, if a file appears only in the second directory +of the two, treat it as present but empty in the other.See Section +.Dq Comparing Directories . +.Pp +.It -U Va lines +.It --unified[= Va lines] +Use the unified output format, showing +.Va lines +(an integer) lines of context, or three if +.Va lines +is not given.See Section +.Dq Unified Format . +For proper operation, +.Xr patch +typically needs at least two lines of context. +.Pp +On older systems, +.Xr diff +supports an obsolete option +.Op - Va lines +that has effect when combined with +.Op -u . +POSIX 1003.1-2001 (see Section +.Dq Standards conformance ) +does not allow this; use +.Op -U Va lines +instead. +.Pp +.It -v +.It --version +Output version information and then exit. +.Pp +.It -w +.It --ignore-all-space +Ignore white space when comparing lines.See Section +.Dq White Space . +.Pp +.It -W Va columns +.It --width= Va columns +Output at most +.Va columns +(default 130) print columns per line in side by side format.See Section +.Dq Side by Side Format . +.Pp +.It -x Va pattern +.It --exclude= Va pattern +When comparing directories, ignore files and subdirectories whose basenames +match +.Va pattern . +See Section.Dq Comparing Directories . +.Pp +.It -X Va file +.It --exclude-from= Va file +When comparing directories, ignore files and subdirectories whose basenames +match any pattern contained in +.Va file . +See Section.Dq Comparing Directories . +.Pp +.It -y +.It --side-by-side +Use the side by side output format.See Section +.Dq Side by Side Format . +.El +.Pp +.Sh Invoking Xr diff3 +The +.Xr diff3 +command compares three files and outputs descriptions of their differences. +Its arguments are as follows: +.Pp +.Bd -literal -offset indent +diff3 options... mine older yours +.Ed +.Pp +The files to compare are +.Va mine , +.Va older , +and +.Va yours . +At most one of these three file names may be +.Pa - , +which tells +.Xr diff3 +to read the standard input for that file. +.Pp +An exit status of 0 means +.Xr diff3 +was successful, 1 means some conflicts were found, and 2 means trouble. +.Pp +.Ss Options to Xr diff3 +Below is a summary of all of the options that GNU +.Xr diff3 +accepts. Multiple single letter options (unless they take an argument) can +be combined into a single command line argument. +.Pp +.Bl -tag -width Ds +.It -a +.It --text +Treat all files as text and compare them line-by-line, even if they do not +appear to be text.See Section +.Dq Binary . +.Pp +.It -A +.It --show-all +Incorporate all unmerged changes from +.Va older +to +.Va yours +into +.Va mine , +surrounding conflicts with bracket lines.See Section +.Dq Marking Conflicts . +.Pp +.It --diff-program= Va program +Use the compatible comparison program +.Va program +to compare files instead of +.Xr diff . +.Pp +.It -e +.It --ed +Generate an +.Xr ed +script that incorporates all the changes from +.Va older +to +.Va yours +into +.Va mine . +See Section.Dq Which Changes . +.Pp +.It -E +.It --show-overlap +Like +.Op -e , +except bracket lines from overlapping changes' first and third files.See Section +.Dq Marking Conflicts . +With +.Op -E , +an overlapping change looks like this: +.Pp +.Bd -literal -offset indent +<<<<<<< mine +lines from mine +======= +lines from yours +>>>>>>> yours +.Ed +.Pp +.It --help +Output a summary of usage and then exit. +.Pp +.It -i +Generate +.Li w +and +.Li q +commands at the end of the +.Xr ed +script for System V compatibility. This option must be combined with one of +the +.Op -AeExX3 +options, and may not be combined with +.Op -m . +See Section.Dq Saving the Changed File . +.Pp +.It --label= Va label +Use the label +.Va label +for the brackets output by the +.Op -A , +.Op -E +and +.Op -X +options. This option may be given up to three times, one for each input file. +The default labels are the names of the input files. Thus +.Li diff3 --label X --label Y --label Z -m A B C +acts like +.Li diff3 -m A B C , +except that the output looks like it came from files named +.Li X , +.Li Y +and +.Li Z +rather than from files named +.Li A , +.Li B +and +.Li C . +See Section.Dq Marking Conflicts . +.Pp +.It -m +.It --merge +Apply the edit script to the first file and send the result to standard output. +Unlike piping the output from +.Xr diff3 +to +.Xr ed , +this works even for binary files and incomplete lines. +.Op -A +is assumed if no edit script option is specified.See Section +.Dq Bypassing ed . +.Pp +.It --strip-trailing-cr +Strip any trailing carriage return at the end of an input line.See Section +.Dq Binary . +.Pp +.It -T +.It --initial-tab +Output a tab rather than two spaces before the text of a line in normal format. +This causes the alignment of tabs in the line to look normal.See Section +.Dq Tabs . +.Pp +.It -v +.It --version +Output version information and then exit. +.Pp +.It -x +.It --overlap-only +Like +.Op -e , +except output only the overlapping changes.See Section +.Dq Which Changes . +.Pp +.It -X +Like +.Op -E , +except output only the overlapping changes. In other words, like +.Op -x , +except bracket changes as in +.Op -E . +See Section.Dq Marking Conflicts . +.Pp +.It -3 +.It --easy-only +Like +.Op -e , +except output only the nonoverlapping changes.See Section +.Dq Which Changes . +.El +.Pp +.Sh Invoking Xr patch +Normally +.Xr patch +is invoked like this: +.Pp +.Bd -literal -offset indent +patch <patchfile +.Ed +.Pp +The full format for invoking +.Xr patch +is: +.Pp +.Bd -literal -offset indent +patch options... [origfile [patchfile]] +.Ed +.Pp +You can also specify where to read the patch from with the +.Op -i Va patchfile +or +.Op --input= Va patchfile +option. If you do not specify +.Va patchfile , +or if +.Va patchfile +is +.Pa - , +.Xr patch +reads the patch (that is, the +.Xr diff +output) from the standard input. +.Pp +If you do not specify an input file on the command line, +.Xr patch +tries to intuit from the +.Em leading text +(any text in the patch that comes before the +.Xr diff +output) which file to edit.See Section +.Dq Multiple Patches . +.Pp +By default, +.Xr patch +replaces the original input file with the patched version, possibly after +renaming the original file into a backup file (see Section +.Dq Backup Names , +for a description of how +.Xr patch +names backup files). You can also specify where to put the output with the +.Op -o Va file +or +.Op --output= Va file +option; however, do not use this option if +.Va file +is one of the input files. +.Pp +.Ss Options to Xr patch +Here is a summary of all of the options that GNU +.Xr patch +accepts.See Section +.Dq patch and Tradition , +for which of these options are safe to use in older versions of +.Xr patch . +.Pp +Multiple single-letter options that do not take an argument can be combined +into a single command line argument with only one dash. +.Pp +.Bl -tag -width Ds +.It -b +.It --backup +Back up the original contents of each file, even if backups would normally +not be made.See Section +.Dq Backups . +.Pp +.It -B Va prefix +.It --prefix= Va prefix +Prepend +.Va prefix +to backup file names.See Section +.Dq Backup Names . +.Pp +.It --backup-if-mismatch +Back up the original contents of each file if the patch does not exactly match +the file. This is the default behavior when not conforming to POSIX.See Section +.Dq Backups . +.Pp +.It --binary +Read and write all files in binary mode, except for standard output and +.Pa /dev/tty . +This option has no effect on POSIX-conforming systems like GNU/Linux. On systems +where this option makes a difference, the patch should be generated by +.Li diff -a --binary . +See Section.Dq Binary . +.Pp +.It -c +.It --context +Interpret the patch file as a context diff.See Section +.Dq patch Input . +.Pp +.It -d Va directory +.It --directory= Va directory +Make directory +.Va directory +the current directory for interpreting both file names in the patch file, +and file names given as arguments to other options.See Section +.Dq patch Directories . +.Pp +.It -D Va name +.It --ifdef= Va name +Make merged if-then-else output using +.Va name . +See Section.Dq If-then-else . +.Pp +.It --dry-run +Print the results of applying the patches without actually changing any files.See Section +.Dq Dry Runs . +.Pp +.It -e +.It --ed +Interpret the patch file as an +.Xr ed +script.See Section +.Dq patch Input . +.Pp +.It -E +.It --remove-empty-files +Remove output files that are empty after the patches have been applied.See Section +.Dq Creating and Removing . +.Pp +.It -f +.It --force +Assume that the user knows exactly what he or she is doing, and do not ask +any questions.See Section +.Dq patch Messages . +.Pp +.It -F Va lines +.It --fuzz= Va lines +Set the maximum fuzz factor to +.Va lines . +See Section.Dq Inexact . +.Pp +.It -g Va num +.It --get= Va num +If +.Va num +is positive, get input files from a revision control system as necessary; +if zero, do not get the files; if negative, ask the user whether to get the +files.See Section +.Dq Revision Control . +.Pp +.It --help +Output a summary of usage and then exit. +.Pp +.It -i Va patchfile +.It --input= Va patchfile +Read the patch from +.Va patchfile +rather than from standard input.See Section +.Dq patch Options . +.Pp +.It -l +.It --ignore-white-space +Let any sequence of blanks (spaces or tabs) in the patch file match any sequence +of blanks in the input file.See Section +.Dq Changed White Space . +.Pp +.It -n +.It --normal +Interpret the patch file as a normal diff.See Section +.Dq patch Input . +.Pp +.It -N +.It --forward +Ignore patches that +.Xr patch +thinks are reversed or already applied. See also +.Op -R . +See Section.Dq Reversed Patches . +.Pp +.It --no-backup-if-mismatch +Do not back up the original contents of files. This is the default behavior +when conforming to POSIX.See Section +.Dq Backups . +.Pp +.It -o Va file +.It --output= Va file +Use +.Va file +as the output file name.See Section +.Dq patch Options . +.Pp +.It -p Va number +.It --strip= Va number +Set the file name strip count to +.Va number . +See Section.Dq patch Directories . +.Pp +.It --posix +Conform to POSIX, as if the +.Ev POSIXLY_CORRECT +environment variable had been set.See Section +.Dq patch and POSIX . +.Pp +.It --quoting-style= Va word +Use style +.Va word +to quote names in diagnostics, as if the +.Ev QUOTING_STYLE +environment variable had been set to +.Va word . +See Section.Dq patch Quoting Style . +.Pp +.It -r Va reject-file +.It --reject-file= Va reject-file +Use +.Va reject-file +as the reject file name.See Section +.Dq Reject Names . +.Pp +.It -R +.It --reverse +Assume that this patch was created with the old and new files swapped.See Section +.Dq Reversed Patches . +.Pp +.It -s +.It --quiet +.It --silent +Work silently unless an error occurs.See Section +.Dq patch Messages . +.Pp +.It -t +.It --batch +Do not ask any questions.See Section +.Dq patch Messages . +.Pp +.It -T +.It --set-time +Set the modification and access times of patched files from time stamps given +in context diff headers, assuming that the context diff headers use local +time.See Section +.Dq Patching Time Stamps . +.Pp +.It -u +.It --unified +Interpret the patch file as a unified diff.See Section +.Dq patch Input . +.Pp +.It -v +.It --version +Output version information and then exit. +.Pp +.It -V Va backup-style +.It --version=control= Va backup-style +Select the naming convention for backup file names.See Section +.Dq Backup Names . +.Pp +.It --verbose +Print more diagnostics than usual.See Section +.Dq patch Messages . +.Pp +.It -x Va number +.It --debug= Va number +Set internal debugging flags. Of interest only to +.Xr patch +patchers. +.Pp +.It -Y Va prefix +.It --basename-prefix= Va prefix +Prepend +.Va prefix +to base names of backup files.See Section +.Dq Backup Names . +.Pp +.It -z Va suffix +.It --suffix= Va suffix +Use +.Va suffix +as the backup extension instead of +.Li .orig +or +.Li ~ . +See Section.Dq Backup Names . +.Pp +.It -Z +.It --set-utc +Set the modification and access times of patched files from time stamps given +in context diff headers, assuming that the context diff headers use UTC.See Section +.Dq Patching Time Stamps . +.Pp +.El +.Sh Invoking Xr sdiff +The +.Xr sdiff +command merges two files and interactively outputs the results. Its arguments +are as follows: +.Pp +.Bd -literal -offset indent +sdiff -o outfile options... from-file to-file +.Ed +.Pp +This merges +.Va from-file +with +.Va to-file , +with output to +.Va outfile . +If +.Va from-file +is a directory and +.Va to-file +is not, +.Xr sdiff +compares the file in +.Va from-file +whose file name is that of +.Va to-file , +and vice versa. +.Va from-file +and +.Va to-file +may not both be directories. +.Pp +.Xr sdiff +options begin with +.Li - , +so normally +.Va from-file +and +.Va to-file +may not begin with +.Li - . +However, +.Op -- +as an argument by itself treats the remaining arguments as file names even +if they begin with +.Li - . +You may not use +.Pa - +as an input file. +.Pp +.Xr sdiff +without +.Op -o +(or +.Op --output ) +produces a side-by-side difference. This usage is obsolete; use the +.Op -y +or +.Op --side-by-side +option of +.Xr diff +instead. +.Pp +An exit status of 0 means no differences were found, 1 means some differences +were found, and 2 means trouble. +.Pp +.Ss Options to Xr sdiff +Below is a summary of all of the options that GNU +.Xr sdiff +accepts. Each option has two equivalent names, one of which is a single letter +preceded by +.Li - , +and the other of which is a long name preceded by +.Li -- . +Multiple single letter options (unless they take an argument) can be combined +into a single command line argument. Long named options can be abbreviated +to any unique prefix of their name. +.Pp +.Bl -tag -width Ds +.It -a +.It --text +Treat all files as text and compare them line-by-line, even if they do not +appear to be text.See Section +.Dq Binary . +.Pp +.It -b +.It --ignore-space-change +Ignore changes in amount of white space.See Section +.Dq White Space . +.Pp +.It -B +.It --ignore-blank-lines +Ignore changes that just insert or delete blank lines.See Section +.Dq Blank Lines . +.Pp +.It -d +.It --minimal +Change the algorithm to perhaps find a smaller set of changes. This makes +.Xr sdiff +slower (sometimes much slower).See Section +.Dq diff Performance . +.Pp +.It --diff-program= Va program +Use the compatible comparison program +.Va program +to compare files instead of +.Xr diff . +.Pp +.It -E +.It --ignore-tab-expansion +Ignore changes due to tab expansion.See Section +.Dq White Space . +.Pp +.It --help +Output a summary of usage and then exit. +.Pp +.It -i +.It --ignore-case +Ignore changes in case; consider upper- and lower-case to be the same.See Section +.Dq Case Folding . +.Pp +.It -I Va regexp +.It --ignore-matching-lines= Va regexp +Ignore changes that just insert or delete lines that match +.Va regexp . +See Section.Dq Specified Lines . +.Pp +.It -l +.It --left-column +Print only the left column of two common lines.See Section +.Dq Side by Side Format . +.Pp +.It -o Va file +.It --output= Va file +Put merged output into +.Va file . +This option is required for merging. +.Pp +.It -s +.It --suppress-common-lines +Do not print common lines.See Section +.Dq Side by Side Format . +.Pp +.It --speed-large-files +Use heuristics to speed handling of large files that have numerous scattered +small changes.See Section +.Dq diff Performance . +.Pp +.It --strip-trailing-cr +Strip any trailing carriage return at the end of an input line.See Section +.Dq Binary . +.Pp +.It -t +.It --expand-tabs +Expand tabs to spaces in the output, to preserve the alignment of tabs in +the input files.See Section +.Dq Tabs . +.Pp +.It --tabsize= Va columns +Assume that tab stops are set every +.Va columns +(default 8) print columns.See Section +.Dq Tabs . +.Pp +.It -v +.It --version +Output version information and then exit. +.Pp +.It -w Va columns +.It --width= Va columns +Output at most +.Va columns +(default 130) print columns per line.See Section +.Dq Side by Side Format . +Note that for historical reasons, this option is +.Op -W +in +.Xr diff , +.Op -w +in +.Xr sdiff . +.Pp +.It -W +.It --ignore-all-space +Ignore white space when comparing lines.See Section +.Dq White Space . +Note that for historical reasons, this option is +.Op -w +in +.Xr diff , +.Op -W +in +.Xr sdiff . +.El +.Pp +.Sh Standards conformance +In a few cases, the GNU utilities' default behavior is incompatible with the +POSIX standard. To suppress these incompatibilities, define the +.Ev POSIXLY_CORRECT +environment variable. Unless you are checking for POSIX conformance, you probably +do not need to define +.Ev POSIXLY_CORRECT . +.Pp +Normally options and operands can appear in any order, and programs act as +if all the options appear before any operands. For example, +.Li diff lao tzu -C 2 +acts like +.Li diff -C 2 lao tzu , +since +.Li 2 +is an option-argument of +.Op -C . +However, if the +.Ev POSIXLY_CORRECT +environment variable is set, options must appear before operands, unless otherwise +specified for a particular command. +.Pp +Newer versions of POSIX are occasionally incompatible with older versions. +For example, older versions of POSIX allowed the command +.Li diff -c -10 +to have the same meaning as +.Li diff -C 10 , +but POSIX 1003.1-2001 +.Li diff +no longer allows digit-string options like +.Op -10 . +.Pp +The GNU utilities normally conform to the version of POSIX that is standard +for your system. To cause them to conform to a different version of POSIX, +define the +.Ev _POSIX2_VERSION +environment variable to a value of the form +.Va yyyymm +specifying the year and month the standard was adopted. Two values are currently +supported for +.Ev _POSIX2_VERSION : +.Li 199209 +stands for POSIX 1003.2-1992, and +.Li 200112 +stands for POSIX 1003.1-2001. For example, if you are running older software +that assumes an older version of POSIX and uses +.Li diff -c -10 , +you can work around the compatibility problems by setting +.Li _POSIX2_VERSION=199209 +in your environment. +.Pp +.Sh Future Projects +Here are some ideas for improving GNU +.Xr diff +and +.Xr patch . +The GNU project has identified some improvements as potential programming +projects for volunteers. You can also help by reporting any bugs that you +find. +.Pp +If you are a programmer and would like to contribute something to the GNU +project, please consider volunteering for one of these projects. If you are +seriously contemplating work, please write to +.Mt gvc@gnu.org +to coordinate with other volunteers. +.Pp +.Ss Suggested Projects for Improving GNU Xr diff and Xr patch +One should be able to use GNU +.Xr diff +to generate a patch from any pair of directory trees, and given the patch +and a copy of one such tree, use +.Xr patch +to generate a faithful copy of the other. Unfortunately, some changes to directory +trees cannot be expressed using current patch formats; also, +.Xr patch +does not handle some of the existing formats. These shortcomings motivate +the following suggested projects. +.Pp +.Em Handling Multibyte and Varying-Width Characters +.Pp +.Xr diff , +.Xr diff3 +and +.Xr sdiff +treat each line of input as a string of unibyte characters. This can mishandle +multibyte characters in some cases. For example, when asked to ignore spaces, +.Xr diff +does not properly ignore a multibyte space character. +.Pp +Also, +.Xr diff +currently assumes that each byte is one column wide, and this assumption is +incorrect in some locales, e.g., locales that use UTF-8 encoding. This causes +problems with the +.Op -y +or +.Op --side-by-side +option of +.Xr diff . +.Pp +These problems need to be fixed without unduly affecting the performance of +the utilities in unibyte environments. +.Pp +The IBM GNU/Linux Technology Center Internationalization Team has proposed +.Lk http://oss.software.ibm.com/developer/opensource/linux/patches/i18n/diffutils-2.7.2-i18n-0.1.patch.gz . +Unfortunately, these patches are incomplete and are to an older version of +.Xr diff , +so more work needs to be done in this area. +.Pp +.Em Handling Changes to the Directory Structure +.Pp +.Xr diff +and +.Xr patch +do not handle some changes to directory structure. For example, suppose one +directory tree contains a directory named +.Li D +with some subsidiary files, and another contains a file with the same name +.Li D . +.Li diff -r +does not output enough information for +.Xr patch +to transform the directory subtree into the file. +.Pp +There should be a way to specify that a file has been removed without having +to include its entire contents in the patch file. There should also be a way +to tell +.Xr patch +that a file was renamed, even if there is no way for +.Xr diff +to generate such information. There should be a way to tell +.Xr patch +that a file's time stamp has changed, even if its contents have not changed. +.Pp +These problems can be fixed by extending the +.Xr diff +output format to represent changes in directory structure, and extending +.Xr patch +to understand these extensions. +.Pp +.Em Files that are Neither Directories Nor Regular Files +.Pp +Some files are neither directories nor regular files: they are unusual files +like symbolic links, device special files, named pipes, and sockets. Currently, +.Xr diff +treats symbolic links as if they were the pointed-to files, except that a +recursive +.Xr diff +reports an error if it detects infinite loops of symbolic links (e.g., symbolic +links to +.Pa .. ) . +.Xr diff +treats other special files like regular files if they are specified at the +top level, but simply reports their presence when comparing directories. This +means that +.Xr patch +cannot represent changes to such files. For example, if you change which file +a symbolic link points to, +.Xr diff +outputs the difference between the two files, instead of the change to the +symbolic link. +.Pp +.Xr diff +should optionally report changes to special files specially, and +.Xr patch +should be extended to understand these extensions. +.Pp +.Em File Names that Contain Unusual Characters +.Pp +When a file name contains an unusual character like a newline or white space, +.Li diff -r +generates a patch that +.Xr patch +cannot parse. The problem is with format of +.Xr diff +output, not just with +.Xr patch , +because with odd enough file names one can cause +.Xr diff +to generate a patch that is syntactically correct but patches the wrong files. +The format of +.Xr diff +output should be extended to handle all possible file names. +.Pp +.Em Outputting Diffs in Time Stamp Order +.Pp +Applying +.Xr patch +to a multiple-file diff can result in files whose time stamps are out of order. +GNU +.Xr patch +has options to restore the time stamps of the updated files (see Section +.Dq Patching Time Stamps ) , +but sometimes it is useful to generate a patch that works even if the recipient +does not have GNU patch, or does not use these options. One way to do this +would be to implement a +.Xr diff +option to output diffs in time stamp order. +.Pp +.Em Ignoring Certain Changes +.Pp +It would be nice to have a feature for specifying two strings, one in +.Va from-file +and one in +.Va to-file , +which should be considered to match. Thus, if the two strings are +.Li foo +and +.Li bar , +then if two lines differ only in that +.Li foo +in file 1 corresponds to +.Li bar +in file 2, the lines are treated as identical. +.Pp +It is not clear how general this feature can or should be, or what syntax +should be used for it. +.Pp +A partial substitute is to filter one or both files before comparing, e.g.: +.Pp +.Bd -literal -offset indent +sed 's/foo/bar/g' file1 | diff - file2 +.Ed +.Pp +However, this outputs the filtered text, not the original. +.Pp +.Em Improving Performance +.Pp +When comparing two large directory structures, one of which was originally +copied from the other with time stamps preserved (e.g., with +.Li cp -pR ) , +it would greatly improve performance if an option told +.Xr diff +to assume that two files with the same size and time stamps have the same +content.See Section +.Dq diff Performance . +.Pp +.Ss Reporting Bugs +If you think you have found a bug in GNU +.Xr cmp , +.Xr diff , +.Xr diff3 , +or +.Xr sdiff , +please report it by electronic mail to the +.Lk http://mail.gnu.org/mailman/listinfo/bug-gnu-utils +.Mt bug-gnu-utils@gnu.org . +Please send bug reports for GNU +.Xr patch +to +.Mt bug-patch@gnu.org . +Send as precise a description of the problem as you can, including the output +of the +.Op --version +option and sample input files that produce the bug, if applicable. If you +have a nontrivial fix for the bug, please send it as well. If you have a patch, +please send it too. It may simplify the maintainer's job if the patch is relative +to a recent test release, which you can find in the directory +.Lk ftp://alpha.gnu.org/gnu/diffutils/ . +.Pp +.Sh Copying This Manual +.Ss GNU Free Documentation License +.Bd -filled -offset indent +Copyright \(co 2000,2001,2002 Free Software Foundation, Inc. 59 Temple Place, +Suite 330, Boston, MA 02111-1307, 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 functional +and useful document +.Em free +in the sense of freedom: to assure everyone the effective freedom to copy +and redistribute it, with or without modifying it, either commercially or +noncommercially. Secondarily, this License preserves for the author and publisher +a way to get credit for their work, while not being considered responsible +for modifications made by others. +.Pp +This License is a kind of \(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, in any medium, that contains +a notice placed by the copyright holder saying it can be distributed under +the terms of this License. Such a notice grants a world-wide, royalty-free +license, unlimited in duration, to use that work under the conditions stated +herein. 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. You accept the license +if you copy, modify or distribute the work in a way requiring permission under +copyright law. +.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. +(Thus, 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. If a section does not fit the above definition +of Secondary then it is not allowed to be designated as Invariant. The Document +may contain zero Invariant Sections. If the Document does not identify any +Invariant Sections then there are none. +.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. A Front-Cover Text may be at most 5 words, and a Back-Cover +Text may be at most 25 words. +.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, that is +suitable for revising the document 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, or absence of markup, has been arranged to thwart or discourage +subsequent modification by readers is not Transparent. An image format is +not Transparent if used for any substantial amount of text. 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, PostScript or PDF designed +for human modification. Examples of transparent image formats include PNG, +XCF and JPG. Opaque formats include 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, PostScript or PDF 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 +A section \(lqEntitled XYZ\(rq means a named subunit of the Document whose title either +is precisely XYZ or contains XYZ in parentheses following text that translates +XYZ in another language. (Here XYZ stands for a specific section name mentioned +below, such as \(lqAcknowledgements\(rq, \(lqDedications\(rq, \(lqEndorsements\(rq, or \(lqHistory\(rq.) To +\(lqPreserve the Title\(rq of such a section when you modify the Document means that +it remains a section \(lqEntitled XYZ\(rq according to this definition. +.Pp +The Document may include Warranty Disclaimers next to the notice which states +that this License applies to the Document. These Warranty Disclaimers are +considered to be included by reference in this License, but only as regards +disclaiming warranties: any other implication that these Warranty Disclaimers +may have is void and has no effect on the meaning of this License. +.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 (or copies in media that commonly have printed +covers) 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 computer-network +location from which the general network-using public has access to download +using public-standard network protocols a complete Transparent copy of the +Document, free of added material. 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 +.Bl -enum +.It +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. +.Pp +.It +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 fewer than five), unless they release you from this requirement. +.Pp +.It +State on the Title page the name of the publisher of the Modified Version, +as the publisher. +.Pp +.It +Preserve all the copyright notices of the Document. +.Pp +.It +Add an appropriate copyright notice for your modifications adjacent to the +other copyright notices. +.Pp +.It +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. +.Pp +.It +Preserve in that license notice the full lists of Invariant Sections and required +Cover Texts given in the Document's license notice. +.Pp +.It +Include an unaltered copy of this License. +.Pp +.It +Preserve the section Entitled \(lqHistory\(rq, Preserve 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. +.Pp +.It +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. +.Pp +.It +For any section Entitled \(lqAcknowledgements\(rq or \(lqDedications\(rq, Preserve the Title +of the section, and preserve in the section all the substance and tone of +each of the contributor acknowledgements and/or dedications given therein. +.Pp +.It +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. +.Pp +.It +Delete any section Entitled \(lqEndorsements\(rq. Such a section may not be included +in the Modified Version. +.Pp +.It +Do not retitle any existing section to be Entitled \(lqEndorsements\(rq or to conflict +in title with any Invariant Section. +.Pp +.It +Preserve any Warranty Disclaimers. +.El +.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, and that you preserve all their +Warranty Disclaimers. +.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, +is called an \(lqaggregate\(rq if the copyright resulting from the compilation is +not used to limit the legal rights of the compilation's users beyond what +the individual works permit. When the Document is included in an aggregate, +this License does not apply to the other works in the aggregate which 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 half of the entire aggregate, +the Document's Cover Texts may be placed on covers that bracket the Document +within the aggregate, or the electronic equivalent of covers if the Document +is in electronic form. Otherwise they must appear on printed covers that bracket +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, and all the license notices in the Document, and any Warranty +Disclaimers, provided that you also include the original English version of +this License and the original versions of those notices and disclaimers. In +case of a disagreement between the translation and the original version of +this License or a notice or disclaimer, the original version will prevail. +.Pp +If a section in the Document is Entitled \(lqAcknowledgements\(rq, \(lqDedications\(rq, or +\(lqHistory\(rq, the requirement (section 4) to Preserve its Title (section 1) will +typically require changing the actual title. +.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 +.Lk 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. +.El +.Pp +.Em ADDENDUM: How to use this License for your documents +.Pp +To use this License in a document you have written, include a copy of the +License in the document and put the following copyright and license notices +just after the title page: +.Pp +.Bd -literal -offset indent + + Copyright (C) year your name. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled \(lqGNU + Free Documentation License\(rq. + +.Ed +.Pp +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace +the \(lqwith...Texts.\(rq line with this: +.Pp +.Bd -literal -offset indent + + with the Invariant Sections being list their titles, with + the Front-Cover Texts being list, and with the Back-Cover Texts + being list. + +.Ed +.Pp +If you have Invariant Sections without Cover Texts, or some other combination +of the three, merge those two alternatives to suit the situation. +.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 Translations of This Manual +Nishio Futoshi of the GNUjdoc project has prepared a Japanese translation +of this manual. Its most recent version can be found at +.Lk http://openlab.ring.gr.jp/gnujdoc/cvsweb/cvsweb.cgi/gnujdoc/ . +.Pp +.Sh Index diff --git a/contrib/gperf/doc/gperf.7 b/contrib/gperf/doc/gperf.7 new file mode 100644 index 000000000000..b44dc3b20e8d --- /dev/null +++ b/contrib/gperf/doc/gperf.7 @@ -0,0 +1,1892 @@ +.Dd 2015-03-02 +.Dt GPERF 7 +.Os +.Sh NAME +.Nm gperf +.Nd Perfect Hash Function Generator +.Sh Introduction +This manual documents the GNU +.Li gperf +perfect hash function generator utility, focusing on its features and how +to use them, and how to report bugs. +.Pp +.Sh GNU GENERAL PUBLIC LICENSE +.Bd -filled -offset indent +Copyright \(co 1989, 1991 Free Software Foundation, Inc., 59 Temple Place, Suite +330, Boston, MA 02111-1307, USA. +.Pp +Everyone is permitted to copy and distribute verbatim copies of this license +document, but changing it is not allowed. +.Ed +.Pp +.Ss Preamble +The licenses for most software are designed to take away your freedom to share +and change it. By contrast, the GNU General Public License is intended to +guarantee your freedom to share and change free software---to make sure the +software is free for all its users. This General Public License applies to +most of the Free Software Foundation's software and to any other program whose +authors commit to using it. (Some other Free Software Foundation software +is covered by the GNU Library General Public License instead.) You can apply +it to your programs, too. +.Pp +When we speak of free software, we are referring to freedom, not price. Our +General Public Licenses are designed to make sure that you have the freedom +to distribute copies of free software (and charge for this service if you +wish), that you receive source code or can get it if you want it, that you +can change the software or use pieces of it in new free programs; and that +you know you can do these things. +.Pp +To protect your rights, we need to make restrictions that forbid anyone to +deny you these rights or to ask you to surrender the rights. These restrictions +translate to certain responsibilities for you if you distribute copies of +the software, or if you modify it. +.Pp +For example, if you distribute copies of such a program, whether gratis or +for a fee, you must give the recipients all the rights that you have. You +must make sure that they, too, receive or can get the source code. And you +must show them these terms so they know their rights. +.Pp +We protect your rights with two steps: (1) copyright the software, and (2) +offer you this license which gives you legal permission to copy, distribute +and/or modify the software. +.Pp +Also, for each author's protection and ours, we want to make certain that +everyone understands that there is no warranty for this free software. If +the software is modified by someone else and passed on, we want its recipients +to know that what they have is not the original, so that any problems introduced +by others will not reflect on the original authors' reputations. +.Pp +Finally, any free program is threatened constantly by software patents. We +wish to avoid the danger that redistributors of a free program will individually +obtain patent licenses, in effect making the program proprietary. To prevent +this, we have made it clear that any patent must be licensed for everyone's +free use or not licensed at all. +.Pp +The precise terms and conditions for copying, distribution and modification +follow. +.Pp +.Bl -enum +.It +This License applies to any program or other work which contains a notice +placed by the copyright holder saying it may be distributed under the terms +of this General Public License. The \(lqProgram\(rq, below, refers to any such program +or work, and a \(lqwork based on the Program\(rq means either the Program or any derivative +work under copyright law: that is to say, a work containing the Program or +a portion of it, either verbatim or with modifications and/or translated into +another language. (Hereinafter, translation is included without limitation +in the term \(lqmodification\(rq.) Each licensee is addressed as \(lqyou\(rq. +.Pp +Activities other than copying, distribution and modification are not covered +by this License; they are outside its scope. The act of running the Program +is not restricted, and the output from the Program is covered only if its +contents constitute a work based on the Program (independent of having been +made by running the Program). Whether that is true depends on what the Program +does. +.Pp +.It +You may copy and distribute verbatim copies of the Program's source code as +you receive it, in any medium, provided that you conspicuously and appropriately +publish on each copy an appropriate copyright notice and disclaimer of warranty; +keep intact all the notices that refer to this License and to the absence +of any warranty; and give any other recipients of the Program a copy of this +License along with the Program. +.Pp +You may charge a fee for the physical act of transferring a copy, and you +may at your option offer warranty protection in exchange for a fee. +.Pp +.It +You may modify your copy or copies of the Program or any portion of it, thus +forming a work based on the Program, and copy and distribute such modifications +or work under the terms of Section 1 above, provided that you also meet all +of these conditions: +.Pp +.Bl -enum +.It +You must cause the modified files to carry prominent notices stating that +you changed the files and the date of any change. +.Pp +.It +You must cause any work that you distribute or publish, that in whole or in +part contains or is derived from the Program or any part thereof, to be licensed +as a whole at no charge to all third parties under the terms of this License. +.Pp +.It +If the modified program normally reads commands interactively when run, you +must cause it, when started running for such interactive use in the most ordinary +way, to print or display an announcement including an appropriate copyright +notice and a notice that there is no warranty (or else, saying that you provide +a warranty) and that users may redistribute the program under these conditions, +and telling the user how to view a copy of this License. (Exception: if the +Program itself is interactive but does not normally print such an announcement, +your work based on the Program is not required to print an announcement.) +.El +.Pp +These requirements apply to the modified work as a whole. If identifiable +sections of that work are not derived from the Program, and can be reasonably +considered independent and separate works in themselves, then this License, +and its terms, do not apply to those sections when you distribute them as +separate works. But when you distribute the same sections as part of a whole +which is a work based on the Program, the distribution of the whole must be +on the terms of this License, whose permissions for other licensees extend +to the entire whole, and thus to each and every part regardless of who wrote +it. +.Pp +Thus, it is not the intent of this section to claim rights or contest your +rights to work written entirely by you; rather, the intent is to exercise +the right to control the distribution of derivative or collective works based +on the Program. +.Pp +In addition, mere aggregation of another work not based on the Program with +the Program (or with a work based on the Program) on a volume of a storage +or distribution medium does not bring the other work under the scope of this +License. +.Pp +.It +You may copy and distribute the Program (or a work based on it, under Section +2) in object code or executable form under the terms of Sections 1 and 2 above +provided that you also do one of the following: +.Pp +.Bl -enum +.It +Accompany it with the complete corresponding machine-readable source code, +which must be distributed under the terms of Sections 1 and 2 above on a medium +customarily used for software interchange; or, +.Pp +.It +Accompany it with a written offer, valid for at least three years, to give +any third party, for a charge no more than your cost of physically performing +source distribution, a complete machine-readable copy of the corresponding +source code, to be distributed under the terms of Sections 1 and 2 above on +a medium customarily used for software interchange; or, +.Pp +.It +Accompany it with the information you received as to the offer to distribute +corresponding source code. (This alternative is allowed only for noncommercial +distribution and only if you received the program in object code or executable +form with such an offer, in accord with Subsection b above.) +.El +.Pp +The source code for a work means the preferred form of the work for making +modifications to it. For an executable work, complete source code means all +the source code for all modules it contains, plus any associated interface +definition files, plus the scripts used to control compilation and installation +of the executable. However, as a special exception, the source code distributed +need not include anything that is normally distributed (in either source or +binary form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component itself +accompanies the executable. +.Pp +If distribution of executable or object code is made by offering access to +copy from a designated place, then offering equivalent access to copy the +source code from the same place counts as distribution of the source code, +even though third parties are not compelled to copy the source along with +the object code. +.Pp +.It +You may not copy, modify, sublicense, or distribute the Program except as +expressly provided under this License. Any attempt otherwise to copy, modify, +sublicense or distribute the Program 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 +You are not required to accept this License, since you have not signed it. +However, nothing else grants you permission to modify or distribute the Program +or its derivative works. These actions are prohibited by law if you do not +accept this License. Therefore, by modifying or distributing the Program (or +any work based on the Program), you indicate your acceptance of this License +to do so, and all its terms and conditions for copying, distributing or modifying +the Program or works based on it. +.Pp +.It +Each time you redistribute the Program (or any work based on the Program), +the recipient automatically receives a license from the original licensor +to copy, distribute or modify the Program subject to these terms and conditions. +You may not impose any further restrictions on the recipients' exercise of +the rights granted herein. You are not responsible for enforcing compliance +by third parties to this License. +.Pp +.It +If, as a consequence of a court judgment or allegation of patent infringement +or for any other reason (not limited to patent issues), conditions are imposed +on you (whether by court order, agreement or otherwise) that contradict the +conditions of this License, they do not excuse you from the conditions of +this License. If you cannot distribute so as to satisfy simultaneously your +obligations under this License and any other pertinent obligations, then as +a consequence you may not distribute the Program at all. For example, if a +patent license would not permit royalty-free redistribution of the Program +by all those who receive copies directly or indirectly through you, then the +only way you could satisfy both it and this License would be to refrain entirely +from distribution of the Program. +.Pp +If any portion of this section is held invalid or unenforceable under any +particular circumstance, the balance of the section is intended to apply and +the section as a whole is intended to apply in other circumstances. +.Pp +It is not the purpose of this section to induce you to infringe any patents +or other property right claims or to contest validity of any such claims; +this section has the sole purpose of protecting the integrity of the free +software distribution system, which is implemented by public license practices. +Many people have made generous contributions to the wide range of software +distributed through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing to +distribute software through any other system and a licensee cannot impose +that choice. +.Pp +This section is intended to make thoroughly clear what is believed to be a +consequence of the rest of this License. +.Pp +.It +If the distribution and/or use of the Program is restricted in certain countries +either by patents or by copyrighted interfaces, the original copyright holder +who places the Program under this License may add an explicit geographical +distribution limitation excluding those countries, so that distribution is +permitted only in or among countries not thus excluded. In such case, this +License incorporates the limitation as if written in the body of this License. +.Pp +.It +The Free Software Foundation may publish revised and/or new versions of the +General Public 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. +.Pp +Each version is given a distinguishing version number. If the Program specifies +a version number of this License which applies to it and \(lqany later version\(rq, +you have the option of following the terms and conditions either of that version +or of any later version published by the Free Software Foundation. If the +Program does not specify a version number of this License, you may choose +any version ever published by the Free Software Foundation. +.Pp +.It +If you wish to incorporate parts of the Program into other free programs whose +distribution conditions are different, write to the author to ask for permission. +For software which is copyrighted by the Free Software Foundation, write to +the Free Software Foundation; we sometimes make exceptions for this. Our decision +will be guided by the two goals of preserving the free status of all derivatives +of our free software and of promoting the sharing and reuse of software generally. +.Pp +.It +BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE +PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE +STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM +\(lqAS IS\(rq WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, +BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS +FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE +OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME +THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. +.Pp +.It +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL +ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE +THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY +GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE +OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA +OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES +OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH +HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. +.El +.Pp +.Ss How to Apply These Terms to Your New Programs +If you develop a new program, and you want it to be of the greatest possible +use to the public, the best way to achieve this is to make it free software +which everyone can redistribute and change under these terms. +.Pp +To do so, attach the following notices to the program. It is safest to attach +them to the start of each source file to most effectively convey the exclusion +of warranty; and each file should have at least the \(lqcopyright\(rq line and a pointer +to where the full notice is found. +.Pp +.Bd -literal -offset indent +one line to give the program's name and an idea of what it does. +Copyright (C) year name of author + +This program is free software; you can redistribute it and/or +modify it under the terms of the GNU General Public License +as published by the Free Software Foundation; either version 2 +of the License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA. +.Ed +.Pp +Also add information on how to contact you by electronic and paper mail. +.Pp +If the program is interactive, make it output a short notice like this when +it starts in an interactive mode: +.Pp +.Bd -literal -offset indent +Gnomovision version 69, Copyright (C) year name of author +Gnomovision comes with ABSOLUTELY NO WARRANTY; for details +type `show w'. This is free software, and you are welcome +to redistribute it under certain conditions; type `show c' +for details. +.Ed +.Pp +The hypothetical commands +.Li show w +and +.Li show c +should show the appropriate parts of the General Public License. Of course, +the commands you use may be called something other than +.Li show w +and +.Li show c +; they could even be mouse-clicks or menu items---whatever suits your program. +.Pp +You should also get your employer (if you work as a programmer) or your school, +if any, to sign a \(lqcopyright disclaimer\(rq for the program, if necessary. Here +is a sample; alter the names: +.Pp +.Bd -literal -offset indent + +Yoyodyne, Inc., hereby disclaims all copyright +interest in the program `Gnomovision' +(which makes passes at compilers) written +by James Hacker. + +signature of Ty Coon, 1 April 1989 +Ty Coon, President of Vice + +.Ed +.Pp +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may consider +it more useful to permit linking proprietary applications with the library. +If this is what you want to do, use the GNU Library General Public License +instead of this License. +.Pp +.Sh Contributors to GNU Li gperf Utility +.Bl -bullet +.It +The GNU +.Li gperf +perfect hash function generator utility was written in GNU C++ by Douglas +C. Schmidt. The general idea for the perfect hash function generator was inspired +by Keith Bostic's algorithm written in C, and distributed to net.sources around +1984. The current program is a heavily modified, enhanced, and extended implementation +of Keith's basic idea, created at the University of California, Irvine. Bugs, +patches, and suggestions should be reported to +.Li <bug-gnu-gperf@gnu.org> . +.Pp +.It +Special thanks is extended to Michael Tiemann and Doug Lea, for providing +a useful compiler, and for giving me a forum to exhibit my creation. +.Pp +In addition, Adam de Boor and Nels Olson provided many tips and insights that +greatly helped improve the quality and functionality of +.Li gperf . +.Pp +.It +Bruno Haible enhanced and optimized the search algorithm. He also rewrote +the input routines and the output routines for better reliability, and added +a testsuite. +.El +.Pp +.Sh Introduction +.Li gperf +is a perfect hash function generator written in C++. It transforms an +.Va n +element user-specified keyword set +.Va W +into a perfect hash function +.Va F . +.Va F +uniquely maps keywords in +.Va W +onto the range 0.. +.Va k , +where +.Va k +>= +.Va n-1 . +If +.Va k += +.Va n-1 +then +.Va F +is a +.Em minimal +perfect hash function. +.Li gperf +generates a 0.. +.Va k +element static lookup table and a pair of C functions. These functions determine +whether a given character string +.Va s +occurs in +.Va W , +using at most one probe into the lookup table. +.Pp +.Li gperf +currently generates the reserved keyword recognizer for lexical analyzers +in several production and research compilers and language processing tools, +including GNU C, GNU C++, GNU Java, GNU Pascal, GNU Modula 3, and GNU indent. +Complete C++ source code for +.Li gperf +is available from +.Li http://ftp.gnu.org/pub/gnu/gperf/ . +A paper describing +.Li gperf +\&'s design and implementation in greater detail is available in the Second +USENIX C++ Conference proceedings or from +.Li http://www.cs.wustl.edu/~schmidt/resume.html . +.Pp +.Sh Static search structures and GNU Li gperf +A +.Em static search structure +is an Abstract Data Type with certain fundamental operations, e.g., +.Em initialize , +.Em insert , +and +.Em retrieve . +Conceptually, all insertions occur before any retrievals. In practice, +.Li gperf +generates a +.Em static +array containing search set keywords and any associated attributes specified +by the user. Thus, there is essentially no execution-time cost for the insertions. +It is a useful data structure for representing +.Em static search sets . +Static search sets occur frequently in software system applications. Typical +static search sets include compiler reserved words, assembler instruction +opcodes, and built-in shell interpreter commands. Search set members, called +.Em keywords , +are inserted into the structure only once, usually during program initialization, +and are not generally modified at run-time. +.Pp +Numerous static search structure implementations exist, e.g., arrays, linked +lists, binary search trees, digital search tries, and hash tables. Different +approaches offer trade-offs between space utilization and search time efficiency. +For example, an +.Va n +element sorted array is space efficient, though the average-case time complexity +for retrieval operations using binary search is proportional to log +.Va n . +Conversely, hash table implementations often locate a table entry in constant +time, but typically impose additional memory overhead and exhibit poor worst +case performance. +.Pp +.Em Minimal perfect hash functions +provide an optimal solution for a particular class of static search sets. +A minimal perfect hash function is defined by two properties: +.Pp +.Bl -bullet +.It +It allows keyword recognition in a static search set using at most +.Em one +probe into the hash table. This represents the \(lqperfect\(rq property. +.It +The actual memory allocated to store the keywords is precisely large enough +for the keyword set, and +.Em no larger . +This is the \(lqminimal\(rq property. +.El +.Pp +For most applications it is far easier to generate +.Em perfect +hash functions than +.Em minimal perfect +hash functions. Moreover, non-minimal perfect hash functions frequently execute +faster than minimal ones in practice. This phenomena occurs since searching +a sparse keyword table increases the probability of locating a \(lqnull\(rq entry, +thereby reducing string comparisons. +.Li gperf +\&'s default behavior generates +.Em near-minimal +perfect hash functions for keyword sets. However, +.Li gperf +provides many options that permit user control over the degree of minimality +and perfection. +.Pp +Static search sets often exhibit relative stability over time. For example, +Ada's 63 reserved words have remained constant for nearly a decade. It is +therefore frequently worthwhile to expend concerted effort building an optimal +search structure +.Em once , +if it subsequently receives heavy use multiple times. +.Li gperf +removes the drudgery associated with constructing time- and space-efficient +search structures by hand. It has proven a useful and practical tool for serious +programming projects. Output from +.Li gperf +is currently used in several production and research compilers, including +GNU C, GNU C++, GNU Java, GNU Pascal, and GNU Modula 3. The latter two compilers +are not yet part of the official GNU distribution. Each compiler utilizes +.Li gperf +to automatically generate static search structures that efficiently identify +their respective reserved keywords. +.Pp +.Sh High-Level Description of GNU Li gperf +The perfect hash function generator +.Li gperf +reads a set of \(lqkeywords\(rq from an input file (or from the standard input by +default). It attempts to derive a perfect hashing function that recognizes +a member of the +.Em static keyword set +with at most a single probe into the lookup table. If +.Li gperf +succeeds in generating such a function it produces a pair of C source code +routines that perform hashing and table lookup recognition. All generated +C code is directed to the standard output. Command-line options described +below allow you to modify the input and output format to +.Li gperf . +.Pp +By default, +.Li gperf +attempts to produce time-efficient code, with less emphasis on efficient space +utilization. However, several options exist that permit trading-off execution +time for storage space and vice versa. In particular, expanding the generated +table size produces a sparse search structure, generally yielding faster searches. +Conversely, you can direct +.Li gperf +to utilize a C +.Li switch +statement scheme that minimizes data space storage size. Furthermore, using +a C +.Li switch +may actually speed up the keyword retrieval time somewhat. Actual results +depend on your C compiler, of course. +.Pp +In general, +.Li gperf +assigns values to the bytes it is using for hashing until some set of values +gives each keyword a unique value. A helpful heuristic is that the larger +the hash value range, the easier it is for +.Li gperf +to find and generate a perfect hash function. Experimentation is the key to +getting the most from +.Li gperf . +.Pp +.Ss Input Format to Li gperf +You can control the input file format by varying certain command-line arguments, +in particular the +.Li -t +option. The input's appearance is similar to GNU utilities +.Li flex +and +.Li bison +(or UNIX utilities +.Li lex +and +.Li yacc ) . +Here's an outline of the general format: +.Pp +.Bd -literal -offset indent + +declarations +%% +keywords +%% +functions + +.Ed +.Pp +.Em Unlike +.Li flex +or +.Li bison , +the declarations section and the functions section are optional. The following +sections describe the input format for each section. +.Pp +It is possible to omit the declaration section entirely, if the +.Li -t +option is not given. In this case the input file begins directly with the +first keyword line, e.g.: +.Pp +.Bd -literal -offset indent + +january +february +march +april +\&... + +.Ed +.Pp +.Em Declarations +.Pp +The keyword input file optionally contains a section for including arbitrary +C declarations and definitions, +.Li gperf +declarations that act like command-line options, as well as for providing +a user-supplied +.Li struct . +.Pp +.No User-supplied Li struct +.Pp +If the +.Li -t +option (or, equivalently, the +.Li %struct-type +declaration) +.Em is +enabled, you +.Em must +provide a C +.Li struct +as the last component in the declaration section from the input file. The +first field in this struct must be of type +.Li char * +or +.Li const char * +if the +.Li -P +option is not given, or of type +.Li int +if the option +.Li -P +(or, equivalently, the +.Li %pic +declaration) is enabled. This first field must be called +.Li name , +although it is possible to modify its name with the +.Li -K +option (or, equivalently, the +.Li %define slot-name +declaration) described below. +.Pp +Here is a simple example, using months of the year and their attributes as +input: +.Pp +.Bd -literal -offset indent + +struct month { char *name; int number; int days; int leap_days; }; +%% +january, 1, 31, 31 +february, 2, 28, 29 +march, 3, 31, 31 +april, 4, 30, 30 +may, 5, 31, 31 +june, 6, 30, 30 +july, 7, 31, 31 +august, 8, 31, 31 +september, 9, 30, 30 +october, 10, 31, 31 +november, 11, 30, 30 +december, 12, 31, 31 + +.Ed +.Pp +Separating the +.Li struct +declaration from the list of keywords and other fields are a pair of consecutive +percent signs, +.Li %% , +appearing left justified in the first column, as in the UNIX utility +.Li lex . +.Pp +If the +.Li struct +has already been declared in an include file, it can be mentioned in an abbreviated +form, like this: +.Pp +.Bd -literal -offset indent + +struct month; +%% +january, 1, 31, 31 +\&... + +.Ed +.Pp +.No Gperf Declarations +.Pp +The declaration section can contain +.Li gperf +declarations. They influence the way +.Li gperf +works, like command line options do. In fact, every such declaration is equivalent +to a command line option. There are three forms of declarations: +.Pp +.Bl -enum +.It +Declarations without argument, like +.Li %compare-lengths . +.Pp +.It +Declarations with an argument, like +.Li %switch= Va count . +.Pp +.It +Declarations of names of entities in the output file, like +.Li %define lookup-function-name Va name . +.El +.Pp +When a declaration is given both in the input file and as a command line option, +the command-line option's value prevails. +.Pp +The following +.Li gperf +declarations are available. +.Pp +.Bl -tag -width Ds +.It %delimiters= Va delimiter-list +Allows you to provide a string containing delimiters used to separate keywords +from their attributes. The default is ",". This option is essential if you +want to use keywords that have embedded commas or newlines. +.Pp +.It %struct-type +Allows you to include a +.Li struct +type declaration for generated code; see above for an example. +.Pp +.It %ignore-case +Consider upper and lower case ASCII characters as equivalent. The string comparison +will use a case insignificant character comparison. Note that locale dependent +case mappings are ignored. +.Pp +.It %language= Va language-name +Instructs +.Li gperf +to generate code in the language specified by the option's argument. Languages +handled are currently: +.Pp +.Bl -tag -width Ds +.It KR-C +Old-style K&R C. This language is understood by old-style C compilers and +ANSI C compilers, but ANSI C compilers may flag warnings (or even errors) +because of lacking +.Li const . +.Pp +.It C +Common C. This language is understood by ANSI C compilers, and also by old-style +C compilers, provided that you +.Li #define const +to empty for compilers which don't know about this keyword. +.Pp +.It ANSI-C +ANSI C. This language is understood by ANSI C compilers and C++ compilers. +.Pp +.It C++ +C++. This language is understood by C++ compilers. +.El +.Pp +The default is C. +.Pp +.It %define slot-name Va name +This declaration is only useful when option +.Li -t +(or, equivalently, the +.Li %struct-type +declaration) has been given. By default, the program assumes the structure +component identifier for the keyword is +.Li name . +This option allows an arbitrary choice of identifier for this component, although +it still must occur as the first field in your supplied +.Li struct . +.Pp +.It %define initializer-suffix Va initializers +This declaration is only useful when option +.Li -t +(or, equivalently, the +.Li %struct-type +declaration) has been given. It permits to specify initializers for the structure +members following +.Va slot-name +in empty hash table entries. The list of initializers should start with a +comma. By default, the emitted code will zero-initialize structure members +following +.Va slot-name . +.Pp +.It %define hash-function-name Va name +Allows you to specify the name for the generated hash function. Default name +is +.Li hash . +This option permits the use of two hash tables in the same file. +.Pp +.It %define lookup-function-name Va name +Allows you to specify the name for the generated lookup function. Default +name is +.Li in_word_set . +This option permits multiple generated hash functions to be used in the same +application. +.Pp +.It %define class-name Va name +This option is only useful when option +.Li -L C++ +(or, equivalently, the +.Li %language=C++ +declaration) has been given. It allows you to specify the name of generated +C++ class. Default name is +.Li Perfect_Hash . +.Pp +.It %7bit +This option specifies that all strings that will be passed as arguments to +the generated hash function and the generated lookup function will solely +consist of 7-bit ASCII characters (bytes in the range 0..127). (Note that +the ANSI C functions +.Li isalnum +and +.Li isgraph +do +.Em not +guarantee that a byte is in this range. Only an explicit test like +.Li c >= 'A' && c <= 'Z' +guarantees this.) +.Pp +.It %compare-lengths +Compare keyword lengths before trying a string comparison. This option is +mandatory for binary comparisons (see Section +.Dq Binary Strings ) . +It also might cut down on the number of string comparisons made during the +lookup, since keywords with different lengths are never compared via +.Li strcmp . +However, using +.Li %compare-lengths +might greatly increase the size of the generated C code if the lookup table +range is large (which implies that the switch option +.Li -S +or +.Li %switch +is not enabled), since the length table contains as many elements as there +are entries in the lookup table. +.Pp +.It %compare-strncmp +Generates C code that uses the +.Li strncmp +function to perform string comparisons. The default action is to use +.Li strcmp . +.Pp +.It %readonly-tables +Makes the contents of all generated lookup tables constant, i.e., \(lqreadonly\(rq. +Many compilers can generate more efficient code for this by putting the tables +in readonly memory. +.Pp +.It %enum +Define constant values using an enum local to the lookup function rather than +with #defines. This also means that different lookup functions can reside +in the same file. Thanks to James Clark +.Li <jjc@ai.mit.edu> . +.Pp +.It %includes +Include the necessary system include file, +.Li <string.h> , +at the beginning of the code. By default, this is not done; the user must +include this header file himself to allow compilation of the code. +.Pp +.It %global-table +Generate the static table of keywords as a static global variable, rather +than hiding it inside of the lookup function (which is the default behavior). +.Pp +.It %pic +Optimize the generated table for inclusion in shared libraries. This reduces +the startup time of programs using a shared library containing the generated +code. If the +.Li %struct-type +declaration (or, equivalently, the option +.Li -t ) +is also given, the first field of the user-defined struct must be of type +.Li int , +not +.Li char * , +because it will contain offsets into the string pool instead of actual strings. +To convert such an offset to a string, you can use the expression +.Li stringpool + Va o , +where +.Va o +is the offset. The string pool name can be changed through the +.Li %define string-pool-name +declaration. +.Pp +.It %define string-pool-name Va name +Allows you to specify the name of the generated string pool created by the +declaration +.Li %pic +(or, equivalently, the option +.Li -P ) . +The default name is +.Li stringpool . +This declaration permits the use of two hash tables in the same file, with +.Li %pic +and even when the +.Li %global-table +declaration (or, equivalently, the option +.Li -G ) +is given. +.Pp +.It %null-strings +Use NULL strings instead of empty strings for empty keyword table entries. +This reduces the startup time of programs using a shared library containing +the generated code (but not as much as the declaration +.Li %pic ) , +at the expense of one more test-and-branch instruction at run time. +.Pp +.It %define word-array-name Va name +Allows you to specify the name for the generated array containing the hash +table. Default name is +.Li wordlist . +This option permits the use of two hash tables in the same file, even when +the option +.Li -G +(or, equivalently, the +.Li %global-table +declaration) is given. +.Pp +.It %define length-table-name Va name +Allows you to specify the name for the generated array containing the length +table. Default name is +.Li lengthtable . +This option permits the use of two length tables in the same file, even when +the option +.Li -G +(or, equivalently, the +.Li %global-table +declaration) is given. +.Pp +.It %switch= Va count +Causes the generated C code to use a +.Li switch +statement scheme, rather than an array lookup table. This can lead to a reduction +in both time and space requirements for some input files. The argument to +this option determines how many +.Li switch +statements are generated. A value of 1 generates 1 +.Li switch +containing all the elements, a value of 2 generates 2 tables with 1/2 the +elements in each +.Li switch , +etc. This is useful since many C compilers cannot correctly generate code +for large +.Li switch +statements. This option was inspired in part by Keith Bostic's original C +program. +.Pp +.It %omit-struct-type +Prevents the transfer of the type declaration to the output file. Use this +option if the type is already defined elsewhere. +.El +.Pp +.No C Code Inclusion +.Pp +Using a syntax similar to GNU utilities +.Li flex +and +.Li bison , +it is possible to directly include C source text and comments verbatim into +the generated output file. This is accomplished by enclosing the region inside +left-justified surrounding +.Li %{ , +.Li %} +pairs. Here is an input fragment based on the previous example that illustrates +this feature: +.Pp +.Bd -literal -offset indent + +%{ +#include <assert.h> +/* This section of code is inserted directly into the output. */ +int return_month_days (struct month *months, int is_leap_year); +%} +struct month { char *name; int number; int days; int leap_days; }; +%% +january, 1, 31, 31 +february, 2, 28, 29 +march, 3, 31, 31 +\&... + +.Ed +.Pp +.Em Format for Keyword Entries +.Pp +The second input file format section contains lines of keywords and any associated +attributes you might supply. A line beginning with +.Li # +in the first column is considered a comment. Everything following the +.Li # +is ignored, up to and including the following newline. A line beginning with +.Li % +in the first column is an option declaration and must not occur within the +keywords section. +.Pp +The first field of each non-comment line is always the keyword itself. It +can be given in two ways: as a simple name, i.e., without surrounding string +quotation marks, or as a string enclosed in double-quotes, in C syntax, possibly +with backslash escapes like +.Li \e" +or +.Li \e234 +or +.Li \exa8 . +In either case, it must start right at the beginning of the line, without +leading whitespace. In this context, a \(lqfield\(rq is considered to extend up to, +but not include, the first blank, comma, or newline. Here is a simple example +taken from a partial list of C reserved words: +.Pp +.Bd -literal -offset indent + +# These are a few C reserved words, see the c.gperf file +# for a complete list of ANSI C reserved words. +unsigned +sizeof +switch +signed +if +default +for +while +return + +.Ed +.Pp +Note that unlike +.Li flex +or +.Li bison +the first +.Li %% +marker may be elided if the declaration section is empty. +.Pp +Additional fields may optionally follow the leading keyword. Fields should +be separated by commas, and terminate at the end of line. What these fields +mean is entirely up to you; they are used to initialize the elements of the +user-defined +.Li struct +provided by you in the declaration section. If the +.Li -t +option (or, equivalently, the +.Li %struct-type +declaration) is +.Em not +enabled these fields are simply ignored. All previous examples except the +last one contain keyword attributes. +.Pp +.Em Including Additional C Functions +.Pp +The optional third section also corresponds closely with conventions found +in +.Li flex +and +.Li bison . +All text in this section, starting at the final +.Li %% +and extending to the end of the input file, is included verbatim into the +generated output file. Naturally, it is your responsibility to ensure that +the code contained in this section is valid C. +.Pp +.Em Where to place directives for GNU Li indent. +.Pp +If you want to invoke GNU +.Li indent +on a +.Li gperf +input file, you will see that GNU +.Li indent +doesn't understand the +.Li %% , +.Li %{ +and +.Li %} +directives that control +.Li gperf +\&'s interpretation of the input file. Therefore you have to insert some directives +for GNU +.Li indent . +More precisely, assuming the most general input file structure +.Pp +.Bd -literal -offset indent + +declarations part 1 +%{ +verbatim code +%} +declarations part 2 +%% +keywords +%% +functions + +.Ed +.Pp +you would insert +.Li *INDENT-OFF* +and +.Li *INDENT-ON* +comments as follows: +.Pp +.Bd -literal -offset indent + +/* *INDENT-OFF* */ +declarations part 1 +%{ +/* *INDENT-ON* */ +verbatim code +/* *INDENT-OFF* */ +%} +declarations part 2 +%% +keywords +%% +/* *INDENT-ON* */ +functions + +.Ed +.Pp +.Ss Output Format for Generated C Code with Li gperf +Several options control how the generated C code appears on the standard output. +Two C functions are generated. They are called +.Li hash +and +.Li in_word_set , +although you may modify their names with a command-line option. Both functions +require two arguments, a string, +.Li char * +.Va str , +and a length parameter, +.Li int +.Va len . +Their default function prototypes are as follows: +.Pp +Function: +.Ft unsigned int +.Fo hash +.Fa (const char * Va str, unsigned int Va len) +.Fc +.Pp +By default, the generated +.Li hash +function returns an integer value created by adding +.Va len +to several user-specified +.Va str +byte positions indexed into an +.Em associated values +table stored in a local static array. The associated values table is constructed +internally by +.Li gperf +and later output as a static local C array called +.Li hash_table . +The relevant selected positions (i.e. indices into +.Va str ) +are specified via the +.Li -k +option when running +.Li gperf , +as detailed in the +.Em Options +section below (see Section +.Dq Options ) . +.Pp +Function: +.Ft +.Fo in_word_set +.Fa (const char * Va str, unsigned int Va len) +.Fc +.Pp +If +.Va str +is in the keyword set, returns a pointer to that keyword. More exactly, if +the option +.Li -t +(or, equivalently, the +.Li %struct-type +declaration) was given, it returns a pointer to the matching keyword's structure. +Otherwise it returns +.Li NULL . +.Pp +If the option +.Li -c +(or, equivalently, the +.Li %compare-strncmp +declaration) is not used, +.Va str +must be a NUL terminated string of exactly length +.Va len . +If +.Li -c +(or, equivalently, the +.Li %compare-strncmp +declaration) is used, +.Va str +must simply be an array of +.Va len +bytes and does not need to be NUL terminated. +.Pp +The code generated for these two functions is affected by the following options: +.Pp +.Bl -tag -width Ds +.It -t +.It --struct-type +Make use of the user-defined +.Li struct . +.Pp +.It -S Va total-switch-statements +.It --switch= Va total-switch-statements +Generate 1 or more C +.Li switch +statement rather than use a large, (and potentially sparse) static array. +Although the exact time and space savings of this approach vary according +to your C compiler's degree of optimization, this method often results in +smaller and faster code. +.El +.Pp +If the +.Li -t +and +.Li -S +options (or, equivalently, the +.Li %struct-type +and +.Li %switch +declarations) are omitted, the default action is to generate a +.Li char * +array containing the keywords, together with additional empty strings used +for padding the array. By experimenting with the various input and output +options, and timing the resulting C code, you can determine the best option +choices for different keyword set characteristics. +.Pp +.Ss Use of NUL bytes +By default, the code generated by +.Li gperf +operates on zero terminated strings, the usual representation of strings in +C. This means that the keywords in the input file must not contain NUL bytes, +and the +.Va str +argument passed to +.Li hash +or +.Li in_word_set +must be NUL terminated and have exactly length +.Va len . +.Pp +If option +.Li -c +(or, equivalently, the +.Li %compare-strncmp +declaration) is used, then the +.Va str +argument does not need to be NUL terminated. The code generated by +.Li gperf +will only access the first +.Va len , +not +.Va len+1 , +bytes starting at +.Va str . +However, the keywords in the input file still must not contain NUL bytes. +.Pp +If option +.Li -l +(or, equivalently, the +.Li %compare-lengths +declaration) is used, then the hash table performs binary comparison. The +keywords in the input file may contain NUL bytes, written in string syntax +as +.Li \e000 +or +.Li \ex00 , +and the code generated by +.Li gperf +will treat NUL like any other byte. Also, in this case the +.Li -c +option (or, equivalently, the +.Li %compare-strncmp +declaration) is ignored. +.Pp +.Sh Invoking Li gperf +There are +.Em many +options to +.Li gperf . +They were added to make the program more convenient for use with real applications. +\(lqOn-line\(rq help is readily available via the +.Li --help +option. Here is the complete list of options. +.Pp +.Ss Specifying the Location of the Output File +.Bl -tag -width Ds +.It --output-file= Va file +Allows you to specify the name of the file to which the output is written +to. +.El +.Pp +The results are written to standard output if no output file is specified +or if it is +.Li - . +.Pp +.Ss Options that affect Interpretation of the Input File +These options are also available as declarations in the input file (see Section +.Dq Gperf Declarations ) . +.Pp +.Bl -tag -width Ds +.It -e Va keyword-delimiter-list +.It --delimiters= Va keyword-delimiter-list +Allows you to provide a string containing delimiters used to separate keywords +from their attributes. The default is ",". This option is essential if you +want to use keywords that have embedded commas or newlines. One useful trick +is to use -e'TAB', where TAB is the literal tab character. +.Pp +.It -t +.It --struct-type +Allows you to include a +.Li struct +type declaration for generated code. Any text before a pair of consecutive +.Li %% +is considered part of the type declaration. Keywords and additional fields +may follow this, one group of fields per line. A set of examples for generating +perfect hash tables and functions for Ada, C, C++, Pascal, Modula 2, Modula +3 and JavaScript reserved words are distributed with this release. +.Pp +.It --ignore-case +Consider upper and lower case ASCII characters as equivalent. The string comparison +will use a case insignificant character comparison. Note that locale dependent +case mappings are ignored. This option is therefore not suitable if a properly +internationalized or locale aware case mapping should be used. (For example, +in a Turkish locale, the upper case equivalent of the lowercase ASCII letter +.Li i +is the non-ASCII character +.Li capital i with dot above . ) +For this case, it is better to apply an uppercase or lowercase conversion +on the string before passing it to the +.Li gperf +generated function. +.El +.Pp +.Ss Options to specify the Language for the Output Code +These options are also available as declarations in the input file (see Section +.Dq Gperf Declarations ) . +.Pp +.Bl -tag -width Ds +.It -L Va generated-language-name +.It --language= Va generated-language-name +Instructs +.Li gperf +to generate code in the language specified by the option's argument. Languages +handled are currently: +.Pp +.Bl -tag -width Ds +.It KR-C +Old-style K&R C. This language is understood by old-style C compilers and +ANSI C compilers, but ANSI C compilers may flag warnings (or even errors) +because of lacking +.Li const . +.Pp +.It C +Common C. This language is understood by ANSI C compilers, and also by old-style +C compilers, provided that you +.Li #define const +to empty for compilers which don't know about this keyword. +.Pp +.It ANSI-C +ANSI C. This language is understood by ANSI C compilers and C++ compilers. +.Pp +.It C++ +C++. This language is understood by C++ compilers. +.El +.Pp +The default is C. +.Pp +.It -a +This option is supported for compatibility with previous releases of +.Li gperf . +It does not do anything. +.Pp +.It -g +This option is supported for compatibility with previous releases of +.Li gperf . +It does not do anything. +.El +.Pp +.Ss Options for fine tuning Details in the Output Code +Most of these options are also available as declarations in the input file +(see Section +.Dq Gperf Declarations ) . +.Pp +.Bl -tag -width Ds +.It -K Va slot-name +.It --slot-name= Va slot-name +This option is only useful when option +.Li -t +(or, equivalently, the +.Li %struct-type +declaration) has been given. By default, the program assumes the structure +component identifier for the keyword is +.Li name . +This option allows an arbitrary choice of identifier for this component, although +it still must occur as the first field in your supplied +.Li struct . +.Pp +.It -F Va initializers +.It --initializer-suffix= Va initializers +This option is only useful when option +.Li -t +(or, equivalently, the +.Li %struct-type +declaration) has been given. It permits to specify initializers for the structure +members following +.Va slot-name +in empty hash table entries. The list of initializers should start with a +comma. By default, the emitted code will zero-initialize structure members +following +.Va slot-name . +.Pp +.It -H Va hash-function-name +.It --hash-function-name= Va hash-function-name +Allows you to specify the name for the generated hash function. Default name +is +.Li hash . +This option permits the use of two hash tables in the same file. +.Pp +.It -N Va lookup-function-name +.It --lookup-function-name= Va lookup-function-name +Allows you to specify the name for the generated lookup function. Default +name is +.Li in_word_set . +This option permits multiple generated hash functions to be used in the same +application. +.Pp +.It -Z Va class-name +.It --class-name= Va class-name +This option is only useful when option +.Li -L C++ +(or, equivalently, the +.Li %language=C++ +declaration) has been given. It allows you to specify the name of generated +C++ class. Default name is +.Li Perfect_Hash . +.Pp +.It -7 +.It --seven-bit +This option specifies that all strings that will be passed as arguments to +the generated hash function and the generated lookup function will solely +consist of 7-bit ASCII characters (bytes in the range 0..127). (Note that +the ANSI C functions +.Li isalnum +and +.Li isgraph +do +.Em not +guarantee that a byte is in this range. Only an explicit test like +.Li c >= 'A' && c <= 'Z' +guarantees this.) This was the default in versions of +.Li gperf +earlier than 2.7; now the default is to support 8-bit and multibyte characters. +.Pp +.It -l +.It --compare-lengths +Compare keyword lengths before trying a string comparison. This option is +mandatory for binary comparisons (see Section +.Dq Binary Strings ) . +It also might cut down on the number of string comparisons made during the +lookup, since keywords with different lengths are never compared via +.Li strcmp . +However, using +.Li -l +might greatly increase the size of the generated C code if the lookup table +range is large (which implies that the switch option +.Li -S +or +.Li %switch +is not enabled), since the length table contains as many elements as there +are entries in the lookup table. +.Pp +.It -c +.It --compare-strncmp +Generates C code that uses the +.Li strncmp +function to perform string comparisons. The default action is to use +.Li strcmp . +.Pp +.It -C +.It --readonly-tables +Makes the contents of all generated lookup tables constant, i.e., \(lqreadonly\(rq. +Many compilers can generate more efficient code for this by putting the tables +in readonly memory. +.Pp +.It -E +.It --enum +Define constant values using an enum local to the lookup function rather than +with #defines. This also means that different lookup functions can reside +in the same file. Thanks to James Clark +.Li <jjc@ai.mit.edu> . +.Pp +.It -I +.It --includes +Include the necessary system include file, +.Li <string.h> , +at the beginning of the code. By default, this is not done; the user must +include this header file himself to allow compilation of the code. +.Pp +.It -G +.It --global-table +Generate the static table of keywords as a static global variable, rather +than hiding it inside of the lookup function (which is the default behavior). +.Pp +.It -P +.It --pic +Optimize the generated table for inclusion in shared libraries. This reduces +the startup time of programs using a shared library containing the generated +code. If the option +.Li -t +(or, equivalently, the +.Li %struct-type +declaration) is also given, the first field of the user-defined struct must +be of type +.Li int , +not +.Li char * , +because it will contain offsets into the string pool instead of actual strings. +To convert such an offset to a string, you can use the expression +.Li stringpool + Va o , +where +.Va o +is the offset. The string pool name can be changed through the option +.Li --string-pool-name . +.Pp +.It -Q Va string-pool-name +.It --string-pool-name= Va string-pool-name +Allows you to specify the name of the generated string pool created by option +.Li -P . +The default name is +.Li stringpool . +This option permits the use of two hash tables in the same file, with +.Li -P +and even when the option +.Li -G +(or, equivalently, the +.Li %global-table +declaration) is given. +.Pp +.It --null-strings +Use NULL strings instead of empty strings for empty keyword table entries. +This reduces the startup time of programs using a shared library containing +the generated code (but not as much as option +.Li -P ) , +at the expense of one more test-and-branch instruction at run time. +.Pp +.It -W Va hash-table-array-name +.It --word-array-name= Va hash-table-array-name +Allows you to specify the name for the generated array containing the hash +table. Default name is +.Li wordlist . +This option permits the use of two hash tables in the same file, even when +the option +.Li -G +(or, equivalently, the +.Li %global-table +declaration) is given. +.Pp +.It --length-table-name= Va length-table-array-name +Allows you to specify the name for the generated array containing the length +table. Default name is +.Li lengthtable . +This option permits the use of two length tables in the same file, even when +the option +.Li -G +(or, equivalently, the +.Li %global-table +declaration) is given. +.Pp +.It -S Va total-switch-statements +.It --switch= Va total-switch-statements +Causes the generated C code to use a +.Li switch +statement scheme, rather than an array lookup table. This can lead to a reduction +in both time and space requirements for some input files. The argument to +this option determines how many +.Li switch +statements are generated. A value of 1 generates 1 +.Li switch +containing all the elements, a value of 2 generates 2 tables with 1/2 the +elements in each +.Li switch , +etc. This is useful since many C compilers cannot correctly generate code +for large +.Li switch +statements. This option was inspired in part by Keith Bostic's original C +program. +.Pp +.It -T +.It --omit-struct-type +Prevents the transfer of the type declaration to the output file. Use this +option if the type is already defined elsewhere. +.Pp +.It -p +This option is supported for compatibility with previous releases of +.Li gperf . +It does not do anything. +.El +.Pp +.Ss Options for changing the Algorithms employed by Li gperf +.Bl -tag -width Ds +.It -k Va selected-byte-positions +.It --key-positions= Va selected-byte-positions +Allows selection of the byte positions used in the keywords' hash function. +The allowable choices range between 1-255, inclusive. The positions are separated +by commas, e.g., +.Li -k 9,4,13,14 +; ranges may be used, e.g., +.Li -k 2-7 +; and positions may occur in any order. Furthermore, the wildcard '*' causes +the generated hash function to consider +.Sy all +byte positions in each keyword, whereas '$' instructs the hash function to +use the \(lqfinal byte\(rq of a keyword (this is the only way to use a byte position +greater than 255, incidentally). +.Pp +For instance, the option +.Li -k 1,2,4,6-10,'$' +generates a hash function that considers positions 1,2,4,6,7,8,9,10, plus +the last byte in each keyword (which may be at a different position for each +keyword, obviously). Keywords with length less than the indicated byte positions +work properly, since selected byte positions exceeding the keyword length +are simply not referenced in the hash function. +.Pp +This option is not normally needed since version 2.8 of +.Li gperf +; the default byte positions are computed depending on the keyword set, through +a search that minimizes the number of byte positions. +.Pp +.It -D +.It --duplicates +Handle keywords whose selected byte sets hash to duplicate values. Duplicate +hash values can occur if a set of keywords has the same names, but possesses +different attributes, or if the selected byte positions are not well chosen. +With the -D option +.Li gperf +treats all these keywords as part of an equivalence class and generates a +perfect hash function with multiple comparisons for duplicate keywords. It +is up to you to completely disambiguate the keywords by modifying the generated +C code. However, +.Li gperf +helps you out by organizing the output. +.Pp +Using this option usually means that the generated hash function is no longer +perfect. On the other hand, it permits +.Li gperf +to work on keyword sets that it otherwise could not handle. +.Pp +.It -m Va iterations +.It --multiple-iterations= Va iterations +Perform multiple choices of the +.Li -i +and +.Li -j +values, and choose the best results. This increases the running time by a +factor of +.Va iterations +but does a good job minimizing the generated table size. +.Pp +.It -i Va initial-value +.It --initial-asso= Va initial-value +Provides an initial +.Va value +for the associate values array. Default is 0. Increasing the initial value +helps inflate the final table size, possibly leading to more time efficient +keyword lookups. Note that this option is not particularly useful when +.Li -S +(or, equivalently, +.Li %switch ) +is used. Also, +.Li -i +is overridden when the +.Li -r +option is used. +.Pp +.It -j Va jump-value +.It --jump= Va jump-value +Affects the \(lqjump value\(rq, i.e., how far to advance the associated byte value +upon collisions. +.Va Jump-value +is rounded up to an odd number, the default is 5. If the +.Va jump-value +is 0 +.Li gperf +jumps by random amounts. +.Pp +.It -n +.It --no-strlen +Instructs the generator not to include the length of a keyword when computing +its hash value. This may save a few assembly instructions in the generated +lookup table. +.Pp +.It -r +.It --random +Utilizes randomness to initialize the associated values table. This frequently +generates solutions faster than using deterministic initialization (which +starts all associated values at 0). Furthermore, using the randomization option +generally increases the size of the table. +.Pp +.It -s Va size-multiple +.It --size-multiple= Va size-multiple +Affects the size of the generated hash table. The numeric argument for this +option indicates \(lqhow many times larger or smaller\(rq the maximum associated value +range should be, in relationship to the number of keywords. It can be written +as an integer, a floating-point number or a fraction. For example, a value +of 3 means \(lqallow the maximum associated value to be about 3 times larger than +the number of input keywords\(rq. Conversely, a value of 1/3 means \(lqallow the maximum +associated value to be about 3 times smaller than the number of input keywords\(rq. +Values smaller than 1 are useful for limiting the overall size of the generated +hash table, though the option +.Li -m +is better at this purpose. +.Pp +If `generate switch' option +.Li -S +(or, equivalently, +.Li %switch ) +is +.Em not +enabled, the maximum associated value influences the static array table size, +and a larger table should decrease the time required for an unsuccessful search, +at the expense of extra table space. +.Pp +The default value is 1, thus the default maximum associated value about the +same size as the number of keywords (for efficiency, the maximum associated +value is always rounded up to a power of 2). The actual table size may vary +somewhat, since this technique is essentially a heuristic. +.El +.Pp +.Ss Informative Output +.Bl -tag -width Ds +.It -h +.It --help +Prints a short summary on the meaning of each program option. Aborts further +program execution. +.Pp +.It -v +.It --version +Prints out the current version number. +.Pp +.It -d +.It --debug +Enables the debugging option. This produces verbose diagnostics to \(lqstandard +error\(rq when +.Li gperf +is executing. It is useful both for maintaining the program and for determining +whether a given set of options is actually speeding up the search for a solution. +Some useful information is dumped at the end of the program when the +.Li -d +option is enabled. +.El +.Pp +.Sh Known Bugs and Limitations with Li gperf +The following are some limitations with the current release of +.Li gperf : +.Pp +.Bl -bullet +.It +The +.Li gperf +utility is tuned to execute quickly, and works quickly for small to medium +size data sets (around 1000 keywords). It is extremely useful for maintaining +perfect hash functions for compiler keyword sets. Several recent enhancements +now enable +.Li gperf +to work efficiently on much larger keyword sets (over 15,000 keywords). When +processing large keyword sets it helps greatly to have over 8 megs of RAM. +.Pp +.It +The size of the generate static keyword array can get +.Em extremely +large if the input keyword file is large or if the keywords are quite similar. +This tends to slow down the compilation of the generated C code, and +.Em greatly +inflates the object code size. If this situation occurs, consider using the +.Li -S +option to reduce data size, potentially increasing keyword recognition time +a negligible amount. Since many C compilers cannot correctly generate code +for large switch statements it is important to qualify the +.Va -S +option with an appropriate numerical argument that controls the number of +switch statements generated. +.Pp +.It +The maximum number of selected byte positions has an arbitrary limit of 255. +This restriction should be removed, and if anyone considers this a problem +write me and let me know so I can remove the constraint. +.El +.Pp +.Sh Things Still Left to Do +It should be \(lqrelatively\(rq easy to replace the current perfect hash function +algorithm with a more exhaustive approach; the perfect hash module is essential +independent from other program modules. Additional worthwhile improvements +include: +.Pp +.Bl -bullet +.It +Another useful extension involves modifying the program to generate \(lqminimal\(rq +perfect hash functions (under certain circumstances, the current version can +be rather extravagant in the generated table size). This is mostly of theoretical +interest, since a sparse table often produces faster lookups, and use of the +.Li -S +.Li switch +option can minimize the data size, at the expense of slightly longer lookups +(note that the gcc compiler generally produces good code for +.Li switch +statements, reducing the need for more complex schemes). +.Pp +.It +In addition to improving the algorithm, it would also be useful to generate +an Ada package as the code output, in addition to the current C and C++ routines. +.El +.Pp +.Sh Bibliography +[1] Chang, C.C.: +.Em A Scheme for Constructing Ordered Minimal Perfect Hashing Functions +Information Sciences 39(1986), 187-195. +.Pp +[2] Cichelli, Richard J. +.Em Author's Response to \(lqOn Cichelli's Minimal Perfect Hash Functions Method\(rq +Communications of the ACM, 23, 12(December 1980), 729. +.Pp +[3] Cichelli, Richard J. +.Em Minimal Perfect Hash Functions Made Simple +Communications of the ACM, 23, 1(January 1980), 17-19. +.Pp +[4] Cook, C. R. and Oldehoeft, R.R. +.Em A Letter Oriented Minimal Perfect Hashing Function +SIGPLAN Notices, 17, 9(September 1982), 18-27. +.Pp +[5] Cormack, G. V. and Horspool, R. N. S. and Kaiserwerth, M. +.Em Practical Perfect Hashing +Computer Journal, 28, 1(January 1985), 54-58. +.Pp +[6] Jaeschke, G. +.Em Reciprocal Hashing: A Method for Generating Minimal Perfect Hashing Functions +Communications of the ACM, 24, 12(December 1981), 829-833. +.Pp +[7] Jaeschke, G. and Osterburg, G. +.Em On Cichelli's Minimal Perfect Hash Functions Method +Communications of the ACM, 23, 12(December 1980), 728-729. +.Pp +[8] Sager, Thomas J. +.Em A Polynomial Time Generator for Minimal Perfect Hash Functions +Communications of the ACM, 28, 5(December 1985), 523-532 +.Pp +[9] Schmidt, Douglas C. +.Em GPERF: A Perfect Hash Function Generator +Second USENIX C++ Conference Proceedings, April 1990. +.Pp +[10] Schmidt, Douglas C. +.Em GPERF: A Perfect Hash Function Generator +C++ Report, SIGS 10 10 (November/December 1998). +.Pp +[11] Sebesta, R.W. and Taylor, M.A. +.Em Minimal Perfect Hash Functions for Reserved Word Lists +SIGPLAN Notices, 20, 12(September 1985), 47-53. +.Pp +[12] Sprugnoli, R. +.Em Perfect Hashing Functions: A Single Probe Retrieving Method for Static Sets +Communications of the ACM, 20 11(November 1977), 841-850. +.Pp +[13] Stallman, Richard M. +.Em Using and Porting GNU CC +Free Software Foundation, 1988. +.Pp +[14] Stroustrup, Bjarne +.Em The C++ Programming Language. +Addison-Wesley, 1986. +.Pp +[15] Tiemann, Michael D. +.Em User's Guide to GNU C++ +Free Software Foundation, 1989. +.Pp +.Sh Concept Index diff --git a/contrib/libucl/ChangeLog.md b/contrib/libucl/ChangeLog.md index 0df5e072222e..093ff97a842d 100644 --- a/contrib/libucl/ChangeLog.md +++ b/contrib/libucl/ChangeLog.md @@ -20,3 +20,15 @@ ### Libucl 0.6.1 - Various utilities fixes + +### Libucl 0.7.0 + +- Move to klib library from uthash to reduce memory overhead and increase performance + +### Libucl 0.7.1 + +- Added safe iterators API + +### Libucl 0.7.2 + +- Fixed serious bugs in schema and arrays iteration diff --git a/contrib/libucl/Makefile.am b/contrib/libucl/Makefile.am index ece5b97df488..957e3a2b0f3c 100644 --- a/contrib/libucl/Makefile.am +++ b/contrib/libucl/Makefile.am @@ -1,5 +1,5 @@ ACLOCAL_AMFLAGS = -I m4 -EXTRA_DIST = uthash README.md +EXTRA_DIST = uthash klib README.md pkgconfigdir = $(libdir)/pkgconfig pkgconfig_DATA = libucl.pc diff --git a/contrib/libucl/README.md b/contrib/libucl/README.md index 235cfb6595df..797278ba932a 100644 --- a/contrib/libucl/README.md +++ b/contrib/libucl/README.md @@ -1,6 +1,6 @@ # LIBUCL -[](https://travis-ci.org/vstakhov/libucl) +[](https://travis-ci.org/vstakhov/libucl)[](https://scan.coverity.com/projects/4138) **Table of Contents** *generated with [DocToc](http://doctoc.herokuapp.com/)* @@ -156,10 +156,10 @@ is converted to the following object: ```nginx section { blah { - key = value; + key = value; } foo { - key = value; + key = value; } } ``` @@ -177,9 +177,9 @@ is presented as: ```nginx section { blah { - foo { - key = value; - } + foo { + key = value; + } } } ``` @@ -219,8 +219,8 @@ UCL supports external macros both multiline and single line ones: ```nginx .macro "sometext"; .macro { - Some long text - .... + Some long text + .... }; ``` diff --git a/contrib/libucl/cmake/CMakeLists.txt b/contrib/libucl/cmake/CMakeLists.txt index 3c57db53784a..e84f61905c58 100644 --- a/contrib/libucl/cmake/CMakeLists.txt +++ b/contrib/libucl/cmake/CMakeLists.txt @@ -82,6 +82,7 @@ ENDIF(ENABLE_URL_SIGN MATCHES "ON") INCLUDE_DIRECTORIES("${CMAKE_CURRENT_SOURCE_DIR}/../src") INCLUDE_DIRECTORIES("${CMAKE_CURRENT_SOURCE_DIR}/../include") INCLUDE_DIRECTORIES("${CMAKE_CURRENT_SOURCE_DIR}/../uthash") +INCLUDE_DIRECTORIES("${CMAKE_CURRENT_SOURCE_DIR}/../klib") SET(UCLSRC ../src/ucl_util.c ../src/ucl_parser.c diff --git a/contrib/libucl/configure.ac b/contrib/libucl/configure.ac index 32db73ad0fdd..be6f6522f121 100644 --- a/contrib/libucl/configure.ac +++ b/contrib/libucl/configure.ac @@ -1,7 +1,7 @@ m4_define([maj_ver], [0]) -m4_define([med_ver], [6]) -m4_define([min_ver], [1]) -m4_define([so_version], [3:0:1]) +m4_define([med_ver], [7]) +m4_define([min_ver], [2]) +m4_define([so_version], [5:0:1]) m4_define([ucl_version], [maj_ver.med_ver.min_ver]) AC_INIT([libucl],[ucl_version],[https://github.com/vstakhov/libucl],[libucl]) diff --git a/contrib/libucl/doc/Makefile.am b/contrib/libucl/doc/Makefile.am index c6223ecf24fd..2c7a588bf9a0 100644 --- a/contrib/libucl/doc/Makefile.am +++ b/contrib/libucl/doc/Makefile.am @@ -4,5 +4,6 @@ dist_man_MANS = libucl.3 gen-man: @PANDOC@ tail -n +$$(grep -n '# Synopsis' api.md | cut -d':' -f1) api.md | \ - cat pandoc.template - | sed -e 's/^# \(.*\)/# \U\1/' | \ + cat pandoc.template - | sed -e 's/^# \(.*\)/# \U\1/' \ + -e "s/%%date%%/$$(LANG=C date +'%d %B, %Y')/" | \ @PANDOC@ -s -f markdown -t man -o libucl.3 diff --git a/contrib/libucl/doc/api.md b/contrib/libucl/doc/api.md index 174c7ff47060..75b954bb302c 100644 --- a/contrib/libucl/doc/api.md +++ b/contrib/libucl/doc/api.md @@ -377,7 +377,9 @@ If parsing operations fail then the resulting UCL object will be a `UCL_STRING`. # Iteration functions -Iteration are used to iterate over UCL compound types: arrays and objects. Moreover, iterations could be performed over the keys with multiple values (implicit arrays). To iterate over an object, an array or a key with multiple values there is a function `ucl_iterate_object`. +Iteration are used to iterate over UCL compound types: arrays and objects. Moreover, iterations could be performed over the keys with multiple values (implicit arrays). +There are two types of iterators API: old and unsafe one via `ucl_iterate_object` and the proposed interface of safe iterators. + ## ucl_iterate_object ~~~C @@ -402,6 +404,60 @@ while ((obj = ucl_iterate_object (top, &it, true))) { } ~~~ +## Safe iterators API + +Safe iterators are defined to clarify iterating over UCL objects and simplify flattening of UCL objects in non-trivial cases. +For example, if there is an implicit array that contains another array and a boolean value it is extremely unclear how to iterate over +such an object. Safe iterators are desinged to define two sorts of iteration: + +1. Iteration over complex objects with expanding all values +2. Iteration over complex objects without expanding of values + +The following example demonstrates the difference between these two types of iteration: + +~~~ +key = 1; +key = [2, 3, 4]; + +Iteration with expansion: + +1, 2, 3, 4 + +Iteration without expansion: + +1, [2, 3, 4] +~~~ + +UCL defines the following functions to manage safe iterators: + +- `ucl_object_iterate_new` - creates new safe iterator +- `ucl_object_iterate_reset` - resets iterator to a new object +- `ucl_object_iterate_safe` - safely iterate the object inside iterator +- `ucl_object_iterate_free` - free memory associated with the safe iterator + +Please note that unlike unsafe iterators, safe iterators *must* be explicitly initialized and freed. +An assert is likely generated if you use uninitialized or `NULL` iterator in all safe iterators functions. + +~~~C +ucl_object_iter_t it; +const ucl_object_t *cur; + +it = ucl_object_iterate_new (obj); + +while ((cur = ucl_object_iterate_safe (it, true)) != NULL) { + /* Do something */ +} + +/* Switch to another object */ +it = ucl_object_iterate_reset (it, another_obj); + +while ((cur = ucl_object_iterate_safe (it, true)) != NULL) { + /* Do something else */ +} + +ucl_object_iterate_free (it); +~~~ + # Validation functions Currently, there is only one validation function called `ucl_object_validate`. It performs validation of object using the specified schema. This function is defined as following: diff --git a/contrib/libucl/doc/libucl.3 b/contrib/libucl/doc/libucl.3 index e319a0d3f932..ec5046325700 100644 --- a/contrib/libucl/doc/libucl.3 +++ b/contrib/libucl/doc/libucl.3 @@ -1,4 +1,4 @@ -.TH "LIBUCL" "3" "July 26, 2014" "Libucl manual" "" +.TH "LIBUCL" "3" "27 December, 2014" "Libucl manual" "" .SH NAME .PP \f[B]ucl_parser_new\f[], \f[B]ucl_parser_register_macro\f[], @@ -528,8 +528,9 @@ Iteration are used to iterate over UCL compound types: arrays and objects. Moreover, iterations could be performed over the keys with multiple values (implicit arrays). -To iterate over an object, an array or a key with multiple values there -is a function \f[C]ucl_iterate_object\f[]. +There are two types of iterators API: old and unsafe one via +\f[C]ucl_iterate_object\f[] and the proposed interface of safe +iterators. .SS ucl_iterate_object .IP .nf @@ -578,6 +579,75 @@ while\ ((obj\ =\ ucl_iterate_object\ (top,\ &it,\ true)))\ { } \f[] .fi +.SS Safe iterators API +.PP +Safe iterators are defined to clarify iterating over UCL objects and +simplify flattening of UCL objects in non\-trivial cases. +For example, if there is an implicit array that contains another array +and a boolean value it is extremely unclear how to iterate over such an +object. +Safe iterators are desinged to define two sorts of iteration: +.IP "1." 3 +Iteration over complex objects with expanding all values +.IP "2." 3 +Iteration over complex objects without expanding of values +.PP +The following example demonstrates the difference between these two +types of iteration: +.IP +.nf +\f[C] +key\ =\ 1; +key\ =\ [2,\ 3,\ 4]; + +Iteration\ with\ expansion: + +1,\ 2,\ 3,\ 4 + +Iteration\ without\ expansion: + +1,\ [2,\ 3,\ 4] +\f[] +.fi +.PP +UCL defines the following functions to manage safe iterators: +.IP \[bu] 2 +\f[C]ucl_object_iterate_new\f[] \- creates new safe iterator +.IP \[bu] 2 +\f[C]ucl_object_iterate_reset\f[] \- resets iterator to a new object +.IP \[bu] 2 +\f[C]ucl_object_iterate_safe\f[] \- safely iterate the object inside +iterator +.IP \[bu] 2 +\f[C]ucl_object_iterate_free\f[] \- free memory associated with the safe +iterator +.PP +Please note that unlike unsafe iterators, safe iterators \f[I]must\f[] +be explicitly initialized and freed. +An assert is likely generated if you use uninitialized or \f[C]NULL\f[] +iterator in all safe iterators functions. +.IP +.nf +\f[C] +ucl_object_iter_t\ it; +const\ ucl_object_t\ *cur; + +it\ =\ ucl_object_iterate_new\ (obj); + +while\ ((cur\ =\ ucl_object_iterate_safe\ (it,\ true))\ !=\ NULL)\ { +\ \ \ \ /*\ Do\ something\ */ +} + +/*\ Switch\ to\ another\ object\ */ +it\ =\ ucl_object_iterate_reset\ (it,\ another_obj); + +while\ ((cur\ =\ ucl_object_iterate_safe\ (it,\ true))\ !=\ NULL)\ { +\ \ \ \ /*\ Do\ something\ else\ */ +} + +ucl_object_iterate_free\ (it); +\f[] +.fi .SH VALIDATION FUNCTIONS .PP Currently, there is only one validation function called diff --git a/contrib/libucl/doc/pandoc.template b/contrib/libucl/doc/pandoc.template index 6d5f0277ae40..2effe1a157ef 100644 --- a/contrib/libucl/doc/pandoc.template +++ b/contrib/libucl/doc/pandoc.template @@ -1,6 +1,6 @@ % LIBUCL(3) Libucl manual % Vsevolod Stakhov <vsevolod@highsecure.ru> -% July 26, 2014 +% %%date%% # Name diff --git a/contrib/libucl/include/ucl.h b/contrib/libucl/include/ucl.h index 1aac6a25332c..823ac8d3bfc9 100644 --- a/contrib/libucl/include/ucl.h +++ b/contrib/libucl/include/ucl.h @@ -192,7 +192,7 @@ typedef struct ucl_object_s { int64_t iv; /**< Int value of an object */ const char *sv; /**< String value of an object */ double dv; /**< Double value of an object */ - struct ucl_object_s *av; /**< Array */ + void *av; /**< Array */ void *ov; /**< Object */ void* ud; /**< Opaque user data */ } value; @@ -715,6 +715,37 @@ typedef void* ucl_object_iter_t; */ UCL_EXTERN const ucl_object_t* ucl_iterate_object (const ucl_object_t *obj, ucl_object_iter_t *iter, bool expand_values); + +/** + * Create new safe iterator for the specified object + * @param obj object to iterate + * @return new iterator object that should be used with safe iterators API only + */ +UCL_EXTERN ucl_object_iter_t ucl_object_iterate_new (const ucl_object_t *obj) + UCL_WARN_UNUSED_RESULT; +/** + * Reset initialized iterator to a new object + * @param obj new object to iterate + * @return modified iterator object + */ +UCL_EXTERN ucl_object_iter_t ucl_object_iterate_reset (ucl_object_iter_t it, + const ucl_object_t *obj); + +/** + * Get the next object from the `obj`. This fucntion iterates over arrays, objects + * and implicit arrays + * @param iter safe iterator + * @return the next object in sequence + */ +UCL_EXTERN const ucl_object_t* ucl_object_iterate_safe (ucl_object_iter_t iter, + bool expand_values); + +/** + * Free memory associated with the safe iterator + * @param it safe iterator object + */ +UCL_EXTERN void ucl_object_iterate_free (ucl_object_iter_t it); + /** @} */ @@ -854,6 +885,13 @@ UCL_EXTERN ucl_object_t* ucl_parser_get_object (struct ucl_parser *parser); * @param parser parser object */ UCL_EXTERN const char *ucl_parser_get_error(struct ucl_parser *parser); + +/** + * Clear the error in the parser + * @param parser parser object + */ +UCL_EXTERN void ucl_parser_clear_error(struct ucl_parser *parser); + /** * Free ucl parser object * @param parser parser object diff --git a/contrib/libucl/klib/khash.h b/contrib/libucl/klib/khash.h new file mode 100644 index 000000000000..afc3ce3ef0dc --- /dev/null +++ b/contrib/libucl/klib/khash.h @@ -0,0 +1,627 @@ +/* The MIT License + + Copyright (c) 2008, 2009, 2011 by Attractive Chaos <attractor@live.co.uk> + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS + BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN + ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE. +*/ + +/* + An example: + +#include "khash.h" +KHASH_MAP_INIT_INT(32, char) +int main() { + int ret, is_missing; + khiter_t k; + khash_t(32) *h = kh_init(32); + k = kh_put(32, h, 5, &ret); + kh_value(h, k) = 10; + k = kh_get(32, h, 10); + is_missing = (k == kh_end(h)); + k = kh_get(32, h, 5); + kh_del(32, h, k); + for (k = kh_begin(h); k != kh_end(h); ++k) + if (kh_exist(h, k)) kh_value(h, k) = 1; + kh_destroy(32, h); + return 0; +} +*/ + +/* + 2013-05-02 (0.2.8): + + * Use quadratic probing. When the capacity is power of 2, stepping function + i*(i+1)/2 guarantees to traverse each bucket. It is better than double + hashing on cache performance and is more robust than linear probing. + + In theory, double hashing should be more robust than quadratic probing. + However, my implementation is probably not for large hash tables, because + the second hash function is closely tied to the first hash function, + which reduce the effectiveness of double hashing. + + Reference: http://research.cs.vt.edu/AVresearch/hashing/quadratic.php + + 2011-12-29 (0.2.7): + + * Minor code clean up; no actual effect. + + 2011-09-16 (0.2.6): + + * The capacity is a power of 2. This seems to dramatically improve the + speed for simple keys. Thank Zilong Tan for the suggestion. Reference: + + - http://code.google.com/p/ulib/ + - http://nothings.org/computer/judy/ + + * Allow to optionally use linear probing which usually has better + performance for random input. Double hashing is still the default as it + is more robust to certain non-random input. + + * Added Wang's integer hash function (not used by default). This hash + function is more robust to certain non-random input. + + 2011-02-14 (0.2.5): + + * Allow to declare global functions. + + 2009-09-26 (0.2.4): + + * Improve portability + + 2008-09-19 (0.2.3): + + * Corrected the example + * Improved interfaces + + 2008-09-11 (0.2.2): + + * Improved speed a little in kh_put() + + 2008-09-10 (0.2.1): + + * Added kh_clear() + * Fixed a compiling error + + 2008-09-02 (0.2.0): + + * Changed to token concatenation which increases flexibility. + + 2008-08-31 (0.1.2): + + * Fixed a bug in kh_get(), which has not been tested previously. + + 2008-08-31 (0.1.1): + + * Added destructor +*/ + + +#ifndef __AC_KHASH_H +#define __AC_KHASH_H + +/*! + @header + + Generic hash table library. + */ + +#define AC_VERSION_KHASH_H "0.2.8" + +#include <stdlib.h> +#include <string.h> +#include <limits.h> + +/* compiler specific configuration */ + +#if UINT_MAX == 0xffffffffu +typedef unsigned int khint32_t; +#elif ULONG_MAX == 0xffffffffu +typedef unsigned long khint32_t; +#endif + +#if ULONG_MAX == ULLONG_MAX +typedef unsigned long khint64_t; +#else +typedef unsigned long long khint64_t; +#endif + +#ifndef kh_inline +#ifdef _MSC_VER +#define kh_inline __inline +#else +#define kh_inline inline +#endif +#endif /* kh_inline */ + +#ifndef kh_unused +# ifdef __GNUC__ +# define kh_unused(x) __attribute__((__unused__)) x +# else +# define kh_unused(x) x +# endif +#endif + +typedef khint32_t khint_t; +typedef khint_t khiter_t; + +#define __ac_isempty(flag, i) ((flag[i>>4]>>((i&0xfU)<<1))&2) +#define __ac_isdel(flag, i) ((flag[i>>4]>>((i&0xfU)<<1))&1) +#define __ac_iseither(flag, i) ((flag[i>>4]>>((i&0xfU)<<1))&3) +#define __ac_set_isdel_false(flag, i) (flag[i>>4]&=~(1ul<<((i&0xfU)<<1))) +#define __ac_set_isempty_false(flag, i) (flag[i>>4]&=~(2ul<<((i&0xfU)<<1))) +#define __ac_set_isboth_false(flag, i) (flag[i>>4]&=~(3ul<<((i&0xfU)<<1))) +#define __ac_set_isdel_true(flag, i) (flag[i>>4]|=1ul<<((i&0xfU)<<1)) + +#define __ac_fsize(m) ((m) < 16? 1 : (m)>>4) + +#ifndef kroundup32 +#define kroundup32(x) (--(x), (x)|=(x)>>1, (x)|=(x)>>2, (x)|=(x)>>4, (x)|=(x)>>8, (x)|=(x)>>16, ++(x)) +#endif + +#ifndef kcalloc +#define kcalloc(N,Z) calloc(N,Z) +#endif +#ifndef kmalloc +#define kmalloc(Z) malloc(Z) +#endif +#ifndef krealloc +#define krealloc(P,Z) realloc(P,Z) +#endif +#ifndef kfree +#define kfree(P) free(P) +#endif + +static const double __ac_HASH_UPPER = 0.77; + +#define __KHASH_TYPE(name, khkey_t, khval_t) \ + typedef struct kh_##name##_s { \ + khint_t n_buckets, size, n_occupied, upper_bound; \ + khint32_t *flags; \ + khkey_t *keys; \ + khval_t *vals; \ + } kh_##name##_t; + +#define __KHASH_PROTOTYPES(name, khkey_t, khval_t) \ + extern kh_##name##_t * kh_init_##name(void); \ + extern void kh_destroy_##name(kh_##name##_t *h); \ + extern void kh_clear_##name(kh_##name##_t *h); \ + extern khint_t kh_get_##name(const kh_##name##_t *h, khkey_t key); \ + extern int kh_resize_##name(kh_##name##_t *h, khint_t new_n_buckets); \ + extern khint_t kh_put_##name(kh_##name##_t *h, khkey_t key, int *ret); \ + extern void kh_del_##name(kh_##name##_t *h, khint_t x); + +#define __KHASH_IMPL(name, SCOPE, khkey_t, khval_t, kh_is_map, __hash_func, __hash_equal) \ + SCOPE kh_##name##_t *kh_init_##name(void) { \ + return (kh_##name##_t*)kcalloc(1, sizeof(kh_##name##_t)); \ + } \ + SCOPE void kh_destroy_##name(kh_##name##_t *h) \ + { \ + if (h) { \ + kfree((void *)h->keys); kfree(h->flags); \ + kfree((void *)h->vals); \ + kfree(h); \ + } \ + } \ + SCOPE void kh_unused(kh_clear_##name)(kh_##name##_t *h) \ + { \ + if (h && h->flags) { \ + memset(h->flags, 0xaa, __ac_fsize(h->n_buckets) * sizeof(khint32_t)); \ + h->size = h->n_occupied = 0; \ + } \ + } \ + SCOPE khint_t kh_get_##name(const kh_##name##_t *h, khkey_t key) \ + { \ + if (h->n_buckets) { \ + khint_t k, i, last, mask, step = 0; \ + mask = h->n_buckets - 1; \ + k = __hash_func(key); i = k & mask; \ + last = i; \ + while (!__ac_isempty(h->flags, i) && (__ac_isdel(h->flags, i) || !__hash_equal(h->keys[i], key))) { \ + i = (i + (++step)) & mask; \ + if (i == last) return h->n_buckets; \ + } \ + return __ac_iseither(h->flags, i)? h->n_buckets : i; \ + } else return 0; \ + } \ + SCOPE int kh_resize_##name(kh_##name##_t *h, khint_t new_n_buckets) \ + { /* This function uses 0.25*n_buckets bytes of working space instead of [sizeof(key_t+val_t)+.25]*n_buckets. */ \ + khint32_t *new_flags = 0; \ + khint_t j = 1; \ + { \ + kroundup32(new_n_buckets); \ + if (new_n_buckets < 4) new_n_buckets = 4; \ + if (h->size >= (khint_t)(new_n_buckets * __ac_HASH_UPPER + 0.5)) j = 0; /* requested size is too small */ \ + else { /* hash table size to be changed (shrink or expand); rehash */ \ + new_flags = (khint32_t*)kmalloc(__ac_fsize(new_n_buckets) * sizeof(khint32_t)); \ + if (!new_flags) return -1; \ + memset(new_flags, 0xaa, __ac_fsize(new_n_buckets) * sizeof(khint32_t)); \ + if (h->n_buckets < new_n_buckets) { /* expand */ \ + khkey_t *new_keys = (khkey_t*)krealloc((void *)h->keys, new_n_buckets * sizeof(khkey_t)); \ + if (!new_keys) { kfree(new_flags); return -1; } \ + h->keys = new_keys; \ + if (kh_is_map) { \ + khval_t *new_vals = (khval_t*)krealloc((void *)h->vals, new_n_buckets * sizeof(khval_t)); \ + if (!new_vals) { kfree(new_flags); return -1; } \ + h->vals = new_vals; \ + } \ + } /* otherwise shrink */ \ + } \ + } \ + if (j) { /* rehashing is needed */ \ + for (j = 0; j != h->n_buckets; ++j) { \ + if (__ac_iseither(h->flags, j) == 0) { \ + khkey_t key = h->keys[j]; \ + khval_t val; \ + khint_t new_mask; \ + new_mask = new_n_buckets - 1; \ + if (kh_is_map) val = h->vals[j]; \ + __ac_set_isdel_true(h->flags, j); \ + while (1) { /* kick-out process; sort of like in Cuckoo hashing */ \ + khint_t k, i, step = 0; \ + k = __hash_func(key); \ + i = k & new_mask; \ + while (!__ac_isempty(new_flags, i)) i = (i + (++step)) & new_mask; \ + __ac_set_isempty_false(new_flags, i); \ + if (i < h->n_buckets && __ac_iseither(h->flags, i) == 0) { /* kick out the existing element */ \ + { khkey_t tmp = h->keys[i]; h->keys[i] = key; key = tmp; } \ + if (kh_is_map) { khval_t tmp = h->vals[i]; h->vals[i] = val; val = tmp; } \ + __ac_set_isdel_true(h->flags, i); /* mark it as deleted in the old hash table */ \ + } else { /* write the element and jump out of the loop */ \ + h->keys[i] = key; \ + if (kh_is_map) h->vals[i] = val; \ + break; \ + } \ + } \ + } \ + } \ + if (h->n_buckets > new_n_buckets) { /* shrink the hash table */ \ + h->keys = (khkey_t*)krealloc((void *)h->keys, new_n_buckets * sizeof(khkey_t)); \ + if (kh_is_map) h->vals = (khval_t*)krealloc((void *)h->vals, new_n_buckets * sizeof(khval_t)); \ + } \ + kfree(h->flags); /* free the working space */ \ + h->flags = new_flags; \ + h->n_buckets = new_n_buckets; \ + h->n_occupied = h->size; \ + h->upper_bound = (khint_t)(h->n_buckets * __ac_HASH_UPPER + 0.5); \ + } \ + return 0; \ + } \ + SCOPE khint_t kh_put_##name(kh_##name##_t *h, khkey_t key, int *ret) \ + { \ + khint_t x; \ + if (h->n_occupied >= h->upper_bound) { /* update the hash table */ \ + if (h->n_buckets > (h->size<<1)) { \ + if (kh_resize_##name(h, h->n_buckets - 1) < 0) { /* clear "deleted" elements */ \ + *ret = -1; return h->n_buckets; \ + } \ + } else if (kh_resize_##name(h, h->n_buckets + 1) < 0) { /* expand the hash table */ \ + *ret = -1; return h->n_buckets; \ + } \ + } /* TODO: to implement automatically shrinking; resize() already support shrinking */ \ + { \ + khint_t k, i, site, last, mask = h->n_buckets - 1, step = 0; \ + x = site = h->n_buckets; k = __hash_func(key); i = k & mask; \ + if (__ac_isempty(h->flags, i)) x = i; /* for speed up */ \ + else { \ + last = i; \ + while (!__ac_isempty(h->flags, i) && (__ac_isdel(h->flags, i) || !__hash_equal(h->keys[i], key))) { \ + if (__ac_isdel(h->flags, i)) site = i; \ + i = (i + (++step)) & mask; \ + if (i == last) { x = site; break; } \ + } \ + if (x == h->n_buckets) { \ + if (__ac_isempty(h->flags, i) && site != h->n_buckets) x = site; \ + else x = i; \ + } \ + } \ + } \ + if (__ac_isempty(h->flags, x)) { /* not present at all */ \ + h->keys[x] = key; \ + __ac_set_isboth_false(h->flags, x); \ + ++h->size; ++h->n_occupied; \ + *ret = 1; \ + } else if (__ac_isdel(h->flags, x)) { /* deleted */ \ + h->keys[x] = key; \ + __ac_set_isboth_false(h->flags, x); \ + ++h->size; \ + *ret = 2; \ + } else *ret = 0; /* Don't touch h->keys[x] if present and not deleted */ \ + return x; \ + } \ + SCOPE void kh_del_##name(kh_##name##_t *h, khint_t x) \ + { \ + if (x != h->n_buckets && !__ac_iseither(h->flags, x)) { \ + __ac_set_isdel_true(h->flags, x); \ + --h->size; \ + } \ + } + +#define KHASH_DECLARE(name, khkey_t, khval_t) \ + __KHASH_TYPE(name, khkey_t, khval_t) \ + __KHASH_PROTOTYPES(name, khkey_t, khval_t) + +#define KHASH_INIT2(name, SCOPE, khkey_t, khval_t, kh_is_map, __hash_func, __hash_equal) \ + __KHASH_TYPE(name, khkey_t, khval_t) \ + __KHASH_IMPL(name, SCOPE, khkey_t, khval_t, kh_is_map, __hash_func, __hash_equal) + +#define KHASH_INIT(name, khkey_t, khval_t, kh_is_map, __hash_func, __hash_equal) \ + KHASH_INIT2(name, static kh_inline, khkey_t, khval_t, kh_is_map, __hash_func, __hash_equal) + +/* --- BEGIN OF HASH FUNCTIONS --- */ + +/*! @function + @abstract Integer hash function + @param key The integer [khint32_t] + @return The hash value [khint_t] + */ +#define kh_int_hash_func(key) (khint32_t)(key) +/*! @function + @abstract Integer comparison function + */ +#define kh_int_hash_equal(a, b) ((a) == (b)) +/*! @function + @abstract 64-bit integer hash function + @param key The integer [khint64_t] + @return The hash value [khint_t] + */ +#define kh_int64_hash_func(key) (khint32_t)((key)>>33^(key)^(key)<<11) +/*! @function + @abstract 64-bit integer comparison function + */ +#define kh_int64_hash_equal(a, b) ((a) == (b)) +/*! @function + @abstract const char* hash function + @param s Pointer to a null terminated string + @return The hash value + */ +static kh_inline khint_t __ac_X31_hash_string(const char *s) +{ + khint_t h = (khint_t)*s; + if (h) for (++s ; *s; ++s) h = (h << 5) - h + (khint_t)*s; + return h; +} +/*! @function + @abstract Another interface to const char* hash function + @param key Pointer to a null terminated string [const char*] + @return The hash value [khint_t] + */ +#define kh_str_hash_func(key) __ac_X31_hash_string(key) +/*! @function + @abstract Const char* comparison function + */ +#define kh_str_hash_equal(a, b) (strcmp(a, b) == 0) + +static kh_inline khint_t __ac_Wang_hash(khint_t key) +{ + key += ~(key << 15); + key ^= (key >> 10); + key += (key << 3); + key ^= (key >> 6); + key += ~(key << 11); + key ^= (key >> 16); + return key; +} +#define kh_int_hash_func2(k) __ac_Wang_hash((khint_t)key) + +/* --- END OF HASH FUNCTIONS --- */ + +/* Other convenient macros... */ + +/*! + @abstract Type of the hash table. + @param name Name of the hash table [symbol] + */ +#define khash_t(name) kh_##name##_t + +/*! @function + @abstract Initiate a hash table. + @param name Name of the hash table [symbol] + @return Pointer to the hash table [khash_t(name)*] + */ +#define kh_init(name) kh_init_##name() + +/*! @function + @abstract Destroy a hash table. + @param name Name of the hash table [symbol] + @param h Pointer to the hash table [khash_t(name)*] + */ +#define kh_destroy(name, h) kh_destroy_##name(h) + +/*! @function + @abstract Reset a hash table without deallocating memory. + @param name Name of the hash table [symbol] + @param h Pointer to the hash table [khash_t(name)*] + */ +#define kh_clear(name, h) kh_clear_##name(h) + +/*! @function + @abstract Resize a hash table. + @param name Name of the hash table [symbol] + @param h Pointer to the hash table [khash_t(name)*] + @param s New size [khint_t] + */ +#define kh_resize(name, h, s) kh_resize_##name(h, s) + +/*! @function + @abstract Insert a key to the hash table. + @param name Name of the hash table [symbol] + @param h Pointer to the hash table [khash_t(name)*] + @param k Key [type of keys] + @param r Extra return code: -1 if the operation failed; + 0 if the key is present in the hash table; + 1 if the bucket is empty (never used); 2 if the element in + the bucket has been deleted [int*] + @return Iterator to the inserted element [khint_t] + */ +#define kh_put(name, h, k, r) kh_put_##name(h, k, r) + +/*! @function + @abstract Retrieve a key from the hash table. + @param name Name of the hash table [symbol] + @param h Pointer to the hash table [khash_t(name)*] + @param k Key [type of keys] + @return Iterator to the found element, or kh_end(h) if the element is absent [khint_t] + */ +#define kh_get(name, h, k) kh_get_##name(h, k) + +/*! @function + @abstract Remove a key from the hash table. + @param name Name of the hash table [symbol] + @param h Pointer to the hash table [khash_t(name)*] + @param k Iterator to the element to be deleted [khint_t] + */ +#define kh_del(name, h, k) kh_del_##name(h, k) + +/*! @function + @abstract Test whether a bucket contains data. + @param h Pointer to the hash table [khash_t(name)*] + @param x Iterator to the bucket [khint_t] + @return 1 if containing data; 0 otherwise [int] + */ +#define kh_exist(h, x) (!__ac_iseither((h)->flags, (x))) + +/*! @function + @abstract Get key given an iterator + @param h Pointer to the hash table [khash_t(name)*] + @param x Iterator to the bucket [khint_t] + @return Key [type of keys] + */ +#define kh_key(h, x) ((h)->keys[x]) + +/*! @function + @abstract Get value given an iterator + @param h Pointer to the hash table [khash_t(name)*] + @param x Iterator to the bucket [khint_t] + @return Value [type of values] + @discussion For hash sets, calling this results in segfault. + */ +#define kh_val(h, x) ((h)->vals[x]) + +/*! @function + @abstract Alias of kh_val() + */ +#define kh_value(h, x) ((h)->vals[x]) + +/*! @function + @abstract Get the start iterator + @param h Pointer to the hash table [khash_t(name)*] + @return The start iterator [khint_t] + */ +#define kh_begin(h) (khint_t)(0) + +/*! @function + @abstract Get the end iterator + @param h Pointer to the hash table [khash_t(name)*] + @return The end iterator [khint_t] + */ +#define kh_end(h) ((h)->n_buckets) + +/*! @function + @abstract Get the number of elements in the hash table + @param h Pointer to the hash table [khash_t(name)*] + @return Number of elements in the hash table [khint_t] + */ +#define kh_size(h) ((h)->size) + +/*! @function + @abstract Get the number of buckets in the hash table + @param h Pointer to the hash table [khash_t(name)*] + @return Number of buckets in the hash table [khint_t] + */ +#define kh_n_buckets(h) ((h)->n_buckets) + +/*! @function + @abstract Iterate over the entries in the hash table + @param h Pointer to the hash table [khash_t(name)*] + @param kvar Variable to which key will be assigned + @param vvar Variable to which value will be assigned + @param code Block of code to execute + */ +#define kh_foreach(h, kvar, vvar, code) { khint_t __i; \ + for (__i = kh_begin(h); __i != kh_end(h); ++__i) { \ + if (!kh_exist(h,__i)) continue; \ + (kvar) = kh_key(h,__i); \ + (vvar) = kh_val(h,__i); \ + code; \ + } } + +/*! @function + @abstract Iterate over the values in the hash table + @param h Pointer to the hash table [khash_t(name)*] + @param vvar Variable to which value will be assigned + @param code Block of code to execute + */ +#define kh_foreach_value(h, vvar, code) { khint_t __i; \ + for (__i = kh_begin(h); __i != kh_end(h); ++__i) { \ + if (!kh_exist(h,__i)) continue; \ + (vvar) = kh_val(h,__i); \ + code; \ + } } + +/* More conenient interfaces */ + +/*! @function + @abstract Instantiate a hash set containing integer keys + @param name Name of the hash table [symbol] + */ +#define KHASH_SET_INIT_INT(name) \ + KHASH_INIT(name, khint32_t, char, 0, kh_int_hash_func, kh_int_hash_equal) + +/*! @function + @abstract Instantiate a hash map containing integer keys + @param name Name of the hash table [symbol] + @param khval_t Type of values [type] + */ +#define KHASH_MAP_INIT_INT(name, khval_t) \ + KHASH_INIT(name, khint32_t, khval_t, 1, kh_int_hash_func, kh_int_hash_equal) + +/*! @function + @abstract Instantiate a hash map containing 64-bit integer keys + @param name Name of the hash table [symbol] + */ +#define KHASH_SET_INIT_INT64(name) \ + KHASH_INIT(name, khint64_t, char, 0, kh_int64_hash_func, kh_int64_hash_equal) + +/*! @function + @abstract Instantiate a hash map containing 64-bit integer keys + @param name Name of the hash table [symbol] + @param khval_t Type of values [type] + */ +#define KHASH_MAP_INIT_INT64(name, khval_t) \ + KHASH_INIT(name, khint64_t, khval_t, 1, kh_int64_hash_func, kh_int64_hash_equal) + +typedef const char *kh_cstr_t; +/*! @function + @abstract Instantiate a hash map containing const char* keys + @param name Name of the hash table [symbol] + */ +#define KHASH_SET_INIT_STR(name) \ + KHASH_INIT(name, kh_cstr_t, char, 0, kh_str_hash_func, kh_str_hash_equal) + +/*! @function + @abstract Instantiate a hash map containing const char* keys + @param name Name of the hash table [symbol] + @param khval_t Type of values [type] + */ +#define KHASH_MAP_INIT_STR(name, khval_t) \ + KHASH_INIT(name, kh_cstr_t, khval_t, 1, kh_str_hash_func, kh_str_hash_equal) + +#endif /* __AC_KHASH_H */ diff --git a/contrib/libucl/klib/kvec.h b/contrib/libucl/klib/kvec.h new file mode 100644 index 000000000000..b5cce8508f8e --- /dev/null +++ b/contrib/libucl/klib/kvec.h @@ -0,0 +1,103 @@ +/* The MIT License + + Copyright (c) 2008, by Attractive Chaos <attractor@live.co.uk> + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS + BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN + ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE. +*/ + +/* + An example: + +#include "kvec.h" +int main() { + kvec_t(int) array; + kv_init(array); + kv_push(int, array, 10); // append + kv_a(int, array, 20) = 5; // dynamic + kv_A(array, 20) = 4; // static + kv_destroy(array); + return 0; +} +*/ + +/* + 2008-09-22 (0.1.0): + + * The initial version. + +*/ + +#ifndef AC_KVEC_H +#define AC_KVEC_H + +#include <stdlib.h> + +#define kv_roundup32(x) (--(x), (x)|=(x)>>1, (x)|=(x)>>2, (x)|=(x)>>4, (x)|=(x)>>8, (x)|=(x)>>16, ++(x)) + +#define kvec_t(type) struct { size_t n, m; type *a; } +#define kv_init(v) ((v).n = (v).m = 0, (v).a = 0) +#define kv_destroy(v) free((v).a) +#define kv_A(v, i) ((v).a[(i)]) +#define kv_pop(v) ((v).a[--(v).n]) +#define kv_size(v) ((v).n) +#define kv_max(v) ((v).m) + +#define kv_resize(type, v, s) ((v).m = (s), (v).a = (type*)realloc((v).a, sizeof(type) * (v).m)) +#define kv_grow_factor 1.5 +#define kv_grow(type, v) ((v).m = ((v).m > 1 ? (v).m * kv_grow_factor : 2), \ + (v).a = (type*)realloc((v).a, sizeof(type) * (v).m)) + +#define kv_copy(type, v1, v0) do { \ + if ((v1).m < (v0).n) kv_resize(type, v1, (v0).n); \ + (v1).n = (v0).n; \ + memcpy((v1).a, (v0).a, sizeof(type) * (v0).n); \ + } while (0) \ + +#define kv_push(type, v, x) do { \ + if ((v).n == (v).m) { \ + kv_grow(type, v); \ + } \ + (v).a[(v).n++] = (x); \ + } while (0) + +#define kv_prepend(type, v, x) do { \ + if ((v).n == (v).m) { \ + kv_grow(type, v); \ + } \ + memmove((v).a + 1, (v).a, sizeof(type) * (v).n); \ + (v).a[0] = (x); \ + (v).n ++; \ +} while (0) + +#define kv_concat(type, v1, v0) do { \ + if ((v1).m < (v0).n + (v1).n) kv_resize(type, v1, (v0).n + (v1).n); \ + memcpy((v1).a + (v1).n, (v0).a, sizeof(type) * ((v0).n + (v1).n)); \ + (v1).n = (v0).n + (v1).n; \ + } while (0) + +#define kv_del(type, v, i) do { \ + if ((i) < (v).n) { \ + memmove((v).a + (i), (v).a + ((i) + 1), sizeof(type) * ((v).n - (i) - 1)); \ + (v).n --; \ + } \ +} while (0) + +#endif diff --git a/contrib/libucl/m4/.gitignore b/contrib/libucl/m4/.gitignore deleted file mode 100644 index 5e7d2734cfc6..000000000000 --- a/contrib/libucl/m4/.gitignore +++ /dev/null @@ -1,4 +0,0 @@ -# Ignore everything in this directory -* -# Except this file -!.gitignore diff --git a/contrib/libucl/m4/ax_lua.m4 b/contrib/libucl/m4/ax_lua.m4 deleted file mode 100644 index 7662f4f22d1b..000000000000 --- a/contrib/libucl/m4/ax_lua.m4 +++ /dev/null @@ -1,606 +0,0 @@ -# =========================================================================== -# http://www.gnu.org/software/autoconf-archive/ax_lua.html -# =========================================================================== -# -# SYNOPSIS -# -# AX_PROG_LUA[([MINIMUM-VERSION], [TOO-BIG-VERSION], [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND])] -# AX_LUA_HEADERS[([ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND])] -# AX_LUA_LIBS[([ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND])] -# AX_LUA_READLINE[([ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND])] -# -# DESCRIPTION -# -# Detect a Lua interpreter, optionally specifying a minimum and maximum -# version number. Set up important Lua paths, such as the directories in -# which to install scripts and modules (shared libraries). -# -# Also detect Lua headers and libraries. The Lua version contained in the -# header is checked to match the Lua interpreter version exactly. When -# searching for Lua libraries, the version number is used as a suffix. -# This is done with the goal of supporting multiple Lua installs (5.1 and -# 5.2 side-by-side). -# -# A note on compatibility with previous versions: This file has been -# mostly rewritten for serial 18. Most developers should be able to use -# these macros without needing to modify configure.ac. Care has been taken -# to preserve each macro's behavior, but there are some differences: -# -# 1) AX_WITH_LUA is deprecated; it now expands to the exact same thing as -# AX_PROG_LUA with no arguments. -# -# 2) AX_LUA_HEADERS now checks that the version number defined in lua.h -# matches the interpreter version. AX_LUA_HEADERS_VERSION is therefore -# unnecessary, so it is deprecated and does not expand to anything. -# -# 3) The configure flag --with-lua-suffix no longer exists; the user -# should instead specify the LUA precious variable on the command line. -# See the AX_PROG_LUA description for details. -# -# Please read the macro descriptions below for more information. -# -# This file was inspired by Andrew Dalke's and James Henstridge's -# python.m4 and Tom Payne's, Matthieu Moy's, and Reuben Thomas's ax_lua.m4 -# (serial 17). Basically, this file is a mash-up of those two files. I -# like to think it combines the best of the two! -# -# AX_PROG_LUA: Search for the Lua interpreter, and set up important Lua -# paths. Adds precious variable LUA, which may contain the path of the Lua -# interpreter. If LUA is blank, the user's path is searched for an -# suitable interpreter. -# -# If MINIMUM-VERSION is supplied, then only Lua interpreters with a -# version number greater or equal to MINIMUM-VERSION will be accepted. If -# TOO-BIG- VERSION is also supplied, then only Lua interpreters with a -# version number greater or equal to MINIMUM-VERSION and less than -# TOO-BIG-VERSION will be accepted. -# -# The Lua version number, LUA_VERSION, is found from the interpreter, and -# substituted. LUA_PLATFORM is also found, but not currently supported (no -# standard representation). -# -# Finally, the macro finds four paths: -# -# luadir Directory to install Lua scripts. -# pkgluadir $luadir/$PACKAGE -# luaexecdir Directory to install Lua modules. -# pkgluaexecdir $luaexecdir/$PACKAGE -# -# These paths a found based on $prefix, $exec_prefix, Lua's package.path, -# and package.cpath. The first path of package.path beginning with $prefix -# is selected as luadir. The first path of package.cpath beginning with -# $exec_prefix is used as luaexecdir. This should work on all reasonable -# Lua installations. If a path cannot be determined, a default path is -# used. Of course, the user can override these later when invoking make. -# -# luadir Default: $prefix/share/lua/$LUA_VERSION -# luaexecdir Default: $exec_prefix/lib/lua/$LUA_VERSION -# -# These directories can be used by Automake as install destinations. The -# variable name minus 'dir' needs to be used as a prefix to the -# appropriate Automake primary, e.g. lua_SCRIPS or luaexec_LIBRARIES. -# -# If an acceptable Lua interpreter is found, then ACTION-IF-FOUND is -# performed, otherwise ACTION-IF-NOT-FOUND is preformed. If ACTION-IF-NOT- -# FOUND is blank, then it will default to printing an error. To prevent -# the default behavior, give ':' as an action. -# -# AX_LUA_HEADERS: Search for Lua headers. Requires that AX_PROG_LUA be -# expanded before this macro. Adds precious variable LUA_INCLUDE, which -# may contain Lua specific include flags, e.g. -I/usr/include/lua5.1. If -# LUA_INCLUDE is blank, then this macro will attempt to find suitable -# flags. -# -# LUA_INCLUDE can be used by Automake to compile Lua modules or -# executables with embedded interpreters. The *_CPPFLAGS variables should -# be used for this purpose, e.g. myprog_CPPFLAGS = $(LUA_INCLUDE). -# -# This macro searches for the header lua.h (and others). The search is -# performed with a combination of CPPFLAGS, CPATH, etc, and LUA_INCLUDE. -# If the search is unsuccessful, then some common directories are tried. -# If the headers are then found, then LUA_INCLUDE is set accordingly. -# -# The paths automatically searched are: -# -# * /usr/include/luaX.Y -# * /usr/include/lua/X.Y -# * /usr/include/luaXY -# * /usr/local/include/luaX.Y -# * /usr/local/include/lua-X.Y -# * /usr/local/include/lua/X.Y -# * /usr/local/include/luaXY -# -# (Where X.Y is the Lua version number, e.g. 5.1.) -# -# The Lua version number found in the headers is always checked to match -# the Lua interpreter's version number. Lua headers with mismatched -# version numbers are not accepted. -# -# If headers are found, then ACTION-IF-FOUND is performed, otherwise -# ACTION-IF-NOT-FOUND is performed. If ACTION-IF-NOT-FOUND is blank, then -# it will default to printing an error. To prevent the default behavior, -# set the action to ':'. -# -# AX_LUA_LIBS: Search for Lua libraries. Requires that AX_PROG_LUA be -# expanded before this macro. Adds precious variable LUA_LIB, which may -# contain Lua specific linker flags, e.g. -llua5.1. If LUA_LIB is blank, -# then this macro will attempt to find suitable flags. -# -# LUA_LIB can be used by Automake to link Lua modules or executables with -# embedded interpreters. The *_LIBADD and *_LDADD variables should be used -# for this purpose, e.g. mymod_LIBADD = $(LUA_LIB). -# -# This macro searches for the Lua library. More technically, it searches -# for a library containing the function lua_load. The search is performed -# with a combination of LIBS, LIBRARY_PATH, and LUA_LIB. -# -# If the search determines that some linker flags are missing, then those -# flags will be added to LUA_LIB. -# -# If libraries are found, then ACTION-IF-FOUND is performed, otherwise -# ACTION-IF-NOT-FOUND is performed. If ACTION-IF-NOT-FOUND is blank, then -# it will default to printing an error. To prevent the default behavior, -# set the action to ':'. -# -# AX_LUA_READLINE: Search for readline headers and libraries. Requires the -# AX_LIB_READLINE macro, which is provided by ax_lib_readline.m4 from the -# Autoconf Archive. -# -# If a readline compatible library is found, then ACTION-IF-FOUND is -# performed, otherwise ACTION-IF-NOT-FOUND is performed. -# -# LICENSE -# -# Copyright (c) 2014 Reuben Thomas <rrt@sc3d.org> -# Copyright (c) 2013 Tim Perkins <tprk77@gmail.com> -# -# This program is free software: you can redistribute it and/or modify it -# under the terms of the GNU General Public License as published by the -# Free Software Foundation, either version 3 of the License, or (at your -# option) any later version. -# -# This program is distributed in the hope that it will be useful, but -# WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General -# Public License for more details. -# -# You should have received a copy of the GNU General Public License along -# with this program. If not, see <http://www.gnu.org/licenses/>. -# -# As a special exception, the respective Autoconf Macro's copyright owner -# gives unlimited permission to copy, distribute and modify the configure -# scripts that are the output of Autoconf when processing the Macro. You -# need not follow the terms of the GNU General Public License when using -# or distributing such scripts, even though portions of the text of the -# Macro appear in them. The GNU General Public License (GPL) does govern -# all other use of the material that constitutes the Autoconf Macro. -# -# This special exception to the GPL applies to versions of the Autoconf -# Macro released by the Autoconf Archive. When you make and distribute a -# modified version of the Autoconf Macro, you may extend this special -# exception to the GPL to apply to your modified version as well. - -#serial 23 - -dnl ========================================================================= -dnl AX_PROG_LUA([MINIMUM-VERSION], [TOO-BIG-VERSION], -dnl [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND]) -dnl ========================================================================= -AC_DEFUN([AX_PROG_LUA], -[ - dnl Make LUA a precious variable. - AC_ARG_VAR([LUA], [The Lua interpreter, e.g. /usr/bin/lua5.1]) - - dnl Find a Lua interpreter. - m4_define_default([_AX_LUA_INTERPRETER_LIST], - [lua lua5.2 lua52 lua5.1 lua51 lua50]) - - m4_if([$1], [], - [ dnl No version check is needed. Find any Lua interpreter. - AS_IF([test "x$LUA" = 'x'], - [AC_PATH_PROGS([LUA], [_AX_LUA_INTERPRETER_LIST], [:])]) - ax_display_LUA='lua' - - dnl At least check if this is a Lua interpreter. - AC_MSG_CHECKING([if $LUA is a Lua interpreter]) - _AX_LUA_CHK_IS_INTRP([$LUA], - [AC_MSG_RESULT([yes])], - [ AC_MSG_RESULT([no]) - AC_MSG_ERROR([not a Lua interpreter]) - ]) - ], - [ dnl A version check is needed. - AS_IF([test "x$LUA" != 'x'], - [ dnl Check if this is a Lua interpreter. - AC_MSG_CHECKING([if $LUA is a Lua interpreter]) - _AX_LUA_CHK_IS_INTRP([$LUA], - [AC_MSG_RESULT([yes])], - [ AC_MSG_RESULT([no]) - AC_MSG_ERROR([not a Lua interpreter]) - ]) - dnl Check the version. - m4_if([$2], [], - [_ax_check_text="whether $LUA version >= $1"], - [_ax_check_text="whether $LUA version >= $1, < $2"]) - AC_MSG_CHECKING([$_ax_check_text]) - _AX_LUA_CHK_VER([$LUA], [$1], [$2], - [AC_MSG_RESULT([yes])], - [ AC_MSG_RESULT([no]) - AC_MSG_ERROR([version is out of range for specified LUA])]) - ax_display_LUA=$LUA - ], - [ dnl Try each interpreter until we find one that satisfies VERSION. - m4_if([$2], [], - [_ax_check_text="for a Lua interpreter with version >= $1"], - [_ax_check_text="for a Lua interpreter with version >= $1, < $2"]) - AC_CACHE_CHECK([$_ax_check_text], - [ax_cv_pathless_LUA], - [ for ax_cv_pathless_LUA in _AX_LUA_INTERPRETER_LIST none; do - test "x$ax_cv_pathless_LUA" = 'xnone' && break - _AX_LUA_CHK_IS_INTRP([$ax_cv_pathless_LUA], [], [continue]) - _AX_LUA_CHK_VER([$ax_cv_pathless_LUA], [$1], [$2], [break]) - done - ]) - dnl Set $LUA to the absolute path of $ax_cv_pathless_LUA. - AS_IF([test "x$ax_cv_pathless_LUA" = 'xnone'], - [LUA=':'], - [AC_PATH_PROG([LUA], [$ax_cv_pathless_LUA])]) - ax_display_LUA=$ax_cv_pathless_LUA - ]) - ]) - - AS_IF([test "x$LUA" = 'x:'], - [ dnl Run any user-specified action, or abort. - m4_default([$4], [AC_MSG_ERROR([cannot find suitable Lua interpreter])]) - ], - [ dnl Query Lua for its version number. - AC_CACHE_CHECK([for $ax_display_LUA version], [ax_cv_lua_version], - [ ax_cv_lua_version=`$LUA -e 'print(_VERSION:match "(%d+%.%d+)")'` ]) - AS_IF([test "x$ax_cv_lua_version" = 'x'], - [AC_MSG_ERROR([invalid Lua version number])]) - AC_SUBST([LUA_VERSION], [$ax_cv_lua_version]) - AC_SUBST([LUA_SHORT_VERSION], [`echo "$LUA_VERSION" | sed 's|\.||'`]) - - dnl The following check is not supported: - dnl At times (like when building shared libraries) you may want to know - dnl which OS platform Lua thinks this is. - AC_CACHE_CHECK([for $ax_display_LUA platform], [ax_cv_lua_platform], - [ax_cv_lua_platform=`$LUA -e "print('unknown')"`]) - AC_SUBST([LUA_PLATFORM], [$ax_cv_lua_platform]) - - dnl Use the values of $prefix and $exec_prefix for the corresponding - dnl values of LUA_PREFIX and LUA_EXEC_PREFIX. These are made distinct - dnl variables so they can be overridden if need be. However, the general - dnl consensus is that you shouldn't need this ability. - AC_SUBST([LUA_PREFIX], ['${prefix}']) - AC_SUBST([LUA_EXEC_PREFIX], ['${exec_prefix}']) - - dnl Lua provides no way to query the script directory, and instead - dnl provides LUA_PATH. However, we should be able to make a safe educated - dnl guess. If the built-in search path contains a directory which is - dnl prefixed by $prefix, then we can store scripts there. The first - dnl matching path will be used. - AC_CACHE_CHECK([for $ax_display_LUA script directory], - [ax_cv_lua_luadir], - [ AS_IF([test "x$prefix" = 'xNONE'], - [ax_lua_prefix=$ac_default_prefix], - [ax_lua_prefix=$prefix]) - - dnl Initialize to the default path. - ax_cv_lua_luadir="$LUA_PREFIX/share/lua/$LUA_VERSION" - - dnl Try to find a path with the prefix. - _AX_LUA_FND_PRFX_PTH([$LUA], [$ax_lua_prefix], [package.path]) - AS_IF([test "x$ax_lua_prefixed_path" != 'x'], - [ dnl Fix the prefix. - _ax_strip_prefix=`echo "$ax_lua_prefix" | sed 's|.|.|g'` - ax_cv_lua_luadir=`echo "$ax_lua_prefixed_path" | \ - sed "s,^$_ax_strip_prefix,$LUA_PREFIX,"` - ]) - ]) - AC_SUBST([luadir], [$ax_cv_lua_luadir]) - AC_SUBST([pkgluadir], [\${luadir}/$PACKAGE]) - - dnl Lua provides no way to query the module directory, and instead - dnl provides LUA_PATH. However, we should be able to make a safe educated - dnl guess. If the built-in search path contains a directory which is - dnl prefixed by $exec_prefix, then we can store modules there. The first - dnl matching path will be used. - AC_CACHE_CHECK([for $ax_display_LUA module directory], - [ax_cv_lua_luaexecdir], - [ AS_IF([test "x$exec_prefix" = 'xNONE'], - [ax_lua_exec_prefix=$ax_lua_prefix], - [ax_lua_exec_prefix=$exec_prefix]) - - dnl Initialize to the default path. - ax_cv_lua_luaexecdir="$LUA_EXEC_PREFIX/lib/lua/$LUA_VERSION" - - dnl Try to find a path with the prefix. - _AX_LUA_FND_PRFX_PTH([$LUA], - [$ax_lua_exec_prefix], [package.cpathd]) - AS_IF([test "x$ax_lua_prefixed_path" != 'x'], - [ dnl Fix the prefix. - _ax_strip_prefix=`echo "$ax_lua_exec_prefix" | sed 's|.|.|g'` - ax_cv_lua_luaexecdir=`echo "$ax_lua_prefixed_path" | \ - sed "s,^$_ax_strip_prefix,$LUA_EXEC_PREFIX,"` - ]) - ]) - AC_SUBST([luaexecdir], [$ax_cv_lua_luaexecdir]) - AC_SUBST([pkgluaexecdir], [\${luaexecdir}/$PACKAGE]) - - dnl Run any user specified action. - $3 - ]) -]) - -dnl AX_WITH_LUA is now the same thing as AX_PROG_LUA. -AC_DEFUN([AX_WITH_LUA], -[ - AC_MSG_WARN([[$0 is deprecated, please use AX_PROG_LUA]]) - AX_PROG_LUA -]) - - -dnl ========================================================================= -dnl _AX_LUA_CHK_IS_INTRP(PROG, [ACTION-IF-TRUE], [ACTION-IF-FALSE]) -dnl ========================================================================= -AC_DEFUN([_AX_LUA_CHK_IS_INTRP], -[ - dnl Just print _VERSION because all Lua interpreters have this global. - AS_IF([$1 -e "print('Hello ' .. _VERSION .. '!')" &>/dev/null], - [$2], [$3]) -]) - - -dnl ========================================================================= -dnl _AX_LUA_CHK_VER(PROG, MINIMUM-VERSION, [TOO-BIG-VERSION], -dnl [ACTION-IF-TRUE], [ACTION-IF-FALSE]) -dnl ========================================================================= -AC_DEFUN([_AX_LUA_CHK_VER], -[ - AS_IF([$1 2>/dev/null -e ' - function norm (v) i,j=v:match "(%d+)%.(%d+)" return 100 * i + j end - v=norm (_VERSION) - os.exit ((v >= norm ("$2") and ("$3" == "" or v < norm ("$3"))) and 0 or 1)'], - [$4], [$5]) -]) - - -dnl ========================================================================= -dnl _AX_LUA_FND_PRFX_PTH(PROG, PREFIX, LUA-PATH-VARIABLE) -dnl ========================================================================= -AC_DEFUN([_AX_LUA_FND_PRFX_PTH], -[ - dnl Invokes the Lua interpreter PROG to print the path variable - dnl LUA-PATH-VARIABLE, usually package.path or package.cpath. Paths are - dnl then matched against PREFIX. The first path to begin with PREFIX is set - dnl to ax_lua_prefixed_path. - - ax_lua_prefixed_path='' - _ax_package_paths=`$1 -e 'print($3)' 2>/dev/null | sed 's|;|\n|g'` - dnl Try the paths in order, looking for the prefix. - for _ax_package_path in $_ax_package_paths; do - dnl Copy the path, up to the use of a Lua wildcard. - _ax_path_parts=`echo "$_ax_package_path" | sed 's|/|\n|g'` - _ax_reassembled='' - for _ax_path_part in $_ax_path_parts; do - echo "$_ax_path_part" | grep '\?' >/dev/null && break - _ax_reassembled="$_ax_reassembled/$_ax_path_part" - done - dnl Check the path against the prefix. - _ax_package_path=$_ax_reassembled - if echo "$_ax_package_path" | grep "^$2" >/dev/null; then - dnl Found it. - ax_lua_prefixed_path=$_ax_package_path - break - fi - done -]) - - -dnl ========================================================================= -dnl AX_LUA_HEADERS([ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND]) -dnl ========================================================================= -AC_DEFUN([AX_LUA_HEADERS], -[ - dnl Check for LUA_VERSION. - AC_MSG_CHECKING([if LUA_VERSION is defined]) - AS_IF([test "x$LUA_VERSION" != 'x'], - [AC_MSG_RESULT([yes])], - [ AC_MSG_RESULT([no]) - AC_MSG_ERROR([cannot check Lua headers without knowing LUA_VERSION]) - ]) - - dnl Make LUA_INCLUDE a precious variable. - AC_ARG_VAR([LUA_INCLUDE], [The Lua includes, e.g. -I/usr/include/lua5.1]) - - dnl Some default directories to search. - LUA_SHORT_VERSION=`echo "$LUA_VERSION" | sed 's|\.||'` - m4_define_default([_AX_LUA_INCLUDE_LIST], - [ /usr/include/lua$LUA_VERSION \ - /usr/include/lua/$LUA_VERSION \ - /usr/include/lua$LUA_SHORT_VERSION \ - /usr/local/include/lua$LUA_VERSION \ - /usr/local/include/lua-$LUA_VERSION \ - /usr/local/include/lua/$LUA_VERSION \ - /usr/local/include/lua$LUA_SHORT_VERSION \ - ]) - - dnl Try to find the headers. - _ax_lua_saved_cppflags=$CPPFLAGS - CPPFLAGS="$CPPFLAGS $LUA_INCLUDE" - AC_CHECK_HEADERS([lua.h lualib.h lauxlib.h luaconf.h]) - CPPFLAGS=$_ax_lua_saved_cppflags - - dnl Try some other directories if LUA_INCLUDE was not set. - AS_IF([test "x$LUA_INCLUDE" = 'x' && - test "x$ac_cv_header_lua_h" != 'xyes'], - [ dnl Try some common include paths. - for _ax_include_path in _AX_LUA_INCLUDE_LIST; do - test ! -d "$_ax_include_path" && continue - - AC_MSG_CHECKING([for Lua headers in]) - AC_MSG_RESULT([$_ax_include_path]) - - AS_UNSET([ac_cv_header_lua_h]) - AS_UNSET([ac_cv_header_lualib_h]) - AS_UNSET([ac_cv_header_lauxlib_h]) - AS_UNSET([ac_cv_header_luaconf_h]) - - _ax_lua_saved_cppflags=$CPPFLAGS - CPPFLAGS="$CPPFLAGS -I$_ax_include_path" - AC_CHECK_HEADERS([lua.h lualib.h lauxlib.h luaconf.h]) - CPPFLAGS=$_ax_lua_saved_cppflags - - AS_IF([test "x$ac_cv_header_lua_h" = 'xyes'], - [ LUA_INCLUDE="-I$_ax_include_path" - break - ]) - done - ]) - - AS_IF([test "x$ac_cv_header_lua_h" = 'xyes' && test "x$cross_compiling" != 'xyes'], - [ dnl Make a program to print LUA_VERSION defined in the header. - dnl TODO This probably shouldn't be a runtime test. - - AC_CACHE_CHECK([for Lua header version], - [ax_cv_lua_header_version], - [ _ax_lua_saved_cppflags=$CPPFLAGS - CPPFLAGS="$CPPFLAGS $LUA_INCLUDE" - AC_RUN_IFELSE( - [ AC_LANG_SOURCE([[ -#include <lua.h> -#include <stdlib.h> -#include <stdio.h> -int main(int argc, char ** argv) -{ - if(argc > 1) printf("%s", LUA_VERSION); - exit(EXIT_SUCCESS); -} -]]) - ], - [ ax_cv_lua_header_version=`./conftest$EXEEXT p | \ - sed "s|^Lua \(.*\)|\1|" | \ - grep -o "^@<:@0-9@:>@\+\\.@<:@0-9@:>@\+"` - ], - [ax_cv_lua_header_version='unknown']) - CPPFLAGS=$_ax_lua_saved_cppflags - ]) - - dnl Compare this to the previously found LUA_VERSION. - AC_MSG_CHECKING([if Lua header version matches $LUA_VERSION]) - AS_IF([test "x$ax_cv_lua_header_version" = "x$LUA_VERSION"], - [ AC_MSG_RESULT([yes]) - ax_header_version_match='yes' - ], - [ AC_MSG_RESULT([no]) - ax_header_version_match='no' - ]) - ], - [ - ax_header_version_match='yes' - ]) - - dnl Was LUA_INCLUDE specified? - AS_IF([test "x$ax_header_version_match" != 'xyes' && - test "x$LUA_INCLUDE" != 'x'], - [AC_MSG_ERROR([cannot find headers for specified LUA_INCLUDE])]) - - dnl Test the final result and run user code. - AS_IF([test "x$ax_header_version_match" = 'xyes'], [$1], - [m4_default([$2], [AC_MSG_ERROR([cannot find Lua includes])])]) -]) - -dnl AX_LUA_HEADERS_VERSION no longer exists, use AX_LUA_HEADERS. -AC_DEFUN([AX_LUA_HEADERS_VERSION], -[ - AC_MSG_WARN([[$0 is deprecated, please use AX_LUA_HEADERS]]) -]) - - -dnl ========================================================================= -dnl AX_LUA_LIBS([ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND]) -dnl ========================================================================= -AC_DEFUN([AX_LUA_LIBS], -[ - dnl TODO Should this macro also check various -L flags? - - dnl Check for LUA_VERSION. - AC_MSG_CHECKING([if LUA_VERSION is defined]) - AS_IF([test "x$LUA_VERSION" != 'x'], - [AC_MSG_RESULT([yes])], - [ AC_MSG_RESULT([no]) - AC_MSG_ERROR([cannot check Lua libs without knowing LUA_VERSION]) - ]) - - dnl Make LUA_LIB a precious variable. - AC_ARG_VAR([LUA_LIB], [The Lua library, e.g. -llua5.1]) - - AS_IF([test "x$LUA_LIB" != 'x'], - [ dnl Check that LUA_LIBS works. - _ax_lua_saved_libs=$LIBS - LIBS="$LIBS $LUA_LIB" - AC_SEARCH_LIBS([lua_load], [], - [_ax_found_lua_libs='yes'], - [_ax_found_lua_libs='no']) - LIBS=$_ax_lua_saved_libs - - dnl Check the result. - AS_IF([test "x$_ax_found_lua_libs" != 'xyes'], - [AC_MSG_ERROR([cannot find libs for specified LUA_LIB])]) - ], - [ dnl First search for extra libs. - _ax_lua_extra_libs='' - - _ax_lua_saved_libs=$LIBS - LIBS="$LIBS $LUA_LIB" - AC_SEARCH_LIBS([exp], [m]) - AC_SEARCH_LIBS([dlopen], [dl]) - LIBS=$_ax_lua_saved_libs - - AS_IF([test "x$ac_cv_search_exp" != 'xno' && - test "x$ac_cv_search_exp" != 'xnone required'], - [_ax_lua_extra_libs="$_ax_lua_extra_libs $ac_cv_search_exp"]) - - AS_IF([test "x$ac_cv_search_dlopen" != 'xno' && - test "x$ac_cv_search_dlopen" != 'xnone required'], - [_ax_lua_extra_libs="$_ax_lua_extra_libs $ac_cv_search_dlopen"]) - - dnl Try to find the Lua libs. - _ax_lua_saved_libs=$LIBS - LIBS="$LIBS $LUA_LIB" - AC_SEARCH_LIBS([lua_load], - [ lua$LUA_VERSION \ - lua$LUA_SHORT_VERSION \ - lua-$LUA_VERSION \ - lua-$LUA_SHORT_VERSION \ - lua], - [_ax_found_lua_libs='yes'], - [_ax_found_lua_libs='no'], - [$_ax_lua_extra_libs]) - LIBS=$_ax_lua_saved_libs - - AS_IF([test "x$ac_cv_search_lua_load" != 'xno' && - test "x$ac_cv_search_lua_load" != 'xnone required'], - [LUA_LIB="$ac_cv_search_lua_load $_ax_lua_extra_libs"]) - ]) - - dnl Test the result and run user code. - AS_IF([test "x$_ax_found_lua_libs" = 'xyes'], [$1], - [m4_default([$2], [AC_MSG_ERROR([cannot find Lua libs])])]) -]) - - -dnl ========================================================================= -dnl AX_LUA_READLINE([ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND]) -dnl ========================================================================= -AC_DEFUN([AX_LUA_READLINE], -[ - AX_LIB_READLINE - AS_IF([test "x$ac_cv_header_readline_readline_h" != 'x' && - test "x$ac_cv_header_readline_history_h" != 'x'], - [ LUA_LIBS_CFLAGS="-DLUA_USE_READLINE $LUA_LIBS_CFLAGS" - $1 - ], - [$2]) -]) diff --git a/contrib/libucl/src/Makefile.am b/contrib/libucl/src/Makefile.am index 417d34e161ca..c3f0c9fffb60 100644 --- a/contrib/libucl/src/Makefile.am +++ b/contrib/libucl/src/Makefile.am @@ -1,6 +1,7 @@ libucl_common_cflags= -I$(top_srcdir)/src \ -I$(top_srcdir)/include \ -I$(top_srcdir)/uthash \ + -I$(top_srcdir)/klib \ -Wall -W -Wno-unused-parameter -Wno-pointer-sign lib_LTLIBRARIES= libucl.la libucl_la_SOURCES= ucl_emitter.c \ diff --git a/contrib/libucl/src/ucl_emitter.c b/contrib/libucl/src/ucl_emitter.c index 8134d09c1a65..9ddf3584a25b 100644 --- a/contrib/libucl/src/ucl_emitter.c +++ b/contrib/libucl/src/ucl_emitter.c @@ -250,6 +250,7 @@ ucl_emitter_common_start_array (struct ucl_emitter_context *ctx, const ucl_object_t *obj, bool print_key, bool compact) { const ucl_object_t *cur; + ucl_object_iter_t iter = NULL; const struct ucl_emitter_functions *func = ctx->func; bool first = true; @@ -266,18 +267,22 @@ ucl_emitter_common_start_array (struct ucl_emitter_context *ctx, if (obj->type == UCL_ARRAY) { /* explicit array */ - cur = obj->value.av; + while ((cur = ucl_iterate_object (obj, &iter, true)) != NULL) { + ucl_emitter_common_elt (ctx, cur, first, false, compact); + first = false; + } } else { /* implicit array */ cur = obj; + while (cur) { + ucl_emitter_common_elt (ctx, cur, first, false, compact); + first = false; + cur = cur->next; + } } - while (cur) { - ucl_emitter_common_elt (ctx, cur, first, false, compact); - first = false; - cur = cur->next; - } + } /** diff --git a/contrib/libucl/src/ucl_emitter_utils.c b/contrib/libucl/src/ucl_emitter_utils.c index da412097ffbc..91cad78bcbf6 100644 --- a/contrib/libucl/src/ucl_emitter_utils.c +++ b/contrib/libucl/src/ucl_emitter_utils.c @@ -289,6 +289,7 @@ ucl_fd_append_character (unsigned char c, size_t len, void *ud) else { memset (buf, c, len); if (write (fd, buf, len) == -1) { + free(buf); return -1; } free (buf); diff --git a/contrib/libucl/src/ucl_hash.c b/contrib/libucl/src/ucl_hash.c index ea55491ed504..275e84d478aa 100644 --- a/contrib/libucl/src/ucl_hash.c +++ b/contrib/libucl/src/ucl_hash.c @@ -23,119 +23,331 @@ #include "ucl_internal.h" #include "ucl_hash.h" -#include "utlist.h" +#include "khash.h" +#include "kvec.h" + +struct ucl_hash_elt { + const ucl_object_t *obj; + size_t ar_idx; +}; + +struct ucl_hash_struct { + void *hash; + kvec_t(const ucl_object_t *) ar; + bool caseless; +}; + +static inline uint32_t +ucl_hash_func (const ucl_object_t *o) +{ + return XXH32 (o->key, o->keylen, 0xdeadbeef); +} + +static inline int +ucl_hash_equal (const ucl_object_t *k1, const ucl_object_t *k2) +{ + if (k1->keylen == k2->keylen) { + return strncmp (k1->key, k2->key, k1->keylen) == 0; + } + + return 0; +} + +KHASH_INIT (ucl_hash_node, const ucl_object_t *, struct ucl_hash_elt, 1, + ucl_hash_func, ucl_hash_equal) + +static inline uint32_t +ucl_hash_caseless_func (const ucl_object_t *o) +{ + void *xxh = XXH32_init (0xdeadbeef); + char hash_buf[64], *c; + const char *p; + ssize_t remain = o->keylen; + + p = o->key; + c = &hash_buf[0]; + + while (remain > 0) { + *c++ = tolower (*p++); + + if (c - &hash_buf[0] == sizeof (hash_buf)) { + XXH32_update (xxh, hash_buf, sizeof (hash_buf)); + c = &hash_buf[0]; + } + remain --; + } + + if (c - &hash_buf[0] != 0) { + XXH32_update (xxh, hash_buf, c - &hash_buf[0]); + } + + return XXH32_digest (xxh); +} + +static inline int +ucl_hash_caseless_equal (const ucl_object_t *k1, const ucl_object_t *k2) +{ + if (k1->keylen == k2->keylen) { + return strncasecmp (k1->key, k2->key, k1->keylen) == 0; + } + + return 0; +} + +KHASH_INIT (ucl_hash_caseless_node, const ucl_object_t *, struct ucl_hash_elt, 1, + ucl_hash_caseless_func, ucl_hash_caseless_equal) ucl_hash_t* -ucl_hash_create (void) +ucl_hash_create (bool ignore_case) { ucl_hash_t *new; new = UCL_ALLOC (sizeof (ucl_hash_t)); if (new != NULL) { - new->buckets = NULL; + kv_init (new->ar); + + new->caseless = ignore_case; + if (ignore_case) { + khash_t(ucl_hash_caseless_node) *h = kh_init (ucl_hash_caseless_node); + new->hash = (void *)h; + } + else { + khash_t(ucl_hash_node) *h = kh_init (ucl_hash_node); + new->hash = (void *)h; + } } return new; } void ucl_hash_destroy (ucl_hash_t* hashlin, ucl_hash_free_func *func) { - ucl_hash_node_t *elt, *tmp; - const ucl_object_t *cur, *otmp; - - HASH_ITER (hh, hashlin->buckets, elt, tmp) { - HASH_DELETE (hh, hashlin->buckets, elt); - if (func) { - DL_FOREACH_SAFE (elt->data, cur, otmp) { - /* Need to deconst here */ - func (__DECONST (ucl_object_t *, cur)); + const ucl_object_t *cur, *tmp; + + if (hashlin == NULL) { + return; + } + + if (func != NULL) { + /* Iterate over the hash first */ + khash_t(ucl_hash_node) *h = (khash_t(ucl_hash_node) *) + hashlin->hash; + khiter_t k; + + for (k = kh_begin (h); k != kh_end (h); ++k) { + if (kh_exist (h, k)) { + cur = (kh_value (h, k)).obj; + while (cur != NULL) { + tmp = cur->next; + func (__DECONST (ucl_object_t *, cur)); + cur = tmp; + } } } - UCL_FREE (sizeof (ucl_hash_node_t), elt); } - UCL_FREE (sizeof (ucl_hash_t), hashlin); + + if (hashlin->caseless) { + khash_t(ucl_hash_caseless_node) *h = (khash_t(ucl_hash_caseless_node) *) + hashlin->hash; + kh_destroy (ucl_hash_caseless_node, h); + } + else { + khash_t(ucl_hash_node) *h = (khash_t(ucl_hash_node) *) + hashlin->hash; + kh_destroy (ucl_hash_node, h); + } + + kv_destroy (hashlin->ar); + UCL_FREE (sizeof (*hashlin), hashlin); } void ucl_hash_insert (ucl_hash_t* hashlin, const ucl_object_t *obj, const char *key, unsigned keylen) { - ucl_hash_node_t *node; + khiter_t k; + int ret; + struct ucl_hash_elt *elt; + + if (hashlin == NULL) { + return; + } - node = UCL_ALLOC (sizeof (ucl_hash_node_t)); - node->data = obj; - HASH_ADD_KEYPTR (hh, hashlin->buckets, key, keylen, node); + if (hashlin->caseless) { + khash_t(ucl_hash_caseless_node) *h = (khash_t(ucl_hash_caseless_node) *) + hashlin->hash; + k = kh_put (ucl_hash_caseless_node, h, obj, &ret); + if (ret > 0) { + elt = &kh_value (h, k); + kv_push (const ucl_object_t *, hashlin->ar, obj); + elt->obj = obj; + elt->ar_idx = kv_size (hashlin->ar) - 1; + } + } + else { + khash_t(ucl_hash_node) *h = (khash_t(ucl_hash_node) *) + hashlin->hash; + k = kh_put (ucl_hash_node, h, obj, &ret); + if (ret > 0) { + elt = &kh_value (h, k); + kv_push (const ucl_object_t *, hashlin->ar, obj); + elt->obj = obj; + elt->ar_idx = kv_size (hashlin->ar) - 1; + } + } } void ucl_hash_replace (ucl_hash_t* hashlin, const ucl_object_t *old, const ucl_object_t *new) { - ucl_hash_node_t *node; + khiter_t k; + int ret; + struct ucl_hash_elt elt, *pelt; - HASH_FIND (hh, hashlin->buckets, old->key, old->keylen, node); - if (node != NULL) { - /* Direct replacement */ - node->data = new; - node->hh.key = new->key; - node->hh.keylen = new->keylen; + if (hashlin == NULL) { + return; + } + + if (hashlin->caseless) { + khash_t(ucl_hash_caseless_node) *h = (khash_t(ucl_hash_caseless_node) *) + hashlin->hash; + k = kh_put (ucl_hash_caseless_node, h, old, &ret); + if (ret == 0) { + elt = kh_value (h, k); + kh_del (ucl_hash_caseless_node, h, k); + k = kh_put (ucl_hash_caseless_node, h, new, &ret); + pelt = &kh_value (h, k); + pelt->obj = new; + pelt->ar_idx = elt.ar_idx; + kv_A (hashlin->ar, elt.ar_idx) = new; + } + } + else { + khash_t(ucl_hash_node) *h = (khash_t(ucl_hash_node) *) + hashlin->hash; + k = kh_put (ucl_hash_node, h, old, &ret); + if (ret == 0) { + elt = kh_value (h, k); + kh_del (ucl_hash_node, h, k); + k = kh_put (ucl_hash_node, h, new, &ret); + pelt = &kh_value (h, k); + pelt->obj = new; + pelt->ar_idx = elt.ar_idx; + kv_A (hashlin->ar, elt.ar_idx) = new; + } } } +struct ucl_hash_real_iter { + const ucl_object_t **cur; + const ucl_object_t **end; +}; + const void* ucl_hash_iterate (ucl_hash_t *hashlin, ucl_hash_iter_t *iter) { - ucl_hash_node_t *elt = *iter; + struct ucl_hash_real_iter *it = (struct ucl_hash_real_iter *)(*iter); + const ucl_object_t *ret = NULL; - if (elt == NULL) { - if (hashlin == NULL || hashlin->buckets == NULL) { - return NULL; - } - elt = hashlin->buckets; - if (elt == NULL) { - return NULL; - } + if (hashlin == NULL) { + return NULL; + } + + if (it == NULL) { + it = UCL_ALLOC (sizeof (*it)); + it->cur = &hashlin->ar.a[0]; + it->end = it->cur + hashlin->ar.n; + } + + if (it->cur < it->end) { + ret = *it->cur++; } - else if (elt == hashlin->buckets) { + else { + UCL_FREE (sizeof (*it), it); + *iter = NULL; return NULL; } - *iter = elt->hh.next ? elt->hh.next : hashlin->buckets; - return elt->data; + *iter = it; + + return ret; } bool -ucl_hash_iter_has_next (ucl_hash_iter_t iter) +ucl_hash_iter_has_next (ucl_hash_t *hashlin, ucl_hash_iter_t iter) { - ucl_hash_node_t *elt = iter; + struct ucl_hash_real_iter *it = (struct ucl_hash_real_iter *)(iter); - return (elt == NULL || elt->hh.prev != NULL); + return it->cur < it->end - 1; } const ucl_object_t* ucl_hash_search (ucl_hash_t* hashlin, const char *key, unsigned keylen) { - ucl_hash_node_t *found; + khiter_t k; + const ucl_object_t *ret = NULL; + ucl_object_t search; + struct ucl_hash_elt *elt; + + search.key = key; + search.keylen = keylen; if (hashlin == NULL) { return NULL; } - HASH_FIND (hh, hashlin->buckets, key, keylen, found); - if (found) { - return found->data; + if (hashlin->caseless) { + khash_t(ucl_hash_caseless_node) *h = (khash_t(ucl_hash_caseless_node) *) + hashlin->hash; + + k = kh_get (ucl_hash_caseless_node, h, &search); + if (k != kh_end (h)) { + elt = &kh_value (h, k); + ret = elt->obj; + } } - return NULL; + else { + khash_t(ucl_hash_node) *h = (khash_t(ucl_hash_node) *) + hashlin->hash; + k = kh_get (ucl_hash_node, h, &search); + if (k != kh_end (h)) { + elt = &kh_value (h, k); + ret = elt->obj; + } + } + + return ret; } void ucl_hash_delete (ucl_hash_t* hashlin, const ucl_object_t *obj) { - ucl_hash_node_t *found; + khiter_t k; + struct ucl_hash_elt *elt; - HASH_FIND (hh, hashlin->buckets, obj->key, obj->keylen, found); + if (hashlin == NULL) { + return; + } - if (found) { - HASH_DELETE (hh, hashlin->buckets, found); - UCL_FREE (sizeof (ucl_hash_node_t), found); + if (hashlin->caseless) { + khash_t(ucl_hash_caseless_node) *h = (khash_t(ucl_hash_caseless_node) *) + hashlin->hash; + + k = kh_get (ucl_hash_caseless_node, h, obj); + if (k != kh_end (h)) { + elt = &kh_value (h, k); + kv_A (hashlin->ar, elt->ar_idx) = NULL; + kh_del (ucl_hash_caseless_node, h, k); + } + } + else { + khash_t(ucl_hash_node) *h = (khash_t(ucl_hash_node) *) + hashlin->hash; + k = kh_get (ucl_hash_node, h, obj); + if (k != kh_end (h)) { + elt = &kh_value (h, k); + kv_A (hashlin->ar, elt->ar_idx) = NULL; + kh_del (ucl_hash_node, h, k); + } } } diff --git a/contrib/libucl/src/ucl_hash.h b/contrib/libucl/src/ucl_hash.h index ddbfdba19ce8..64c83eac8bc1 100644 --- a/contrib/libucl/src/ucl_hash.h +++ b/contrib/libucl/src/ucl_hash.h @@ -25,15 +25,11 @@ #define __UCL_HASH_H #include "ucl.h" -#include "uthash.h" /******************************************************************************/ -typedef struct ucl_hash_node_s -{ - const ucl_object_t *data; - UT_hash_handle hh; -} ucl_hash_node_t; +struct ucl_hash_node_s; +typedef struct ucl_hash_node_s ucl_hash_node_t; typedef int ucl_hash_cmp_func (const void* void_a, const void* void_b); typedef void ucl_hash_free_func (void *ptr); @@ -43,16 +39,14 @@ typedef void* ucl_hash_iter_t; /** * Linear chained hashtable. */ -typedef struct ucl_hash_struct -{ - ucl_hash_node_t *buckets; /**< array of hash buckets. One list for each hash modulus. */ -} ucl_hash_t; +struct ucl_hash_struct; +typedef struct ucl_hash_struct ucl_hash_t; /** * Initializes the hashtable. */ -ucl_hash_t* ucl_hash_create (void); +ucl_hash_t* ucl_hash_create (bool ignore_case); /** * Deinitializes the hashtable. @@ -94,6 +88,6 @@ const void* ucl_hash_iterate (ucl_hash_t *hashlin, ucl_hash_iter_t *iter); /** * Check whether an iterator has next element */ -bool ucl_hash_iter_has_next (ucl_hash_iter_t iter); +bool ucl_hash_iter_has_next (ucl_hash_t *hashlin, ucl_hash_iter_t iter); #endif diff --git a/contrib/libucl/src/ucl_internal.h b/contrib/libucl/src/ucl_internal.h index 2f75872b7bb8..bdbe691d092b 100644 --- a/contrib/libucl/src/ucl_internal.h +++ b/contrib/libucl/src/ucl_internal.h @@ -339,14 +339,17 @@ ucl_hash_search_obj (ucl_hash_t* hashlin, ucl_object_t *obj) return (const ucl_object_t *)ucl_hash_search (hashlin, obj->key, obj->keylen); } -static inline ucl_hash_t * -ucl_hash_insert_object (ucl_hash_t *hashlin, const ucl_object_t *obj) UCL_WARN_UNUSED_RESULT; +static inline ucl_hash_t * ucl_hash_insert_object (ucl_hash_t *hashlin, + const ucl_object_t *obj, + bool ignore_case) UCL_WARN_UNUSED_RESULT; static inline ucl_hash_t * -ucl_hash_insert_object (ucl_hash_t *hashlin, const ucl_object_t *obj) +ucl_hash_insert_object (ucl_hash_t *hashlin, + const ucl_object_t *obj, + bool ignore_case) { if (hashlin == NULL) { - hashlin = ucl_hash_create (); + hashlin = ucl_hash_create (ignore_case); } ucl_hash_insert (hashlin, obj, obj->key, obj->keylen); diff --git a/contrib/libucl/src/ucl_parser.c b/contrib/libucl/src/ucl_parser.c index 0d118d84b75a..75acba8ecbd3 100644 --- a/contrib/libucl/src/ucl_parser.c +++ b/contrib/libucl/src/ucl_parser.c @@ -570,7 +570,7 @@ ucl_add_parser_stack (ucl_object_t *obj, struct ucl_parser *parser, bool is_arra else { obj->type = UCL_OBJECT; } - obj->value.ov = ucl_hash_create (); + obj->value.ov = ucl_hash_create (parser->flags & UCL_PARSER_KEY_LOWERCASE); parser->state = UCL_STATE_KEY; } else { @@ -975,7 +975,7 @@ ucl_parser_append_elt (struct ucl_parser *parser, ucl_hash_t *cont, else { if ((top->flags & UCL_OBJECT_MULTIVALUE) != 0) { /* Just add to the explicit array */ - DL_APPEND (top->value.av, elt); + ucl_array_append (top, elt); } else { /* Convert to an array */ @@ -984,8 +984,8 @@ ucl_parser_append_elt (struct ucl_parser *parser, ucl_hash_t *cont, nobj->key = top->key; nobj->keylen = top->keylen; nobj->flags |= UCL_OBJECT_MULTIVALUE; - DL_APPEND (nobj->value.av, top); - DL_APPEND (nobj->value.av, elt); + ucl_array_append (nobj, top); + ucl_array_append (nobj, elt); ucl_hash_insert (cont, nobj, nobj->key, nobj->keylen); } } @@ -1016,6 +1016,7 @@ ucl_parse_key (struct ucl_parser *parser, struct ucl_chunk *chunk, bool *next_ke ucl_chunk_skipc (chunk, p); parser->prev_state = parser->state; parser->state = UCL_STATE_MACRO_NAME; + *end_of_object = false; return true; } while (p < chunk->end) { @@ -1195,7 +1196,8 @@ ucl_parse_key (struct ucl_parser *parser, struct ucl_chunk *chunk, bool *next_ke nobj->keylen = keylen; tobj = __DECONST (ucl_object_t *, ucl_hash_search_obj (container, nobj)); if (tobj == NULL) { - container = ucl_hash_insert_object (container, nobj); + container = ucl_hash_insert_object (container, nobj, + parser->flags & UCL_PARSER_KEY_LOWERCASE); nobj->prev = nobj; nobj->next = NULL; parser->stack->obj->len ++; @@ -1363,14 +1365,16 @@ ucl_get_value_object (struct ucl_parser *parser) { ucl_object_t *t, *obj = NULL; + if (parser == NULL || parser->stack == NULL || parser->stack->obj == NULL) { + return NULL; + } + if (parser->stack->obj->type == UCL_ARRAY) { /* Object must be allocated */ obj = ucl_object_new_full (UCL_NULL, parser->chunks->priority); - t = parser->stack->obj->value.av; - DL_APPEND (t, obj); + t = parser->stack->obj; + ucl_array_append (t, obj); parser->cur_obj = obj; - parser->stack->obj->value.av = t; - parser->stack->obj->len ++; } else { /* Object has been already allocated */ diff --git a/contrib/libucl/src/ucl_schema.c b/contrib/libucl/src/ucl_schema.c index faffe8613ce7..834b62accb5f 100644 --- a/contrib/libucl/src/ucl_schema.c +++ b/contrib/libucl/src/ucl_schema.c @@ -525,15 +525,16 @@ ucl_schema_validate_array (const ucl_object_t *schema, ucl_object_iter_t iter = NULL, piter = NULL; bool ret = true, allow_additional = true, need_unique = false; int64_t minmax; + unsigned int idx = 0; while (ret && (elt = ucl_iterate_object (schema, &iter, true)) != NULL) { if (strcmp (ucl_object_key (elt), "items") == 0) { if (elt->type == UCL_ARRAY) { - found = obj->value.av; + found = ucl_array_head (obj); while (ret && (it = ucl_iterate_object (elt, &piter, true)) != NULL) { if (found) { ret = ucl_schema_validate (it, found, false, err, root); - found = found->next; + found = ucl_array_find_index (obj, ++idx); } } if (found != NULL) { @@ -608,14 +609,14 @@ ucl_schema_validate_array (const ucl_object_t *schema, ret = false; } else if (additional_schema != NULL) { - elt = first_unvalidated; + elt = ucl_array_find_index (obj, idx); while (elt) { if (!ucl_schema_validate (additional_schema, elt, false, err, root)) { ret = false; break; } - elt = elt->next; + elt = ucl_array_find_index (obj, idx ++); } } } @@ -741,7 +742,7 @@ ucl_schema_resolve_ref_component (const ucl_object_t *cur, "reference %s is invalid, invalid item number", refc); return NULL; } - res = cur->value.av; + res = ucl_array_head (cur); i = 0; while (res != NULL) { if (i == num) { diff --git a/contrib/libucl/src/ucl_util.c b/contrib/libucl/src/ucl_util.c index 41702e941f5b..41e012bf15bb 100644 --- a/contrib/libucl/src/ucl_util.c +++ b/contrib/libucl/src/ucl_util.c @@ -24,13 +24,21 @@ #include "ucl.h" #include "ucl_internal.h" #include "ucl_chartable.h" +#include "kvec.h" +#ifndef _WIN32 #include <glob.h> +#endif #ifdef HAVE_LIBGEN_H #include <libgen.h> /* For dirname */ #endif +typedef kvec_t(ucl_object_t *) ucl_array_t; + +#define UCL_ARRAY_GET(ar, obj) ucl_array_t *ar = \ + (ucl_array_t *)((obj) != NULL ? (obj)->value.av : NULL) + #ifdef HAVE_OPENSSL #include <openssl/err.h> #include <openssl/sha.h> @@ -68,6 +76,11 @@ #define MAP_FAILED ((void *) -1) #endif +#ifdef _WIN32 +#include <limits.h> +#define NBBY CHAR_BIT +#endif + static void *ucl_mmap(char *addr, size_t length, int prot, int access, int fd, off_t offset) { void *map = NULL; @@ -195,15 +208,27 @@ ucl_object_dtor_unref (ucl_object_t *obj) static void ucl_object_free_internal (ucl_object_t *obj, bool allow_rec, ucl_object_dtor dtor) { - ucl_object_t *sub, *tmp; + ucl_object_t *tmp, *sub; while (obj != NULL) { if (obj->type == UCL_ARRAY) { - sub = obj->value.av; - while (sub != NULL) { - tmp = sub->next; - dtor (sub); - sub = tmp; + UCL_ARRAY_GET (vec, obj); + unsigned int i; + + if (vec != NULL) { + for (i = 0; i < vec->n; i ++) { + sub = kv_A (*vec, i); + if (sub != NULL) { + tmp = sub; + while (sub) { + tmp = sub->next; + dtor (sub); + sub = tmp; + } + } + } + kv_destroy (*vec); + UCL_FREE (sizeof (*vec), vec); } } else if (obj->type == UCL_OBJECT) { @@ -455,6 +480,15 @@ ucl_parser_get_error(struct ucl_parser *parser) return utstring_body(parser->err); } +UCL_EXTERN void +ucl_parser_clear_error(struct ucl_parser *parser) +{ + if (parser != NULL && parser->err != NULL) { + utstring_free(parser->err); + parser->err = NULL; + } +} + UCL_EXTERN bool ucl_pubkey_add (struct ucl_parser *parser, const unsigned char *key, size_t len) { @@ -933,10 +967,10 @@ ucl_include_file (const unsigned char *data, size_t len, const unsigned char *p = data, *end = data + len; bool need_glob = false; int cnt = 0; - glob_t globbuf; char glob_pattern[PATH_MAX]; size_t i; +#ifndef _WIN32 if (!allow_glob) { return ucl_include_file_single (data, len, parser, check_signature, must_exist, priority); @@ -951,6 +985,7 @@ ucl_include_file (const unsigned char *data, size_t len, p ++; } if (need_glob) { + glob_t globbuf; memset (&globbuf, 0, sizeof (globbuf)); ucl_strlcpy (glob_pattern, (const char *)data, sizeof (glob_pattern)); if (glob (glob_pattern, 0, NULL, &globbuf) != 0) { @@ -978,7 +1013,13 @@ ucl_include_file (const unsigned char *data, size_t len, must_exist, priority); } } - +#else + /* Win32 compilers do not support globbing. Therefore, for Win32, + treat allow_glob/need_glob as a NOOP and just return */ + return ucl_include_file_single (data, len, parser, check_signature, + must_exist, priority); +#endif + return true; } @@ -1394,7 +1435,7 @@ ucl_object_insert_key_common (ucl_object_t *top, ucl_object_t *elt, } if (top->value.ov == NULL) { - top->value.ov = ucl_hash_create (); + top->value.ov = ucl_hash_create (false); } if (keylen == 0) { @@ -1427,7 +1468,7 @@ ucl_object_insert_key_common (ucl_object_t *top, ucl_object_t *elt, found = __DECONST (ucl_object_t *, ucl_hash_search_obj (top->value.ov, elt)); if (found == NULL) { - top->value.ov = ucl_hash_insert_object (top->value.ov, elt); + top->value.ov = ucl_hash_insert_object (top->value.ov, elt, false); top->len ++; if (replace) { ret = false; @@ -1444,7 +1485,7 @@ ucl_object_insert_key_common (ucl_object_t *top, ucl_object_t *elt, ucl_object_insert_key_common (elt, found, found->key, found->keylen, copy_key, false, false); ucl_hash_delete (top->value.ov, found); - top->value.ov = ucl_hash_insert_object (top->value.ov, elt); + top->value.ov = ucl_hash_insert_object (top->value.ov, elt, false); } else if (found->type == UCL_OBJECT && elt->type != UCL_OBJECT) { /* Insert new to old */ @@ -1568,7 +1609,7 @@ ucl_object_merge (ucl_object_t *top, ucl_object_t *elt, bool copy) found = __DECONST(ucl_object_t *, ucl_hash_search (top->value.ov, cp->key, cp->keylen)); if (found == NULL) { /* The key does not exist */ - top->value.ov = ucl_hash_insert_object (top->value.ov, cp); + top->value.ov = ucl_hash_insert_object (top->value.ov, cp, false); top->len ++; } else { @@ -1610,7 +1651,7 @@ ucl_object_find_key (const ucl_object_t *obj, const char *key) const ucl_object_t* ucl_iterate_object (const ucl_object_t *obj, ucl_object_iter_t *iter, bool expand_values) { - const ucl_object_t *elt; + const ucl_object_t *elt = NULL; if (obj == NULL || iter == NULL) { return NULL; @@ -1621,19 +1662,25 @@ ucl_iterate_object (const ucl_object_t *obj, ucl_object_iter_t *iter, bool expan case UCL_OBJECT: return (const ucl_object_t*)ucl_hash_iterate (obj->value.ov, iter); break; - case UCL_ARRAY: - elt = *iter; - if (elt == NULL) { - elt = obj->value.av; - if (elt == NULL) { - return NULL; + case UCL_ARRAY: { + unsigned int idx; + UCL_ARRAY_GET (vec, obj); + idx = (unsigned int)(uintptr_t)(*iter); + + if (vec != NULL) { + while (idx < kv_size (*vec)) { + if ((elt = kv_A (*vec, idx)) != NULL) { + idx ++; + break; + } + idx ++; } + *iter = (void *)(uintptr_t)idx; } - else if (elt == obj->value.av) { - return NULL; - } - *iter = elt->next ? elt->next : obj->value.av; + return elt; + break; + } default: /* Go to linear iteration */ break; @@ -1654,6 +1701,95 @@ ucl_iterate_object (const ucl_object_t *obj, ucl_object_iter_t *iter, bool expan return NULL; } +const char safe_iter_magic[4] = {'u', 'i', 't', 'e'}; +struct ucl_object_safe_iter { + char magic[4]; /* safety check */ + const ucl_object_t *impl_it; /* implicit object iteration */ + ucl_object_iter_t expl_it; /* explicit iteration */ +}; + +#define UCL_SAFE_ITER(ptr) (struct ucl_object_safe_iter *)(ptr) +#define UCL_SAFE_ITER_CHECK(it) do { \ + assert (it != NULL); \ + assert (memcmp (it->magic, safe_iter_magic, sizeof (it->magic)) == 0); \ + } while (0) + +ucl_object_iter_t +ucl_object_iterate_new (const ucl_object_t *obj) +{ + struct ucl_object_safe_iter *it; + + it = UCL_ALLOC (sizeof (*it)); + if (it != NULL) { + memcpy (it->magic, safe_iter_magic, sizeof (it->magic)); + it->expl_it = NULL; + it->impl_it = obj; + } + + return (ucl_object_iter_t)it; +} + + +ucl_object_iter_t +ucl_object_iterate_reset (ucl_object_iter_t it, const ucl_object_t *obj) +{ + struct ucl_object_safe_iter *rit = UCL_SAFE_ITER (it); + + UCL_SAFE_ITER_CHECK (rit); + + rit->impl_it = obj; + rit->expl_it = NULL; + + return it; +} + +const ucl_object_t* +ucl_object_iterate_safe (ucl_object_iter_t it, bool expand_values) +{ + struct ucl_object_safe_iter *rit = UCL_SAFE_ITER (it); + const ucl_object_t *ret = NULL; + + UCL_SAFE_ITER_CHECK (rit); + + if (rit->impl_it == NULL) { + return NULL; + } + + if (rit->impl_it->type == UCL_OBJECT || rit->impl_it->type == UCL_ARRAY) { + ret = ucl_iterate_object (rit->impl_it, &rit->expl_it, true); + + if (ret == NULL) { + /* Need to switch to another implicit object in chain */ + rit->impl_it = rit->impl_it->next; + rit->expl_it = NULL; + return ucl_object_iterate_safe (it, expand_values); + } + } + else { + /* Just iterate over the implicit array */ + ret = rit->impl_it; + rit->impl_it = rit->impl_it->next; + if (expand_values) { + /* We flatten objects if need to expand values */ + if (ret->type == UCL_OBJECT || ret->type == UCL_ARRAY) { + return ucl_object_iterate_safe (it, expand_values); + } + } + } + + return ret; +} + +void +ucl_object_iterate_free (ucl_object_iter_t it) +{ + struct ucl_object_safe_iter *rit = UCL_SAFE_ITER (it); + + UCL_SAFE_ITER_CHECK (rit); + + UCL_FREE (sizeof (*rit), it); +} + const ucl_object_t * ucl_lookup_path (const ucl_object_t *top, const char *path_in) { const ucl_object_t *o = NULL, *found; @@ -1733,6 +1869,17 @@ ucl_object_new_full (ucl_type_t type, unsigned priority) new->next = NULL; new->prev = new; ucl_object_set_priority (new, priority); + + if (type == UCL_ARRAY) { + new->value.av = UCL_ALLOC (sizeof (ucl_array_t)); + if (new->value.av) { + memset (new->value.av, 0, sizeof (ucl_array_t)); + UCL_ARRAY_GET (vec, new); + + /* Preallocate some space for arrays */ + kv_resize (ucl_object_t *, *vec, 8); + } + } } } else { @@ -1826,23 +1973,20 @@ ucl_object_frombool (bool bv) bool ucl_array_append (ucl_object_t *top, ucl_object_t *elt) { - ucl_object_t *head; + UCL_ARRAY_GET (vec, top); if (elt == NULL || top == NULL) { return false; } - head = top->value.av; - if (head == NULL) { - top->value.av = elt; - elt->prev = elt; + if (vec == NULL) { + vec = UCL_ALLOC (sizeof (*vec)); + kv_init (*vec); + top->value.av = (void *)vec; } - else { - elt->prev = head->prev; - head->prev->next = elt; - head->prev = elt; - } - elt->next = NULL; + + kv_push (ucl_object_t *, *vec, elt); + top->len ++; return true; @@ -1851,24 +1995,23 @@ ucl_array_append (ucl_object_t *top, ucl_object_t *elt) bool ucl_array_prepend (ucl_object_t *top, ucl_object_t *elt) { - ucl_object_t *head; + UCL_ARRAY_GET (vec, top); if (elt == NULL || top == NULL) { return false; } - - head = top->value.av; - if (head == NULL) { - top->value.av = elt; - elt->prev = elt; + if (vec == NULL) { + vec = UCL_ALLOC (sizeof (*vec)); + kv_init (*vec); + top->value.av = (void *)vec; + kv_push (ucl_object_t *, *vec, elt); } else { - elt->prev = head->prev; - head->prev = elt; + /* Slow O(n) algorithm */ + kv_prepend (ucl_object_t *, *vec, elt); } - elt->next = head; - top->value.av = elt; + top->len ++; return true; @@ -1877,21 +2020,29 @@ ucl_array_prepend (ucl_object_t *top, ucl_object_t *elt) bool ucl_array_merge (ucl_object_t *top, ucl_object_t *elt, bool copy) { - ucl_object_t *cur, *tmp, *cp; + unsigned i; + ucl_object_t **obj; + UCL_ARRAY_GET (v1, top); + UCL_ARRAY_GET (v2, elt); if (elt == NULL || top == NULL || top->type != UCL_ARRAY || elt->type != UCL_ARRAY) { return false; } - DL_FOREACH_SAFE (elt->value.av, cur, tmp) { + kv_concat (ucl_object_t *, *v1, *v2); + + for (i = v2->n; i < v1->n; i ++) { + obj = &kv_A (*v1, i); + if (*obj == NULL) { + continue; + } + + top->len ++; if (copy) { - cp = ucl_object_copy (cur); + *obj = ucl_object_copy (*obj); } else { - cp = ucl_object_ref (cur); - } - if (cp != NULL) { - ucl_array_append (top, cp); + ucl_object_ref (*obj); } } @@ -1901,82 +2052,85 @@ ucl_array_merge (ucl_object_t *top, ucl_object_t *elt, bool copy) ucl_object_t * ucl_array_delete (ucl_object_t *top, ucl_object_t *elt) { - ucl_object_t *head; - - if (top == NULL || top->type != UCL_ARRAY || top->value.av == NULL) { - return NULL; - } - head = top->value.av; + UCL_ARRAY_GET (vec, top); + ucl_object_t *ret = NULL; + unsigned i; - if (elt->prev == elt) { - top->value.av = NULL; - } - else if (elt == head) { - elt->next->prev = elt->prev; - top->value.av = elt->next; - } - else { - elt->prev->next = elt->next; - if (elt->next) { - elt->next->prev = elt->prev; - } - else { - head->prev = elt->prev; + for (i = 0; i < vec->n; i ++) { + if (kv_A (*vec, i) == elt) { + kv_del (ucl_object_t *, *vec, i); + ret = elt; + top->len --; + break; } } - elt->next = NULL; - elt->prev = elt; - top->len --; - return elt; + return ret; } const ucl_object_t * ucl_array_head (const ucl_object_t *top) { + UCL_ARRAY_GET (vec, top); + if (top == NULL || top->type != UCL_ARRAY || top->value.av == NULL) { return NULL; } - return top->value.av; + + return (vec->n > 0 ? vec->a[0] : NULL); } const ucl_object_t * ucl_array_tail (const ucl_object_t *top) { + UCL_ARRAY_GET (vec, top); + if (top == NULL || top->type != UCL_ARRAY || top->value.av == NULL) { return NULL; } - return top->value.av->prev; + + return (vec->n > 0 ? vec->a[vec->n - 1] : NULL); } ucl_object_t * ucl_array_pop_last (ucl_object_t *top) { - return ucl_array_delete (top, __DECONST(ucl_object_t *, ucl_array_tail (top))); + UCL_ARRAY_GET (vec, top); + ucl_object_t **obj, *ret = NULL; + + if (vec != NULL && vec->n > 0) { + obj = &kv_A (*vec, vec->n - 1); + ret = *obj; + kv_del (ucl_object_t *, *vec, vec->n - 1); + top->len --; + } + + return ret; } ucl_object_t * ucl_array_pop_first (ucl_object_t *top) { - return ucl_array_delete (top, __DECONST(ucl_object_t *, ucl_array_head (top))); + UCL_ARRAY_GET (vec, top); + ucl_object_t **obj, *ret = NULL; + + if (vec != NULL && vec->n > 0) { + obj = &kv_A (*vec, 0); + ret = *obj; + kv_del (ucl_object_t *, *vec, 0); + top->len --; + } + + return ret; } const ucl_object_t * ucl_array_find_index (const ucl_object_t *top, unsigned int index) { - ucl_object_iter_t it = NULL; - const ucl_object_t *ret; - - if (top == NULL || top->type != UCL_ARRAY || top->len == 0 || - (index + 1) > top->len) { - return NULL; - } + UCL_ARRAY_GET (vec, top); - while ((ret = ucl_iterate_object (top, &it, true)) != NULL) { - if (index == 0) { - return ret; - } - --index; + if (vec != NULL && vec->n > 0 && index < vec->n) { + return kv_A (*vec, index); } return NULL; @@ -1986,22 +2140,15 @@ ucl_object_t * ucl_array_replace_index (ucl_object_t *top, ucl_object_t *elt, unsigned int index) { - ucl_object_t *cur, *tmp; + UCL_ARRAY_GET (vec, top); + ucl_object_t *ret = NULL; - if (top == NULL || top->type != UCL_ARRAY || elt == NULL || - top->len == 0 || (index + 1) > top->len) { - return NULL; + if (vec != NULL && vec->n > 0 && index < vec->n) { + ret = kv_A (*vec, index); + kv_A (*vec, index) = elt; } - DL_FOREACH_SAFE (top->value.av, cur, tmp) { - if (index == 0) { - DL_REPLACE_ELEM (top->value.av, cur, elt); - return cur; - } - --index; - } - - return NULL; + return ret; } ucl_object_t * @@ -2314,7 +2461,7 @@ ucl_object_compare (const ucl_object_t *o1, const ucl_object_t *o2) switch (o1->type) { case UCL_STRING: - if (o1->len == o2->len) { + if (o1->len == o2->len && o1->len > 0) { ret = strcmp (ucl_object_tostring(o1), ucl_object_tostring(o2)); } else { @@ -2330,17 +2477,28 @@ ucl_object_compare (const ucl_object_t *o1, const ucl_object_t *o2) ret = ucl_object_toboolean (o1) - ucl_object_toboolean (o2); break; case UCL_ARRAY: - if (o1->len == o2->len) { - it1 = o1->value.av; - it2 = o2->value.av; + if (o1->len == o2->len && o1->len > 0) { + UCL_ARRAY_GET (vec1, o1); + UCL_ARRAY_GET (vec2, o2); + unsigned i; + /* Compare all elements in both arrays */ - while (it1 != NULL && it2 != NULL) { - ret = ucl_object_compare (it1, it2); - if (ret != 0) { - break; + for (i = 0; i < vec1->n; i ++) { + it1 = kv_A (*vec1, i); + it2 = kv_A (*vec2, i); + + if (it1 == NULL && it2 != NULL) { + return -1; + } + else if (it2 == NULL && it1 != NULL) { + return 1; + } + else if (it1 != NULL && it2 != NULL) { + ret = ucl_object_compare (it1, it2); + if (ret != 0) { + break; + } } - it1 = it1->next; - it2 = it2->next; } } else { @@ -2348,7 +2506,7 @@ ucl_object_compare (const ucl_object_t *o1, const ucl_object_t *o2) } break; case UCL_OBJECT: - if (o1->len == o2->len) { + if (o1->len == o2->len && o1->len > 0) { while ((it1 = ucl_iterate_object (o1, &iter, true)) != NULL) { it2 = ucl_object_find_key (o2, ucl_object_key (it1)); if (it2 == NULL) { @@ -2377,11 +2535,14 @@ void ucl_object_array_sort (ucl_object_t *ar, int (*cmp)(const ucl_object_t *o1, const ucl_object_t *o2)) { + UCL_ARRAY_GET (vec, ar); + if (cmp == NULL || ar == NULL || ar->type != UCL_ARRAY) { return; } - DL_SORT (ar->value.av, cmp); + qsort (vec->a, vec->n, sizeof (ucl_object_t *), + (int (*)(const void *, const void *))cmp); } #define PRIOBITS 4 diff --git a/contrib/libucl/tests/basic/14.in b/contrib/libucl/tests/basic/14.in new file mode 100644 index 000000000000..62d2e6059296 --- /dev/null +++ b/contrib/libucl/tests/basic/14.in @@ -0,0 +1,8 @@ +# Bad comments case + +section { +# key = value; +} +.include(try=true) "./1.in" + +key = value; diff --git a/contrib/libucl/tests/basic/14.res b/contrib/libucl/tests/basic/14.res new file mode 100644 index 000000000000..f803349a6000 --- /dev/null +++ b/contrib/libucl/tests/basic/14.res @@ -0,0 +1,4 @@ +section { +} +key = "value"; + diff --git a/contrib/libucl/tests/schema.test b/contrib/libucl/tests/schema.test index 0f2c252945c7..fd26804fa295 100755 --- a/contrib/libucl/tests/schema.test +++ b/contrib/libucl/tests/schema.test @@ -5,5 +5,5 @@ rm /tmp/_ucl_test_schema.out ||true for i in ${TEST_DIR}/schema/*.json ; do _name=`basename $i` printf "running schema test suite $_name... " - $PROG >> /tmp/_ucl_test_schema.out < $i && ( echo "OK" ) || ( echo "Fail" ) + $PROG >> /tmp/_ucl_test_schema.out < $i && ( echo "OK" ) || ( echo "Fail" ; exit 1 ) done diff --git a/contrib/libucl/tests/test_generate.c b/contrib/libucl/tests/test_generate.c index aad92b51fb0e..f09eabb839fe 100644 --- a/contrib/libucl/tests/test_generate.c +++ b/contrib/libucl/tests/test_generate.c @@ -30,7 +30,8 @@ int main (int argc, char **argv) { ucl_object_t *obj, *cur, *ar, *ref; - const ucl_object_t *found; + ucl_object_iter_t it; + const ucl_object_t *found, *it_obj; FILE *out; unsigned char *emitted; const char *fname_out = NULL; @@ -59,7 +60,7 @@ main (int argc, char **argv) cur = ucl_object_fromstring_common ("value1", 0, UCL_STRING_TRIM); ucl_object_insert_key (obj, cur, "key0", 0, false); cur = ucl_object_fromdouble (0.1); - ucl_object_replace_key (obj, cur, "key0", 0, false); + assert (ucl_object_replace_key (obj, cur, "key0", 0, false)); /* Create some strings */ cur = ucl_object_fromstring_common (" test string ", 0, UCL_STRING_TRIM); @@ -139,6 +140,33 @@ main (int argc, char **argv) found = ucl_lookup_path (obj, "key9..key1"); assert (found == NULL); + /* Test iteration */ + it = ucl_object_iterate_new (obj); + it_obj = ucl_object_iterate_safe (it, true); + /* key0 = 0.1 */ + assert (ucl_object_type (it_obj) == UCL_FLOAT); + it_obj = ucl_object_iterate_safe (it, true); + /* key1 = "" */ + assert (ucl_object_type (it_obj) == UCL_STRING); + it_obj = ucl_object_iterate_safe (it, true); + /* key2 = "" */ + assert (ucl_object_type (it_obj) == UCL_STRING); + it_obj = ucl_object_iterate_safe (it, true); + /* key3 = "" */ + assert (ucl_object_type (it_obj) == UCL_STRING); + it_obj = ucl_object_iterate_safe (it, true); + /* key4 = ([float, int, float], boolean) */ + ucl_object_iterate_reset (it, it_obj); + it_obj = ucl_object_iterate_safe (it, true); + assert (ucl_object_type (it_obj) == UCL_FLOAT); + it_obj = ucl_object_iterate_safe (it, true); + assert (ucl_object_type (it_obj) == UCL_INT); + it_obj = ucl_object_iterate_safe (it, true); + assert (ucl_object_type (it_obj) == UCL_FLOAT); + it_obj = ucl_object_iterate_safe (it, true); + assert (ucl_object_type (it_obj) == UCL_BOOLEAN); + ucl_object_iterate_free (it); + emitted = ucl_object_emit (obj, UCL_EMIT_CONFIG); fprintf (out, "%s\n", emitted); diff --git a/contrib/libucl/tests/test_schema.c b/contrib/libucl/tests/test_schema.c index 7acebb84b934..4f075dae8d68 100644 --- a/contrib/libucl/tests/test_schema.c +++ b/contrib/libucl/tests/test_schema.c @@ -79,6 +79,8 @@ perform_test (const ucl_object_t *schema, const ucl_object_t *obj, ucl_object_tostring (description), ucl_object_toboolean (valid) ? "valid" : "invalid", err->msg); + fprintf (stdout, "%s\n", ucl_object_emit (data, UCL_EMIT_CONFIG)); + fprintf (stdout, "%s\n", ucl_object_emit (schema, UCL_EMIT_CONFIG)); return false; } diff --git a/contrib/libucl/uthash/utstring.h b/contrib/libucl/uthash/utstring.h index f11f34b77e75..b4399484c70e 100644 --- a/contrib/libucl/uthash/utstring.h +++ b/contrib/libucl/uthash/utstring.h @@ -39,7 +39,7 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. #include <stdarg.h> #ifndef oom -#define oom() exit(-1) +#define oom abort #endif typedef struct { @@ -54,8 +54,8 @@ do { \ if (((s)->n - (s)->i) < (size_t)(amt)) { \ (s)->d = (char*)realloc((s)->d, (s)->n + amt); \ if ((s)->d == NULL) oom(); \ - (s)->n += amt; \ - if ((s)->pd) *((s)->pd) = (s)->d; \ + else {(s)->n += amt; \ + if ((s)->pd) *((s)->pd) = (s)->d;} \ } \ } while(0) @@ -82,7 +82,7 @@ do { \ do { \ s = (UT_string*)calloc(1, sizeof(UT_string)); \ if (!s) oom(); \ - utstring_init(s); \ + else utstring_init(s); \ } while(0) #define utstring_renew(s) \ diff --git a/contrib/libucl/utils/objdump.c b/contrib/libucl/utils/objdump.c index d3f7cd1bcec6..74581baafddb 100644 --- a/contrib/libucl/utils/objdump.c +++ b/contrib/libucl/utils/objdump.c @@ -46,7 +46,7 @@ ucl_obj_dump (const ucl_object_t *obj, unsigned int shift) if (obj->key != NULL) { printf ("%skey: \"%s\"\n", pre, ucl_object_key (obj)); } - printf ("%sref: %hd\n", pre, obj->ref); + printf ("%sref: %u\n", pre, obj->ref); printf ("%slen: %u\n", pre, obj->len); printf ("%sprev: %p\n", pre, obj->prev); printf ("%snext: %p\n", pre, obj->next); @@ -61,7 +61,10 @@ ucl_obj_dump (const ucl_object_t *obj, unsigned int shift) else if (obj->type == UCL_ARRAY) { printf ("%stype: UCL_ARRAY\n", pre); printf ("%svalue: %p\n", pre, obj->value.av); - ucl_obj_dump (obj->value.av, shift + 2); + it_obj = NULL; + while ((cur = ucl_iterate_object (obj, &it_obj, true))) { + ucl_obj_dump (cur, shift + 2); + } } else if (obj->type == UCL_INT) { printf ("%stype: UCL_INT\n", pre); @@ -96,7 +99,7 @@ int main(int argc, char **argv) { const char *fn = NULL; - char inbuf[8192]; + unsigned char inbuf[8192]; struct ucl_parser *parser; int k, ret = 0, r = 0; ucl_object_t *obj = NULL; diff --git a/contrib/mdocml/LICENSE b/contrib/mdocml/LICENSE index 12bf65ade9c7..080c04fa2607 100644 --- a/contrib/mdocml/LICENSE +++ b/contrib/mdocml/LICENSE @@ -1,16 +1,17 @@ -$Id: LICENSE,v 1.5 2014/12/11 07:56:24 schwarze Exp $ +$Id: LICENSE,v 1.7 2015/02/16 14:56:22 schwarze Exp $ With the exceptions noted below, all code and documentation contained in the mdocml toolkit is protected by the Copyright of the following developers: Copyright (c) 2008-2012, 2014 Kristaps Dzonsons <kristaps@bsd.lv> -Copyright (c) 2010, 2011, 2012, 2013, 2014 Ingo Schwarze <schwarze@openbsd.org> +Copyright (c) 2010-2015 Ingo Schwarze <schwarze@openbsd.org> Copyright (c) 2009, 2010, 2011, 2012 Joerg Sonnenberger <joerg@netbsd.org> Copyright (c) 2013 Franco Fichtner <franco@lastsummer.de> Copyright (c) 1999, 2004 Marc Espie <espie@openbsd.org> -Copyright (c) 1998, 2010 Todd C. Miller <Todd.Miller@courtesan.com> +Copyright (c) 1998, 2004, 2010 Todd C. Miller <Todd.Miller@courtesan.com> Copyright (c) 2008 Otto Moerbeek <otto@drijf.net> +Copyright (c) 2004 Ted Unangst <tedu@openbsd.org> Copyright (c) 2003, 2007, 2008, 2014 Jason McIntyre <jmc@openbsd.org> See the individual source files for information about who contributed diff --git a/contrib/mdocml/Makefile b/contrib/mdocml/Makefile index e3f48f711798..d686e01455d6 100644 --- a/contrib/mdocml/Makefile +++ b/contrib/mdocml/Makefile @@ -1,4 +1,4 @@ -# $Id: Makefile,v 1.453 2014/12/09 09:14:33 schwarze Exp $ +# $Id: Makefile,v 1.456 2015/02/16 16:23:54 schwarze Exp $ # # Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> # Copyright (c) 2011, 2013, 2014 Ingo Schwarze <schwarze@openbsd.org> @@ -15,6 +15,8 @@ # ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF # OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +VERSION = 1.13.2 + # === LIST OF FILES ==================================================== TESTSRCS = test-dirent-namlen.c \ @@ -31,6 +33,7 @@ TESTSRCS = test-dirent-namlen.c \ test-strlcpy.c \ test-strptime.c \ test-strsep.c \ + test-strtonum.c \ test-wchar.c SRCS = att.c \ @@ -46,6 +49,7 @@ SRCS = att.c \ compat_strlcat.c \ compat_strlcpy.c \ compat_strsep.c \ + compat_strtonum.c \ demandoc.c \ eqn.c \ eqn_html.c \ @@ -189,7 +193,8 @@ COMPAT_OBJS = compat_fgetln.o \ compat_strcasestr.o \ compat_strlcat.o \ compat_strlcpy.o \ - compat_strsep.o + compat_strsep.o \ + compat_strtonum.o MANDOC_HTML_OBJS = eqn_html.o \ html.o \ @@ -211,6 +216,7 @@ BASE_OBJS = $(MANDOC_HTML_OBJS) \ $(MANDOC_MAN_OBJS) \ $(MANDOC_TERM_OBJS) \ main.o \ + manpath.o \ out.o \ tree.o @@ -218,8 +224,7 @@ MAIN_OBJS = $(BASE_OBJS) DB_OBJS = mandocdb.o \ mansearch.o \ - mansearch_const.o \ - manpath.o + mansearch_const.o CGI_OBJS = $(MANDOC_HTML_OBJS) \ cgi.o \ @@ -308,10 +313,12 @@ base-install: base-build mkdir -p $(DESTDIR)$(MANDIR)/man3 mkdir -p $(DESTDIR)$(MANDIR)/man7 $(INSTALL_PROGRAM) mandoc demandoc $(DESTDIR)$(BINDIR) + ln -f $(DESTDIR)$(BINDIR)/mandoc $(DESTDIR)$(BINDIR)/$(BINM_MAN) $(INSTALL_LIB) libmandoc.a $(DESTDIR)$(LIBDIR) $(INSTALL_LIB) man.h mandoc.h mandoc_aux.h mdoc.h \ $(DESTDIR)$(INCLUDEDIR) $(INSTALL_MAN) mandoc.1 demandoc.1 $(DESTDIR)$(MANDIR)/man1 + $(INSTALL_MAN) man.1 $(DESTDIR)$(MANDIR)/man1/$(BINM_MAN).1 $(INSTALL_MAN) mandoc.3 mandoc_escape.3 mandoc_malloc.3 \ mchars_alloc.3 tbl.3 $(DESTDIR)$(MANDIR)/man3 $(INSTALL_MAN) man.7 $(DESTDIR)$(MANDIR)/man7/${MANM_MAN}.7 @@ -330,12 +337,10 @@ db-install: base-build mkdir -p $(DESTDIR)$(MANDIR)/man5 mkdir -p $(DESTDIR)$(MANDIR)/man8 ln -f $(DESTDIR)$(BINDIR)/mandoc $(DESTDIR)$(BINDIR)/$(BINM_APROPOS) - ln -f $(DESTDIR)$(BINDIR)/mandoc $(DESTDIR)$(BINDIR)/$(BINM_MAN) ln -f $(DESTDIR)$(BINDIR)/mandoc $(DESTDIR)$(BINDIR)/$(BINM_WHATIS) ln -f $(DESTDIR)$(BINDIR)/mandoc \ $(DESTDIR)$(SBINDIR)/$(BINM_MAKEWHATIS) $(INSTALL_MAN) apropos.1 $(DESTDIR)$(MANDIR)/man1/$(BINM_APROPOS).1 - $(INSTALL_MAN) man.1 $(DESTDIR)$(MANDIR)/man1/$(BINM_MAN).1 ln -f $(DESTDIR)$(MANDIR)/man1/$(BINM_APROPOS).1 \ $(DESTDIR)$(MANDIR)/man1/$(BINM_WHATIS).1 $(INSTALL_MAN) mansearch.3 $(DESTDIR)$(MANDIR)/man3 @@ -377,7 +382,7 @@ demandoc: $(DEMANDOC_OBJS) libmandoc.a www-install: www mkdir -p $(HTDOCDIR)/snapshots - $(INSTALL_DATA) $(WWW_MANS) style.css $(HTDOCDIR)/man + $(INSTALL_DATA) $(WWW_MANS) style.css $(HTDOCDIR) $(INSTALL_DATA) $(WWW_OBJS) $(HTDOCDIR)/snapshots $(INSTALL_DATA) mdocml.tar.gz \ $(HTDOCDIR)/snapshots/mdocml-$(VERSION).tar.gz diff --git a/contrib/mdocml/Makefile.depend b/contrib/mdocml/Makefile.depend index a61de19fcdd7..54af8bce33ec 100644 --- a/contrib/mdocml/Makefile.depend +++ b/contrib/mdocml/Makefile.depend @@ -11,6 +11,7 @@ compat_strcasestr.o: compat_strcasestr.c config.h compat_strlcat.o: compat_strlcat.c config.h compat_strlcpy.o: compat_strlcpy.c config.h compat_strsep.o: compat_strsep.c config.h +compat_strtonum.o: compat_strtonum.c config.h demandoc.o: demandoc.c config.h man.h mdoc.h mandoc.h eqn.o: eqn.c config.h mandoc.h mandoc_aux.h libmandoc.h libroff.h eqn_html.o: eqn_html.c config.h mandoc.h out.h html.h @@ -39,7 +40,7 @@ mdoc_macro.o: mdoc_macro.c config.h mdoc.h mandoc.h libmdoc.h libmandoc.h mdoc_man.o: mdoc_man.c config.h mandoc.h mandoc_aux.h out.h man.h mdoc.h main.h mdoc_term.o: mdoc_term.c config.h mandoc.h mandoc_aux.h out.h term.h mdoc.h main.h mdoc_validate.o: mdoc_validate.c config.h mdoc.h mandoc.h mandoc_aux.h libmdoc.h libmandoc.h -msec.o: msec.c config.h libmandoc.h msec.in +msec.o: msec.c config.h mandoc.h libmandoc.h msec.in out.o: out.c config.h mandoc_aux.h mandoc.h out.h preconv.o: preconv.c config.h mandoc.h libmandoc.h read.o: read.c config.h mandoc.h mandoc_aux.h libmandoc.h mdoc.h man.h @@ -69,4 +70,5 @@ test-strlcat.o: test-strlcat.c test-strlcpy.o: test-strlcpy.c test-strptime.o: test-strptime.c test-strsep.o: test-strsep.c +test-strtonum.o: test-strtonum.c test-wchar.o: test-wchar.c diff --git a/contrib/mdocml/Makefile.local b/contrib/mdocml/Makefile.local new file mode 100644 index 000000000000..b197fdfdb2b2 --- /dev/null +++ b/contrib/mdocml/Makefile.local @@ -0,0 +1,30 @@ +BUILD_TARGETS = base-build +INSTALL_TARGETS = base-install db-install +CFLAGS = -g -W -Wall -Wstrict-prototypes -Wno-unused-parameter -Wwrite-strings -I/usr/local/include +DBLIB = -L/usr/local/lib -lsqlite3 +STATIC = -static +PREFIX = /usr/local +BINDIR = /usr/local/bin +SBINDIR = /usr/local/sbin +INCLUDEDIR = /usr/local/include/mandoc +LIBDIR = /usr/local/lib/mandoc +MANDIR = /usr/local/man +EXAMPLEDIR = /usr/local/share/examples/mandoc +WWWPREFIX = /var/www +HTDOCDIR = /var/www/htdocs +CGIBINDIR = /var/www/cgi-bin +BINM_APROPOS = apropos +BINM_MAN = man +BINM_WHATIS = whatis +BINM_MAKEWHATIS = makewhatis +MANM_MAN = man +MANM_MDOC = mdoc +MANM_ROFF = roff +MANM_EQN = eqn +MANM_TBL = tbl +INSTALL = install +INSTALL_PROGRAM = install -m 0555 +INSTALL_LIB = install -m 0444 +INSTALL_MAN = install -m 0444 +INSTALL_DATA = install -m 0444 +MAIN_OBJS = $(BASE_OBJS) $(DB_OBJS) diff --git a/contrib/mdocml/TODO b/contrib/mdocml/TODO index b213e8b92c26..ebd488ccee6a 100644 --- a/contrib/mdocml/TODO +++ b/contrib/mdocml/TODO @@ -1,6 +1,6 @@ ************************************************************************ * Official mandoc TODO. -* $Id: TODO,v 1.195 2014/12/13 13:14:39 schwarze Exp $ +* $Id: TODO,v 1.201 2015/02/20 13:47:28 schwarze Exp $ ************************************************************************ Many issues are annotated for difficulty as follows: @@ -60,7 +60,7 @@ are mere guesses, and some may be wrong. - .fc (field control) found by naddy@ in xloadimage(1) loc ** exist *** algo * size * imp * - + - .nr third argument (auto-increment step size, requires \n+) found by bentley@ in sbcl(1) Mon, 9 Dec 2013 18:36:57 -0700 loc * exist * algo * size * imp ** @@ -69,31 +69,37 @@ are mere guesses, and some may be wrong. reported by brad@ Sat, 15 Jan 2011 15:45:23 -0500 loc *** exist *** algo *** size ** imp * -- .ta (tab settings) occurs in ircbug(1) and probably gnats(1) - reported by brad@ Sat, 15 Jan 2011 15:50:51 -0500 +- .ta (tab settings) + #1 most important issue naddy@ Mon, 16 Feb 2015 20:59:17 +0100 + ircbug(1) gnats(1) reported by brad@ Sat, 15 Jan 2011 15:50:51 -0500 also Tcl_NewStringObj(3) via wiz@ Wed, 5 Mar 2014 22:27:43 +0100 also posix2time(3) Carsten Kunze Mon, 1 Dec 2014 13:03:10 +0100 loc ** exist *** algo ** size ** imp *** - .ti (temporary indent) - found by naddy@ in xloadimage(1) + found by naddy@ in xloadimage(1) [devel/libvstr] vstr(3) found by bentley@ in nmh(1) Mon, 23 Apr 2012 13:38:28 -0600 loc ** exist ** algo ** size * imp ** (parser reorg helps a lot) -- .while and .shift +- .while and .shift found by jca@ in ratpoison(1) Sun, 30 Jun 2013 12:01:09 +0200 loc * exist ** algo ** size ** imp ** - \h horizontal move - found in cclive(1) and nasm(1) asciidoc/DocBook output + #2 most important issue naddy@ Mon, 16 Feb 2015 20:59:17 +0100 + found in cclive(1) nasm(1) bogofilter(1) asciidoc/DocBook output bentley@ on discuss@ Sat, 21 Sep 2013 22:29:34 -0600 naddy@ Thu, 4 Dec 2014 16:26:41 +0100 - loc ** exist ** algo ** size * imp ** (parser reorg helps a lot) + loc ** exist ** algo ** size * imp *** (parser reorg helps a lot) - \n+ and \n- numerical register increment and decrement found by bentley@ in sbcl(1) Mon, 9 Dec 2013 18:36:57 -0700 loc * exist * algo * size * imp ** +- \n(.$ macro argument count number register; ocserv(8) by autogen + found by sthen@ Thu, 19 Feb 2015 22:03:01 +0000 + loc * exist ** algo * size * imp ** + - \w'' improve width measurements would not be very useful without an expression parser, see below needed for Tcl_NewStringObj(3) via wiz@ Wed, 5 Mar 2014 22:27:43 +0100 @@ -105,10 +111,6 @@ are mere guesses, and some may be wrong. --- missing mdoc features ---------------------------------------------- -- fix bad block nesting involving multiple identical explicit blocks - see the OpenBSD mdoc_macro.c 1.47 commit message - loc * exist *** algo *** size * imp ** - - .Bl -column .Xo support is missing ultimate goal: restore .Xr and .Dv to @@ -255,6 +257,10 @@ are mere guesses, and some may be wrong. --- compatibility checks ----------------------------------------------- +- write a configure check for [[:<:]] support and provide some + fallback for whatis(1) when it doesn't work; + Svyatoslav Mishyn Wed, 17 Dec 2014 11:07:10 +0200 + - is .Bk implemented correctly in modern groff? sobrado@ Tue, 19 Apr 2011 22:12:55 +0200 @@ -347,6 +353,10 @@ are mere guesses, and some may be wrong. reminded by jmc@ Thu, 23 Sep 2010 18:13:39 +0059 loc * exist ** algo *** size * imp *** +- a line starting with "\fB something" counts as starting with whitespace + and triggers a line break; found in audio/normalize-mp3(1) + loc ** exist * algo ** size * imp ** + - formatting /usr/local/man/man1/latex2man.1 with groff and mandoc reveals lots of bugs both in groff and mandoc... reported by bentley@ Wed, 22 May 2013 23:49:30 -0600 @@ -457,7 +467,7 @@ are mere guesses, and some may be wrong. loc * exist * algo * size * imp * - trailing whitespace must be ignored even when followed by a font escape, - see for example + see for example makes \fBdig \fR operate in batch mode @@ -531,7 +541,7 @@ are mere guesses, and some may be wrong. How does SQLITE_CONFIG_PAGECACHE actually work? Document it! from kristaps@ Sat, 09 Aug 2014 13:51:36 +0200 -Several areas can be cleaned up to make mandoc even faster. These are +Several areas can be cleaned up to make mandoc even faster. These are - improve hashing mechanism for macros (quite important: performance) @@ -540,7 +550,7 @@ Several areas can be cleaned up to make mandoc even faster. These are - the PDF file is HUGE: this can be reduced by using relative offsets - instead of re-initialising the roff predefined-strings set before each - parse, create a read-only version the first time and copy it + parse, create a read-only version the first time and copy it loc * exist ** algo ** size * imp ** ************************************************************************ @@ -556,7 +566,7 @@ Several areas can be cleaned up to make mandoc even faster. These are - Find better ways to prevent endless loops in roff(7) macro and string expansion. - + - Finish cleanup of date handling. Decide which formats should be recognized where. Update both mdoc(7) and man(7) documentation. diff --git a/contrib/mdocml/apropos.1 b/contrib/mdocml/apropos.1 index e2075349f553..532e4dd7ff74 100644 --- a/contrib/mdocml/apropos.1 +++ b/contrib/mdocml/apropos.1 @@ -1,4 +1,4 @@ -.\" $Id: apropos.1,v 1.36 2014/10/25 01:03:52 schwarze Exp $ +.\" $Id: apropos.1,v 1.37 2015/02/16 16:23:54 schwarze Exp $ .\" .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> .\" Copyright (c) 2011, 2012, 2014 Ingo Schwarze <schwarze@openbsd.org> @@ -15,7 +15,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: October 25 2014 $ +.Dd $Mdocdate: February 16 2015 $ .Dt APROPOS 1 .Os .Sh NAME @@ -24,7 +24,7 @@ .Nd search manual page databases .Sh SYNOPSIS .Nm -.Op Fl acfhklVw +.Op Fl acfhklw .Op Fl C Ar file .Op Fl M Ar path .Op Fl m Ar path @@ -162,8 +162,6 @@ By default, pages from all sections are shown. See .Xr man 1 for a listing of sections. -.It Fl V -Print version and exit. .It Fl w Instead of showing title lines, show the pathnames of the matching manual pages, just like diff --git a/contrib/mdocml/cgi.c b/contrib/mdocml/cgi.c index 65064ab2ad6c..05d1b8a0df01 100644 --- a/contrib/mdocml/cgi.c +++ b/contrib/mdocml/cgi.c @@ -1,4 +1,4 @@ -/* $Id: cgi.c,v 1.102 2014/11/26 17:55:27 schwarze Exp $ */ +/* $Id: cgi.c,v 1.104 2015/02/10 08:05:30 schwarze Exp $ */ /* * Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> * Copyright (c) 2014 Ingo Schwarze <schwarze@usta.de> @@ -58,10 +58,10 @@ static void catman(const struct req *, const char *); static void format(const struct req *, const char *); static void html_print(const char *); static void html_putchar(char); -static int http_decode(char *); +static int http_decode(char *); static void http_parse(struct req *, const char *); static void http_print(const char *); -static void http_putchar(char); +static void http_putchar(char); static void http_printquery(const struct req *, const char *); static void pathgen(struct req *); static void pg_error_badrequest(const char *); @@ -186,7 +186,7 @@ http_print(const char *p) static void html_print(const char *p) { - + if (NULL == p) return; while ('\0' != *p) @@ -621,7 +621,7 @@ pg_searchres(const struct req *req, struct manpage *r, size_t sz) for (i = 0; i < sz; i++) { printf("<TR>\n" "<TD CLASS=\"title\">\n" - "<A HREF=\"%s/%s/%s?", + "<A HREF=\"%s/%s/%s?", scriptname, req->q.manpath, r[i].file); http_printquery(req, "&"); printf("\">"); @@ -701,7 +701,7 @@ catman(const struct req *req, const char *file) while (NULL != (p = fgetln(f, &len))) { bold = italic = 0; for (i = 0; i < (int)len - 1; i++) { - /* + /* * This means that the catpage is out of state. * Ignore it and keep going (although the * catpage is bogus). @@ -742,7 +742,7 @@ catman(const struct req *req, const char *file) continue; } - /* + /* * Handle funny behaviour troff-isms. * These grok'd from the original man2html.c. */ @@ -780,7 +780,7 @@ catman(const struct req *req, const char *file) } /* Bold mode. */ - + if (italic) printf("</I>"); if ( ! bold) @@ -791,9 +791,9 @@ catman(const struct req *req, const char *file) html_putchar(p[i]); } - /* + /* * Clean up the last character. - * We can get to a newline; don't print that. + * We can get to a newline; don't print that. */ if (italic) @@ -822,7 +822,6 @@ format(const struct req *req, const char *file) struct man *man; void *vp; char *opts; - enum mandoclevel rc; int fd; int usepath; @@ -832,18 +831,11 @@ format(const struct req *req, const char *file) } mchars = mchars_alloc(); - mp = mparse_alloc(MPARSE_SO, MANDOCLEVEL_FATAL, NULL, + mp = mparse_alloc(MPARSE_SO, MANDOCLEVEL_BADARG, NULL, mchars, req->q.manpath); - rc = mparse_readfd(mp, fd, file); + mparse_readfd(mp, fd, file); close(fd); - if (rc >= MANDOCLEVEL_FATAL) { - fprintf(stderr, "fatal mandoc error: %s/%s\n", - req->q.manpath, file); - pg_error_internal(); - return; - } - usepath = strcmp(req->q.manpath, req->p[0]); mandoc_asprintf(&opts, "fragment,man=%s?query=%%N&sec=%%S%s%s%s%s", @@ -899,7 +891,7 @@ pg_show(struct req *req, const char *fullpath) pg_error_badrequest( "You did not specify a page to show."); return; - } + } manpath = mandoc_strndup(fullpath, file - fullpath); file++; @@ -1064,7 +1056,7 @@ main(void) MAN_DIR, strerror(errno)); pg_error_internal(); return(EXIT_FAILURE); - } + } memset(&req, 0, sizeof(struct req)); pathgen(&req); diff --git a/contrib/mdocml/chars.c b/contrib/mdocml/chars.c index fe0b17dea823..6b5eba953728 100644 --- a/contrib/mdocml/chars.c +++ b/contrib/mdocml/chars.c @@ -1,4 +1,4 @@ -/* $Id: chars.c,v 1.65 2014/10/29 00:17:43 schwarze Exp $ */ +/* $Id: chars.c,v 1.66 2015/02/17 20:37:16 schwarze Exp $ */ /* * Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> * Copyright (c) 2011, 2014 Ingo Schwarze <schwarze@openbsd.org> @@ -38,7 +38,7 @@ struct ln { int unicode; }; -#define LINES_MAX 330 +#define LINES_MAX 332 #define CHAR(in, ch, code) \ { NULL, (in), (ch), (code) }, diff --git a/contrib/mdocml/chars.in b/contrib/mdocml/chars.in index 752015c1b6d4..ac72aba8588c 100644 --- a/contrib/mdocml/chars.in +++ b/contrib/mdocml/chars.in @@ -1,4 +1,4 @@ -/* $Id: chars.in,v 1.49 2014/11/06 22:28:36 schwarze Exp $ */ +/* $Id: chars.in,v 1.52 2015/02/17 20:37:16 schwarze Exp $ */ /* * Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> * Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org> @@ -70,8 +70,10 @@ CHAR("ti", "~", 126) /* Quotes. */ CHAR("Bq", ",,", 8222) CHAR("bq", ",", 8218) -CHAR("lq", "``", 8220) -CHAR("rq", "\'\'", 8221) +CHAR("lq", "\"", 8220) +CHAR("rq", "\"", 8221) +CHAR("Lq", "``", 8220) +CHAR("Rq", "''", 8221) CHAR("oq", "`", 8216) CHAR("cq", "\'", 8217) CHAR("aq", "\'", 39) @@ -91,30 +93,30 @@ CHAR("ra", ">", 10217) CHAR("bv", "|", 9130) CHAR("braceex", "|", 9130) CHAR("bracketlefttp", "|", 9121) -CHAR("bracketleftbp", "|", 9123) +CHAR("bracketleftbt", "|", 9123) CHAR("bracketleftex", "|", 9122) CHAR("bracketrighttp", "|", 9124) -CHAR("bracketrightbp", "|", 9126) +CHAR("bracketrightbt", "|", 9126) CHAR("bracketrightex", "|", 9125) CHAR("lt", ",-", 9127) CHAR("bracelefttp", ",-", 9127) CHAR("lk", "{", 9128) CHAR("braceleftmid", "{", 9128) CHAR("lb", "`-", 9129) -CHAR("braceleftbp", "`-", 9129) +CHAR("braceleftbt", "`-", 9129) CHAR("braceleftex", "|", 9130) CHAR("rt", "-.", 9131) CHAR("bracerighttp", "-.", 9131) CHAR("rk", "}", 9132) CHAR("bracerightmid", "}", 9132) CHAR("rb", "-\'", 9133) -CHAR("bracerightbp", "-\'", 9133) +CHAR("bracerightbt", "-\'", 9133) CHAR("bracerightex", "|", 9130) CHAR("parenlefttp", "/", 9115) -CHAR("parenleftbp", "\\", 9117) +CHAR("parenleftbt", "\\", 9117) CHAR("parenleftex", "|", 9116) CHAR("parenrighttp", "\\", 9118) -CHAR("parenrightbp", "/", 9120) +CHAR("parenrightbt", "/", 9120) CHAR("parenrightex", "|", 9119) /* Greek characters. */ @@ -281,10 +283,10 @@ CHAR("!=", "!=", 8800) CHAR("==", "==", 8801) CHAR("ne", "!==", 8802) CHAR("=~", "=~", 8773) -CHAR("-~", "-~", 8771) +CHAR("|=", "-~", 8771) CHAR("ap", "~", 8764) CHAR("~~", "~~", 8776) -CHAR("~=", "~=", 8780) +CHAR("~=", "~=", 8776) CHAR("pt", "oc", 8733) CHAR("es", "{}", 8709) CHAR("mo", "E", 8712) @@ -357,7 +359,7 @@ CHAR("Fn", ",\bf", 402) CHAR("ba", "|", 124) CHAR("br", "|", 9474) CHAR("ul", "_", 95) -CHAR("rl", "-", 8254) +CHAR("rn", "-", 8254) CHAR("bb", "|", 166) CHAR("sl", "/", 47) CHAR("rs", "\\", 92) diff --git a/contrib/mdocml/compat_fts.c b/contrib/mdocml/compat_fts.c index d6e99e611aa8..194c56552460 100644 --- a/contrib/mdocml/compat_fts.c +++ b/contrib/mdocml/compat_fts.c @@ -6,8 +6,8 @@ int dummy; #else -/* $Id: compat_fts.c,v 1.6 2014/12/11 18:20:07 schwarze Exp $ */ -/* $OpenBSD: fts.c,v 1.49 2014/11/23 00:14:22 guenther Exp $ */ +/* $Id: compat_fts.c,v 1.8 2015/02/07 07:53:01 schwarze Exp $ */ +/* $OpenBSD: fts.c,v 1.50 2015/01/16 16:48:51 deraadt Exp $ */ /*- * Copyright (c) 1990, 1993, 1994 @@ -38,7 +38,6 @@ int dummy; * SUCH DAMAGE. */ -#include <sys/param.h> #include <sys/stat.h> #include <sys/types.h> @@ -51,6 +50,8 @@ int dummy; #include <unistd.h> #include "compat_fts.h" +#define MAXIMUM(a, b) (((a) > (b)) ? (a) : (b)) + static FTSENT *fts_alloc(FTS *, const char *, size_t); static FTSENT *fts_build(FTS *); static void fts_lfree(FTSENT *); @@ -62,10 +63,12 @@ static unsigned short fts_stat(FTS *, FTSENT *); static int fts_safe_changedir(FTS *, FTSENT *, int, const char *); #define ISDOT(a) (a[0] == '.' && (!a[1] || (a[1] == '.' && !a[2]))) -#define MAX(a,b) (((a)>(b))?(a):(b)) #ifndef O_DIRECTORY #define O_DIRECTORY 0 #endif +#ifndef O_CLOEXEC +#define O_CLOEXEC 0 +#endif #define CLR(opt) (sp->fts_options &= ~(opt)) #define ISSET(opt) (sp->fts_options & (opt)) @@ -97,7 +100,7 @@ fts_open(char * const *argv, int options, void *dummy) * Start out with 1K of path space, and enough, in any case, * to hold the user's paths. */ - if (fts_palloc(sp, MAX(fts_maxarglen(argv), PATH_MAX))) + if (fts_palloc(sp, MAXIMUM(fts_maxarglen(argv), PATH_MAX))) goto mem1; /* Allocate/initialize root's parent. */ diff --git a/contrib/mdocml/compat_strtonum.c b/contrib/mdocml/compat_strtonum.c new file mode 100644 index 000000000000..628e5d51b86b --- /dev/null +++ b/contrib/mdocml/compat_strtonum.c @@ -0,0 +1,76 @@ +#include "config.h" + +#if HAVE_STRTONUM + +int dummy; + +#else + +/* $Id: compat_strtonum.c,v 1.1 2015/02/16 14:56:22 schwarze Exp $ */ +/* $OpenBSD: strtonum.c,v 1.7 2013/04/17 18:40:58 tedu Exp $ */ + +/* + * Copyright (c) 2004 Ted Unangst and Todd Miller + * All rights reserved. + * + * Permission to use, copy, modify, and distribute this software for any + * purpose with or without fee is hereby granted, provided that the above + * copyright notice and this permission notice appear in all copies. + * + * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + */ + +#include <errno.h> +#include <limits.h> +#include <stdlib.h> + +#define INVALID 1 +#define TOOSMALL 2 +#define TOOLARGE 3 + +long long +strtonum(const char *numstr, long long minval, long long maxval, + const char **errstrp) +{ + long long ll = 0; + int error = 0; + char *ep; + struct errval { + const char *errstr; + int err; + } ev[4] = { + { NULL, 0 }, + { "invalid", EINVAL }, + { "too small", ERANGE }, + { "too large", ERANGE }, + }; + + ev[0].err = errno; + errno = 0; + if (minval > maxval) { + error = INVALID; + } else { + ll = strtoll(numstr, &ep, 10); + if (numstr == ep || *ep != '\0') + error = INVALID; + else if ((ll == LLONG_MIN && errno == ERANGE) || ll < minval) + error = TOOSMALL; + else if ((ll == LLONG_MAX && errno == ERANGE) || ll > maxval) + error = TOOLARGE; + } + if (errstrp != NULL) + *errstrp = ev[error].errstr; + errno = ev[error].err; + if (error) + ll = 0; + + return (ll); +} + +#endif /* !HAVE_STRTONUM */ diff --git a/contrib/mdocml/config.h b/contrib/mdocml/config.h index bc16d92ad922..6123a9a418c5 100644 --- a/contrib/mdocml/config.h +++ b/contrib/mdocml/config.h @@ -19,6 +19,7 @@ #define HAVE_STRLCPY 1 #define HAVE_STRPTIME 1 #define HAVE_STRSEP 1 +#define HAVE_STRTONUM 1 #define HAVE_WCHAR 1 #define HAVE_SQLITE3 1 #define HAVE_SQLITE3_ERRSTR 0 diff --git a/contrib/mdocml/configure b/contrib/mdocml/configure index 57ac898f248c..000d11ecc4cd 100755 --- a/contrib/mdocml/configure +++ b/contrib/mdocml/configure @@ -1,6 +1,6 @@ #!/bin/sh # -# Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org> +# Copyright (c) 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> # # Permission to use, copy, modify, and distribute this software for any # purpose with or without fee is hereby granted, provided that the above @@ -31,10 +31,6 @@ echo "config.log: writing..." # Initialize all variables here, # such that nothing can leak in from the environment. -VERSION="1.13.2" -echo "VERSION=\"${VERSION}\"" 1>&2 -echo "VERSION=\"${VERSION}\"" 1>&3 - OSNAME= CC=`printf "all:\\n\\t@echo \\\$(CC)\\n" | make -f -` @@ -56,6 +52,7 @@ HAVE_STRLCAT= HAVE_STRLCPY= HAVE_STRPTIME= HAVE_STRSEP= +HAVE_STRTONUM= HAVE_WCHAR= HAVE_SQLITE3= @@ -70,6 +67,7 @@ INCLUDEDIR= LIBDIR= MANDIR= EXAMPLEDIR= +HOMEBREWDIR= WWWPREFIX="/var/www" HTDOCDIR= @@ -176,6 +174,7 @@ runtest strlcat STRLCAT || true runtest strlcpy STRLCPY || true runtest strptime STRPTIME || true runtest strsep STRSEP || true +runtest strtonum STRTONUM || true runtest wchar WCHAR || true # --- sqlite3 --- @@ -274,8 +273,8 @@ __HEREDOC__ [ ${HAVE_FGETLN} -eq 0 ] && echo "#include <stdio.h>" echo -echo "#define VERSION \"${VERSION}\"" [ -n "${OSNAME}" ] && echo "#define OSNAME \"${OSNAME}\"" +[ -n "${HOMEBREWDIR}" ] && echo "#define HOMEBREWDIR \"${HOMEBREWDIR}\"" cat << __HEREDOC__ #define HAVE_DIRENT_NAMLEN ${HAVE_DIRENT_NAMLEN} @@ -289,6 +288,7 @@ cat << __HEREDOC__ #define HAVE_STRLCPY ${HAVE_STRLCPY} #define HAVE_STRPTIME ${HAVE_STRPTIME} #define HAVE_STRSEP ${HAVE_STRSEP} +#define HAVE_STRTONUM ${HAVE_STRTONUM} #define HAVE_WCHAR ${HAVE_WCHAR} #define HAVE_SQLITE3 ${HAVE_SQLITE3} #define HAVE_SQLITE3_ERRSTR ${HAVE_SQLITE3_ERRSTR} @@ -341,6 +341,9 @@ __HEREDOC__ [ ${HAVE_STRSEP} -eq 0 ] && \ echo "extern char *strsep(char **, const char *);" +[ ${HAVE_STRTONUM} -eq 0 ] && \ + echo "extern long long strtonum(const char *, long long, long long, const char **);" + echo echo "#endif /* MANDOC_CONFIG_H */" @@ -379,7 +382,6 @@ INSTALL_TARGETS="base-install" [ ${BUILD_CGI} -gt 0 ] && INSTALL_TARGETS="${INSTALL_TARGETS} cgi-install" cat << __HEREDOC__ -VERSION = ${VERSION} BUILD_TARGETS = ${BUILD_TARGETS} INSTALL_TARGETS = ${INSTALL_TARGETS} CFLAGS = ${CFLAGS} diff --git a/contrib/mdocml/configure.local.example b/contrib/mdocml/configure.local.example index 037d48a48f99..bb391591cf5d 100644 --- a/contrib/mdocml/configure.local.example +++ b/contrib/mdocml/configure.local.example @@ -1,6 +1,6 @@ -# $Id: configure.local.example,v 1.2 2014/12/09 09:14:33 schwarze Exp $ +# $Id: configure.local.example,v 1.6 2015/02/16 14:56:22 schwarze Exp $ # -# Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org> +# Copyright (c) 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> # # Permission to use, copy, modify, and distribute this software for any # purpose with or without fee is hereby granted, provided that the above @@ -74,6 +74,21 @@ LIBDIR="${PREFIX}/lib/mandoc" MANDIR="${PREFIX}/man" EXAMPLEDIR="${PREFIX}/share/examples/mandoc" +# The man(1) utility needs to know where the manuals reside. +# We know of two ways to tell it: via manpath(1) or man.conf(5). +# The latter is used by OpenBSD and NetBSD, the former by most +# other systems. + +# Force usage of manpath(1). +# If it is not installed or not operational, +# man(1), makewhatis(8), and apropos(1) will not work properly. +HAVE_MANPATH=1 + +# Force usage of man.conf(5). +# If it does not exist or contains no valid configuration, +# man(1), makewhatis(8), and apropos(1) will not work properly. +HAVE_MANPATH=0 + # Some distributions may want to avoid naming conflicts among manuals. # If you want to change the names of installed section 7 manual pages, # the following alternative names are suggested. @@ -87,6 +102,15 @@ MANM_ROFF="mandoc_roff" # default is "roff" MANM_EQN="mandoc_eqn" # default is "eqn" MANM_TBL="mandoc_tbl" # default is "tbl" +# Some distributions may want to avoid naming conflicts +# with another man(1) utility. +# If you want to change the name of the binary program, +# the following alternative name is suggested. +# Using a different name is possible as well. +# This changes the name of the installed section 1 manual page as well. + +BINM_MAN=mman # default is "man" + # It is possible to change the utility program used for installation # and the modes files are installed with. The defaults are: @@ -121,38 +145,29 @@ DBLIB="-L/usr/local/lib -lsqlite3" CFLAGS="${CFLAGS} -I/usr/local/include" -# The man(1) utility needs to know where the manuals reside. -# We know of two ways to tell it: via manpath(1) or man.conf(5). -# The latter is used by OpenBSD and NetBSD, the former by most -# other systems. - -# Force usage of manpath(1). -# If it is not installed or not operational, -# makewhatis(8) and apropos(1) will not work properly. - -HAVE_MANPATH=1 - -# Force usage of man.conf(5). -# If it does not exist or contains no valid configuration, -# makewhatis(8) and apropos(1) will not work properly. - -HAVE_MANPATH=0 - # Some distributions may want to avoid naming conflicts -# with groff, man-db, or other tools. -# If you want to change the names of binary programs, +# with another implementation of apropos(1) and makewhatis(8). +# If you want to change the names of the binary programs, # the following alternative names are suggested. # Using other names is possible as well. # This changes the names of the installed section 1 and section 8 # manual pages as well. -# It is possible to set only one or a few of these variables, +# It is possible to set only one or two of these variables, # there is no need to copy the whole block. BINM_APROPOS=mapropos # default is "apropos" -BINM_MAN=mman # default is "man" BINM_WHATIS=mwhatis # default is "whatis" BINM_MAKEWHATIS=mandocdb # default is "makewhatis" +# When using the "homebrew" package manager on Mac OS X, the actual +# manuals are located in a so-called "cellar" and only symlinked +# into the manual trees. To allow mandoc to follow such symlinks, +# you have to specify the physical location of the cellar as returned +# by realpath(3), for example: + +PREFIX="/usr/local" +HOMEBREWDIR="${PREFIX}/Cellar" + # --- user settings related man.cgi ------------------------------------ # By default, building man.cgi(8) is disabled. To enable it, copy @@ -211,6 +226,7 @@ HAVE_STRLCAT=0 HAVE_STRLCPY=0 HAVE_STRPTIME=0 HAVE_STRSEP=0 +HAVE_STRTONUM=0 HAVE_SQLITE3=0 HAVE_SQLITE3_ERRSTR=0 diff --git a/contrib/mdocml/demandoc.c b/contrib/mdocml/demandoc.c index e9aa62afb2ba..f515931d8b91 100644 --- a/contrib/mdocml/demandoc.c +++ b/contrib/mdocml/demandoc.c @@ -1,4 +1,4 @@ -/* $Id: demandoc.c,v 1.12 2014/10/28 17:36:19 schwarze Exp $ */ +/* $Id: demandoc.c,v 1.15 2015/02/10 08:05:30 schwarze Exp $ */ /* * Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv> * @@ -44,11 +44,12 @@ main(int argc, char *argv[]) { struct mparse *mp; struct mchars *mchars; - int ch, i, list; + int ch, fd, i, list; extern int optind; - progname = strrchr(argv[0], '/'); - if (progname == NULL) + if (argc < 1) + progname = "demandoc"; + else if ((progname = strrchr(argv[0], '/')) == NULL) progname = argv[0]; else ++progname; @@ -78,15 +79,19 @@ main(int argc, char *argv[]) argv += optind; mchars = mchars_alloc(); - mp = mparse_alloc(MPARSE_SO, MANDOCLEVEL_FATAL, NULL, mchars, NULL); + mp = mparse_alloc(MPARSE_SO, MANDOCLEVEL_BADARG, NULL, mchars, NULL); assert(mp); - if (0 == argc) + if (argc < 1) pmandoc(mp, STDIN_FILENO, "<stdin>", list); for (i = 0; i < argc; i++) { mparse_reset(mp); - pmandoc(mp, -1, argv[i], list); + if (mparse_open(mp, &fd, argv[i]) != MANDOCLEVEL_OK) { + perror(argv[i]); + continue; + } + pmandoc(mp, fd, argv[i], list); } mparse_free(mp); @@ -108,16 +113,12 @@ pmandoc(struct mparse *mp, int fd, const char *fn, int list) struct man *man; int line, col; - if (mparse_readfd(mp, fd, fn) >= MANDOCLEVEL_FATAL) { - fprintf(stderr, "%s: Parse failure\n", fn); - return; - } - + mparse_readfd(mp, fd, fn); mparse_result(mp, &mdoc, &man, NULL); line = 1; col = 0; - if (mdoc) + if (mdoc) pmdoc(mdoc_node(mdoc), &line, &col, list); else if (man) pman(man_node(man), &line, &col, list); @@ -167,7 +168,7 @@ again: end = p - 1; while (end > start) - if ('.' == *end || ',' == *end || + if ('.' == *end || ',' == *end || '\'' == *end || '"' == *end || ')' == *end || '!' == *end || '?' == *end || ':' == *end || @@ -199,7 +200,7 @@ again: /* * Print the input word, skipping any special characters. */ - while ('\0' != *p) + while ('\0' != *p) if ('\\' == *p) { p++; esc = mandoc_escape(&p, NULL, NULL); @@ -220,7 +221,7 @@ pline(int line, int *linep, int *col, int list) /* * Print out as many lines as needed to reach parity with the - * original input. + * original input. */ while (*linep < line) { @@ -240,7 +241,7 @@ pmdoc(const struct mdoc_node *p, int *line, int *col, int list) pline(p->line, line, col, list); if (MDOC_TEXT == p->type) pstring(p->string, p->pos, col, list); - if (p->child) + if (p->child) pmdoc(p->child, line, col, list); } } @@ -254,7 +255,7 @@ pman(const struct man_node *p, int *line, int *col, int list) pline(p->line, line, col, list); if (MAN_TEXT == p->type) pstring(p->string, p->pos, col, list); - if (p->child) + if (p->child) pman(p->child, line, col, list); } } diff --git a/contrib/mdocml/eqn.7 b/contrib/mdocml/eqn.7 index c1e9c7634d4a..182fd4cfd719 100644 --- a/contrib/mdocml/eqn.7 +++ b/contrib/mdocml/eqn.7 @@ -1,4 +1,4 @@ -.\" $Id: eqn.7,v 1.31 2014/10/12 11:57:38 schwarze Exp $ +.\" $Id: eqn.7,v 1.33 2015/01/29 00:33:57 schwarze Exp $ .\" .\" Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv> .\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org> @@ -15,7 +15,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: October 12 2014 $ +.Dd $Mdocdate: January 29 2015 $ .Dt EQN 7 .Os .Sh NAME @@ -122,7 +122,7 @@ lambda, mu, nu, omega, omicron, phi, pi, psi, rho, sigma, tau, theta, upsilon, xi, zeta, DELTA, GAMMA, LAMBDA, OMEGA, PHI, PI, PSI, SIGMA, THETA, UPSILON, XI, inter (intersection), union (union), prod (product), int (integral), sum (summation), grad (gradient), del (vector -differential), times (multiply), cdot (centre-dot), nothing (zero-width +differential), times (multiply), cdot (center-dot), nothing (zero-width space), approx (approximately equals), prime (prime), half (one-half), partial (partial differential), inf (infinity), >> (much greater), << (much less), \-> (left arrow), <\- (right arrow), +\- (plus-minus), != @@ -457,11 +457,6 @@ The and .Cm down Ar n commands are also ignored. -.It -Inline equations and the -.Cm delim -control statement are not yet implemented in -.Xr mandoc 1 . .El .Sh SEE ALSO .Xr mandoc 1 , diff --git a/contrib/mdocml/eqn.c b/contrib/mdocml/eqn.c index a64031b29b9c..8737c6620f15 100644 --- a/contrib/mdocml/eqn.c +++ b/contrib/mdocml/eqn.c @@ -1,7 +1,7 @@ -/* $Id: eqn.c,v 1.56 2014/10/25 15:06:30 schwarze Exp $ */ +/* $Id: eqn.c,v 1.57 2015/01/28 21:11:53 schwarze Exp $ */ /* * Copyright (c) 2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -31,8 +31,6 @@ #include "libmandoc.h" #include "libroff.h" -#define EQN_MSG(t, x) \ - mandoc_msg((t), (x)->parse, (x)->eqn.ln, (x)->eqn.pos, NULL) #define EQN_NEST_MAX 128 /* maximum nesting of defines */ #define STRNEQ(p1, sz1, p2, sz2) \ ((sz1) == (sz2) && 0 == strncmp((p1), (p2), (sz1))) @@ -266,6 +264,21 @@ static const struct eqnsym eqnsyms[EQNSYM__MAX] = { { ">=", ">=" }, /* EQNSYM_moreequal */ }; +static struct eqn_box *eqn_box_alloc(struct eqn_node *, struct eqn_box *); +static void eqn_box_free(struct eqn_box *); +static struct eqn_box *eqn_box_makebinary(struct eqn_node *, + enum eqn_post, struct eqn_box *); +static void eqn_def(struct eqn_node *); +static struct eqn_def *eqn_def_find(struct eqn_node *, const char *, size_t); +static void eqn_delim(struct eqn_node *); +static const char *eqn_next(struct eqn_node *, char, size_t *, int); +static const char *eqn_nextrawtok(struct eqn_node *, size_t *); +static const char *eqn_nexttok(struct eqn_node *, size_t *); +static enum rofferr eqn_parse(struct eqn_node *, struct eqn_box *); +static enum eqn_tok eqn_tok_parse(struct eqn_node *, char **); +static void eqn_undef(struct eqn_node *); + + enum rofferr eqn_read(struct eqn_node **epp, int ln, const char *p, int pos, int *offs) @@ -365,7 +378,8 @@ again: /* Prevent self-definitions. */ if (lim >= EQN_NEST_MAX) { - EQN_MSG(MANDOCERR_ROFFLOOP, ep); + mandoc_msg(MANDOCERR_ROFFLOOP, ep->parse, + ep->eqn.ln, ep->eqn.pos, NULL); return(NULL); } @@ -406,7 +420,8 @@ again: ep->cur++; } else { if (q) - EQN_MSG(MANDOCERR_ARG_QUOTE, ep); + mandoc_msg(MANDOCERR_ARG_QUOTE, ep->parse, + ep->eqn.ln, ep->eqn.pos, NULL); next = strchr(start, '\0'); *sz = (size_t)(next - start); ep->cur += *sz; @@ -600,23 +615,27 @@ eqn_delim(struct eqn_node *ep) /* * Undefine a previously-defined string. */ -static int +static void eqn_undef(struct eqn_node *ep) { const char *start; struct eqn_def *def; size_t sz; - if (NULL == (start = eqn_nextrawtok(ep, &sz))) { - EQN_MSG(MANDOCERR_EQNEOF, ep); - return(0); - } else if (NULL != (def = eqn_def_find(ep, start, sz))) - def->keysz = 0; - - return(1); + if ((start = eqn_nextrawtok(ep, &sz)) == NULL) { + mandoc_msg(MANDOCERR_REQ_EMPTY, ep->parse, + ep->eqn.ln, ep->eqn.pos, "undef"); + return; + } + if ((def = eqn_def_find(ep, start, sz)) == NULL) + return; + free(def->key); + free(def->val); + def->key = def->val = NULL; + def->keysz = def->valsz = 0; } -static int +static void eqn_def(struct eqn_node *ep) { const char *start; @@ -624,9 +643,10 @@ eqn_def(struct eqn_node *ep) struct eqn_def *def; int i; - if (NULL == (start = eqn_nextrawtok(ep, &sz))) { - EQN_MSG(MANDOCERR_EQNEOF, ep); - return(0); + if ((start = eqn_nextrawtok(ep, &sz)) == NULL) { + mandoc_msg(MANDOCERR_REQ_EMPTY, ep->parse, + ep->eqn.ln, ep->eqn.pos, "define"); + return; } /* @@ -646,47 +666,51 @@ eqn_def(struct eqn_node *ep) ep->defs[i].key = ep->defs[i].val = NULL; } - ep->defs[i].keysz = sz; - ep->defs[i].key = mandoc_realloc( - ep->defs[i].key, sz + 1); - - memcpy(ep->defs[i].key, start, sz); - ep->defs[i].key[(int)sz] = '\0'; - def = &ep->defs[i]; + def = ep->defs + i; + free(def->key); + def->key = mandoc_strndup(start, sz); + def->keysz = sz; } start = eqn_next(ep, ep->data[(int)ep->cur], &sz, 0); - - if (NULL == start) { - EQN_MSG(MANDOCERR_EQNEOF, ep); - return(-1); + if (start == NULL) { + mandoc_vmsg(MANDOCERR_REQ_EMPTY, ep->parse, + ep->eqn.ln, ep->eqn.pos, "define %s", def->key); + free(def->key); + free(def->val); + def->key = def->val = NULL; + def->keysz = def->valsz = 0; + return; } - + free(def->val); + def->val = mandoc_strndup(start, sz); def->valsz = sz; - def->val = mandoc_realloc(def->val, sz + 1); - memcpy(def->val, start, sz); - def->val[(int)sz] = '\0'; - return(1); } /* * Recursively parse an eqn(7) expression. */ -static int +static enum rofferr eqn_parse(struct eqn_node *ep, struct eqn_box *parent) { + char sym[64]; + struct eqn_box *cur; + const char *start; char *p; + size_t i, sz; enum eqn_tok tok, subtok; enum eqn_post pos; - struct eqn_box *cur; - int rc, size; - size_t i, sz; - char sym[64]; - const char *start; + int size; assert(parent != NULL); + + /* + * Empty equation. + * Do not add it to the high-level syntax tree. + */ + if (ep->data == NULL) - return(-1); + return(ROFF_IGN); next_tok: tok = eqn_tok_parse(ep, &p); @@ -694,20 +718,17 @@ next_tok: this_tok: switch (tok) { case (EQN_TOK_UNDEF): - if ((rc = eqn_undef(ep)) <= 0) - return(rc); + eqn_undef(ep); break; case (EQN_TOK_NDEFINE): case (EQN_TOK_DEFINE): - if ((rc = eqn_def(ep)) <= 0) - return(rc); + eqn_def(ep); break; case (EQN_TOK_TDEFINE): - if (NULL == eqn_nextrawtok(ep, NULL)) - EQN_MSG(MANDOCERR_EQNEOF, ep); - else if (NULL == eqn_next(ep, - ep->data[(int)ep->cur], NULL, 0)) - EQN_MSG(MANDOCERR_EQNEOF, ep); + if (eqn_nextrawtok(ep, NULL) == NULL || + eqn_next(ep, ep->data[(int)ep->cur], NULL, 0) == NULL) + mandoc_msg(MANDOCERR_REQ_EMPTY, ep->parse, + ep->eqn.ln, ep->eqn.pos, "tdefine"); break; case (EQN_TOK_DELIM): eqn_delim(ep); @@ -1037,7 +1058,7 @@ this_tok: * End of file! * TODO: make sure we're not in an open subexpression. */ - return(0); + return(ROFF_EQN); default: assert(tok == EQN_TOK__MAX); assert(NULL != p); @@ -1081,7 +1102,7 @@ eqn_end(struct eqn_node **epp) ep->eqn.root = mandoc_calloc(1, sizeof(struct eqn_box)); ep->eqn.root->expectargs = UINT_MAX; - return(0 == eqn_parse(ep, ep->eqn.root) ? ROFF_EQN : ROFF_IGN); + return(eqn_parse(ep, ep->eqn.root)); } void diff --git a/contrib/mdocml/eqn_term.c b/contrib/mdocml/eqn_term.c index 010a152e2567..5f2818b4052b 100644 --- a/contrib/mdocml/eqn_term.c +++ b/contrib/mdocml/eqn_term.c @@ -1,7 +1,7 @@ -/* $Id: eqn_term.c,v 1.7 2014/10/12 14:49:39 schwarze Exp $ */ +/* $Id: eqn_term.c,v 1.8 2015/01/01 15:36:08 schwarze Exp $ */ /* * Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -79,14 +79,17 @@ eqn_box(struct termp *p, const struct eqn_box *bp) bp->pos == EQNPOS_TO) ? "^" : "_"); p->flags |= TERMP_NOSPACE; child = child->next; - eqn_box(p, child); - if (bp->pos == EQNPOS_FROMTO || - bp->pos == EQNPOS_SUBSUP) { - p->flags |= TERMP_NOSPACE; - term_word(p, "^"); - p->flags |= TERMP_NOSPACE; - child = child->next; + if (child != NULL) { eqn_box(p, child); + if (bp->pos == EQNPOS_FROMTO || + bp->pos == EQNPOS_SUBSUP) { + p->flags |= TERMP_NOSPACE; + term_word(p, "^"); + p->flags |= TERMP_NOSPACE; + child = child->next; + if (child != NULL) + eqn_box(p, child); + } } } else { child = bp->first; diff --git a/contrib/mdocml/example.style.css b/contrib/mdocml/example.style.css index 905412b52d31..90eb4a274f2e 100644 --- a/contrib/mdocml/example.style.css +++ b/contrib/mdocml/example.style.css @@ -1,4 +1,4 @@ -/* $Id: example.style.css,v 1.54 2014/12/10 22:19:45 schwarze Exp $ */ +/* $Id: example.style.css,v 1.55 2015/02/10 08:05:30 schwarze Exp $ */ /* * This is an example style-sheet provided for mandoc(1) and the -Thtml * or -Txhtml output mode. @@ -6,8 +6,8 @@ * See mdoc(7) and man(7) for macro explanations. */ -div.mandoc { min-width: 102ex; - width: 102ex; +div.mandoc { min-width: 102ex; + width: 102ex; font-family: monospace; } /* This is the outer node of all mandoc -T[x]html documents. */ div.mandoc h1 { margin-bottom: 0ex; font-size: inherit; margin-left: -4ex; } /* Section header (Sh, SH). */ div.mandoc h2 { margin-bottom: 0ex; font-size: inherit; margin-left: -2ex; } /* Sub-section header (Ss, SS). */ @@ -39,7 +39,7 @@ div.mandoc .lit { font-style: normal; font-weight: normal; font-family: monosp div.mandoc i.addr { font-weight: normal; } /* Address (Ad). */ div.mandoc i.arg { font-weight: normal; } /* Command argument (Ar). */ div.mandoc span.author { } /* Author name (An). */ -div.mandoc b.cmd { font-style: normal; } /* Command (Cm). */ +div.mandoc b.cmd { font-style: normal; } /* Command (Cm). */ div.mandoc b.config { font-style: normal; } /* Config statement (Cd). */ div.mandoc span.define { } /* Defines (Dv). */ div.mandoc span.desc { } /* Nd. After em-dash. */ diff --git a/contrib/mdocml/gmdiff b/contrib/mdocml/gmdiff index 2c7ba4b343ca..ae27726ee525 100644 --- a/contrib/mdocml/gmdiff +++ b/contrib/mdocml/gmdiff @@ -19,20 +19,32 @@ if [ `id -u` -eq 0 ]; then fi if [ $# -eq 0 ]; then - echo "usage: $0 manual_source_file ..." + echo "usage: $0 -h manual_source_file ..." exit 1 fi +if [ "X$1" = "X-h" ]; then + shift + export PATH="/usr/local/heirloom-doctools/bin:$PATH" + EQN="neqn" + ROFF="nroff" + MOPT="-Omdoc $MOPT" +else + EQN="eqn -Tascii" + ROFF="groff -ww -Tascii -P -c" +fi +MOPT="-Werror $MOPT" + while [ -n "$1" ]; do file=$1 shift echo " ========== $file ========== " - tbl $file | groff -mandoc -Tascii -P -c 2> /tmp/groff.err > /tmp/groff.out - mandoc -Ios='OpenBSD ports' -Werror $file 2> /tmp/mandoc.err > /tmp/mandoc.out - for i in groff mandoc; do + tbl $file | $EQN | $ROFF -mandoc 2> /tmp/roff.err > /tmp/roff.out + mandoc -Ios='OpenBSD ports' $MOPT $file 2> /tmp/mandoc.err > /tmp/mandoc.out + for i in roff mandoc; do [[ -s /tmp/$i.err ]] && echo "$i errors:" && cat /tmp/$i.err done - diff -au /tmp/groff.out /tmp/mandoc.out 2>&1 + diff -au /tmp/roff.out /tmp/mandoc.out 2>&1 done exit 0 diff --git a/contrib/mdocml/html.c b/contrib/mdocml/html.c index fe16224e8e36..487dacda947f 100644 --- a/contrib/mdocml/html.c +++ b/contrib/mdocml/html.c @@ -1,7 +1,7 @@ -/* $Id: html.c,v 1.183 2014/12/02 10:08:06 schwarze Exp $ */ +/* $Id: html.c,v 1.185 2015/01/21 20:33:25 schwarze Exp $ */ /* * Copyright (c) 2008-2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2011, 2012, 2013, 2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2011-2015 Ingo Schwarze <schwarze@openbsd.org> * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -121,7 +121,7 @@ static const char *const roffscales[SCALE_MAX] = { }; static void bufncat(struct html *, const char *, size_t); -static void print_ctag(struct html *, enum htmltag); +static void print_ctag(struct html *, struct tag *); static int print_escape(char); static int print_encode(struct html *, const char *, int); static void print_metaf(struct html *, enum mandoc_esc); @@ -307,6 +307,8 @@ html_strlen(const char *cp) case ESCAPE_NUMBERED: /* FALLTHROUGH */ case ESCAPE_SPECIAL: + /* FALLTHROUGH */ + case ESCAPE_OVERSTRIKE: if (skip) skip = 0; else @@ -433,6 +435,11 @@ print_encode(struct html *h, const char *p, int norecurse) if ('\0' == *p) nospace = 1; continue; + case ESCAPE_OVERSTRIKE: + if (len == 0) + continue; + c = seq[len - 1]; + break; default: continue; } @@ -511,14 +518,26 @@ print_otag(struct html *h, enum htmltag tag, } static void -print_ctag(struct html *h, enum htmltag tag) +print_ctag(struct html *h, struct tag *tag) { - printf("</%s>", htmltags[tag].name); - if (HTML_CLRLINE & htmltags[tag].flags) { + /* + * Remember to close out and nullify the current + * meta-font and table, if applicable. + */ + if (tag == h->metaf) + h->metaf = NULL; + if (tag == h->tblt) + h->tblt = NULL; + + printf("</%s>", htmltags[tag->tag].name); + if (HTML_CLRLINE & htmltags[tag->tag].flags) { h->flags |= HTML_NOSPACE; putchar('\n'); } + + h->tags.head = tag->next; + free(tag); } void @@ -580,17 +599,7 @@ print_tagq(struct html *h, const struct tag *until) struct tag *tag; while ((tag = h->tags.head) != NULL) { - /* - * Remember to close out and nullify the current - * meta-font and table, if applicable. - */ - if (tag == h->metaf) - h->metaf = NULL; - if (tag == h->tblt) - h->tblt = NULL; - print_ctag(h, tag->tag); - h->tags.head = tag->next; - free(tag); + print_ctag(h, tag); if (until && tag == until) return; } @@ -604,17 +613,7 @@ print_stagq(struct html *h, const struct tag *suntil) while ((tag = h->tags.head) != NULL) { if (suntil && tag == suntil) return; - /* - * Remember to close out and nullify the current - * meta-font and table, if applicable. - */ - if (tag == h->metaf) - h->metaf = NULL; - if (tag == h->tblt) - h->tblt = NULL; - print_ctag(h, tag->tag); - h->tags.head = tag->next; - free(tag); + print_ctag(h, tag); } } diff --git a/contrib/mdocml/libman.h b/contrib/mdocml/libman.h index b26c2b60efe2..8d115b3abeda 100644 --- a/contrib/mdocml/libman.h +++ b/contrib/mdocml/libman.h @@ -1,4 +1,4 @@ -/* $Id: libman.h,v 1.66 2014/12/01 04:05:31 schwarze Exp $ */ +/* $Id: libman.h,v 1.67 2014/12/28 14:42:27 schwarze Exp $ */ /* * Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> * Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org> @@ -23,6 +23,7 @@ enum man_next { struct man { struct mparse *parse; /* parse pointer */ + const char *defos; /* default OS argument for .TH */ int quick; /* abort parse early */ int flags; /* parse flags */ #define MAN_ELINE (1 << 1) /* Next-line element scope. */ diff --git a/contrib/mdocml/libmandoc.h b/contrib/mdocml/libmandoc.h index 6aa8b8dcf0f3..11feebdc1019 100644 --- a/contrib/mdocml/libmandoc.h +++ b/contrib/mdocml/libmandoc.h @@ -1,4 +1,4 @@ -/* $Id: libmandoc.h,v 1.51 2014/12/01 08:05:52 schwarze Exp $ */ +/* $Id: libmandoc.h,v 1.55 2015/01/15 04:26:39 schwarze Exp $ */ /* * Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> * Copyright (c) 2013, 2014 Ingo Schwarze <schwarze@openbsd.org> @@ -24,8 +24,7 @@ enum rofferr { ROFF_SO, /* include another file */ ROFF_IGN, /* ignore current line */ ROFF_TBL, /* a table row was successfully parsed */ - ROFF_EQN, /* an equation was successfully parsed */ - ROFF_ERR /* badness: puke and stop */ + ROFF_EQN /* an equation was successfully parsed */ }; struct buf { @@ -37,7 +36,6 @@ __BEGIN_DECLS struct mparse; struct mchars; -enum mandocerr; struct tbl_span; struct eqn; struct roff; @@ -62,15 +60,16 @@ struct mdoc *mdoc_alloc(struct roff *, struct mparse *, const char *, int); void mdoc_reset(struct mdoc *); int mdoc_parseln(struct mdoc *, int, char *, int); -int mdoc_endparse(struct mdoc *); +void mdoc_endparse(struct mdoc *); void mdoc_addspan(struct mdoc *, const struct tbl_span *); void mdoc_addeqn(struct mdoc *, const struct eqn *); void man_free(struct man *); -struct man *man_alloc(struct roff *, struct mparse *, int); +struct man *man_alloc(struct roff *, struct mparse *, + const char *, int); void man_reset(struct man *); int man_parseln(struct man *, int, char *, int); -int man_endparse(struct man *); +void man_endparse(struct man *); void man_addspan(struct man *, const struct tbl_span *); void man_addeqn(struct man *, const struct eqn *); diff --git a/contrib/mdocml/libmdoc.h b/contrib/mdocml/libmdoc.h index b245213a8f22..527fe0270375 100644 --- a/contrib/mdocml/libmdoc.h +++ b/contrib/mdocml/libmdoc.h @@ -1,4 +1,4 @@ -/* $Id: libmdoc.h,v 1.96 2014/12/01 04:05:32 schwarze Exp $ */ +/* $Id: libmdoc.h,v 1.97 2015/02/02 04:26:44 schwarze Exp $ */ /* * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> * Copyright (c) 2013, 2014 Ingo Schwarze <schwarze@openbsd.org> @@ -106,7 +106,7 @@ struct mdoc_node *mdoc_block_alloc(struct mdoc *, int, int, struct mdoc_node *mdoc_head_alloc(struct mdoc *, int, int, enum mdoct); void mdoc_tail_alloc(struct mdoc *, int, int, enum mdoct); struct mdoc_node *mdoc_body_alloc(struct mdoc *, int, int, enum mdoct); -void mdoc_endbody_alloc(struct mdoc *, int, int, enum mdoct, +struct mdoc_node *mdoc_endbody_alloc(struct mdoc *, int, int, enum mdoct, struct mdoc_node *, enum mdoc_endbody); void mdoc_node_delete(struct mdoc *, struct mdoc_node *); void mdoc_node_relink(struct mdoc *, struct mdoc_node *); diff --git a/contrib/mdocml/libroff.h b/contrib/mdocml/libroff.h index dd7ad75a947c..08ed1f7925d2 100644 --- a/contrib/mdocml/libroff.h +++ b/contrib/mdocml/libroff.h @@ -1,7 +1,7 @@ -/* $Id: libroff.h,v 1.33 2014/12/01 08:05:52 schwarze Exp $ */ +/* $Id: libroff.h,v 1.38 2015/01/30 04:11:50 schwarze Exp $ */ /* * Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -34,8 +34,6 @@ struct tbl_node { struct tbl_span *first_span; struct tbl_span *current_span; struct tbl_span *last_span; - struct tbl_head *first_head; - struct tbl_head *last_head; struct tbl_node *next; }; @@ -69,12 +67,12 @@ void tbl_restart(int, int, struct tbl_node *); void tbl_free(struct tbl_node *); void tbl_reset(struct tbl_node *); enum rofferr tbl_read(struct tbl_node *, int, const char *, int); -int tbl_option(struct tbl_node *, int, const char *); -int tbl_layout(struct tbl_node *, int, const char *); -int tbl_data(struct tbl_node *, int, const char *); -int tbl_cdata(struct tbl_node *, int, const char *); +void tbl_option(struct tbl_node *, int, const char *, int *); +void tbl_layout(struct tbl_node *, int, const char *, int); +void tbl_data(struct tbl_node *, int, const char *, int); +int tbl_cdata(struct tbl_node *, int, const char *, int); const struct tbl_span *tbl_span(struct tbl_node *); -void tbl_end(struct tbl_node **); +int tbl_end(struct tbl_node **); struct eqn_node *eqn_alloc(int, int, struct mparse *); enum rofferr eqn_end(struct eqn_node **); void eqn_free(struct eqn_node *); diff --git a/contrib/mdocml/main.c b/contrib/mdocml/main.c index ec6e98006471..236c3c88d16a 100644 --- a/contrib/mdocml/main.c +++ b/contrib/mdocml/main.c @@ -1,7 +1,7 @@ -/* $Id: main.c,v 1.205 2014/12/11 19:19:35 schwarze Exp $ */ +/* $Id: main.c,v 1.222 2015/02/27 16:02:10 schwarze Exp $ */ /* * Copyright (c) 2008-2012 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2010, 2011, 2012, 2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2010-2012, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> * Copyright (c) 2010 Joerg Sonnenberger <joerg@netbsd.org> * * Permission to use, copy, modify, and distribute this software for any @@ -19,11 +19,13 @@ #include "config.h" #include <sys/types.h> +#include <sys/param.h> /* MACHINE */ #include <assert.h> #include <ctype.h> #include <errno.h> #include <fcntl.h> +#include <glob.h> #include <stdio.h> #include <stdint.h> #include <stdlib.h> @@ -82,6 +84,13 @@ struct curparse { char outopts[BUFSIZ]; /* buf of output opts */ }; +static int fs_lookup(const struct manpaths *, + size_t ipath, const char *, + const char *, const char *, + struct manpage **, size_t *); +static void fs_search(const struct mansearch *, + const struct manpaths *, int, char**, + struct manpage **, size_t *); static int koptions(int *, char *); #if HAVE_SQLITE3 int mandocdb(int, char**); @@ -91,13 +100,10 @@ static void mmsg(enum mandocerr, enum mandoclevel, const char *, int, int, const char *); static void parse(struct curparse *, int, const char *, enum mandoclevel *); -#if HAVE_SQLITE3 static enum mandoclevel passthrough(const char *, int, int); -#endif static void spawn_pager(void); static int toptions(struct curparse *, char *); static void usage(enum argmode) __attribute__((noreturn)); -static void version(void) __attribute__((noreturn)); static int woptions(struct curparse *, char *); static const int sec_prios[] = {1, 4, 5, 8, 6, 3, 7, 2, 9}; @@ -114,14 +120,13 @@ main(int argc, char *argv[]) struct manpaths paths; char *auxpaths; char *defos; -#if HAVE_SQLITE3 + unsigned char *uc; struct manpage *res, *resp; char *conf_file, *defpaths; size_t isec, i, sz; int prio, best_prio, synopsis_only; char sec; -#endif - enum mandoclevel rc; + enum mandoclevel rc, rctmp; enum outmode outmode; int fd; int show_usage; @@ -129,8 +134,9 @@ main(int argc, char *argv[]) int options; int c; - progname = strrchr(argv[0], '/'); - if (progname == NULL) + if (argc < 1) + progname = "mandoc"; + else if ((progname = strrchr(argv[0], '/')) == NULL) progname = argv[0]; else ++progname; @@ -143,9 +149,7 @@ main(int argc, char *argv[]) /* Search options. */ memset(&paths, 0, sizeof(struct manpaths)); -#if HAVE_SQLITE3 conf_file = defpaths = NULL; -#endif auxpaths = NULL; memset(&search, 0, sizeof(struct mansearch)); @@ -166,15 +170,13 @@ main(int argc, char *argv[]) memset(&curp, 0, sizeof(struct curparse)); curp.outtype = OUTT_LOCALE; - curp.wlevel = MANDOCLEVEL_FATAL; + curp.wlevel = MANDOCLEVEL_BADARG; options = MPARSE_SO | MPARSE_UTF8 | MPARSE_LATIN1; defos = NULL; use_pager = 1; show_usage = 0; -#if HAVE_SQLITE3 synopsis_only = 0; -#endif outmode = OUTMODE_DEF; while (-1 != (c = getopt(argc, argv, @@ -184,9 +186,7 @@ main(int argc, char *argv[]) outmode = OUTMODE_ALL; break; case 'C': -#if HAVE_SQLITE3 conf_file = optarg; -#endif break; case 'c': use_pager = 0; @@ -196,22 +196,20 @@ main(int argc, char *argv[]) break; case 'h': (void)strlcat(curp.outopts, "synopsis,", BUFSIZ); -#if HAVE_SQLITE3 synopsis_only = 1; -#endif use_pager = 0; outmode = OUTMODE_ALL; break; case 'I': if (strncmp(optarg, "os=", 3)) { fprintf(stderr, - "%s: -I%s: Bad argument\n", + "%s: -I %s: Bad argument\n", progname, optarg); return((int)MANDOCLEVEL_BADARG); } if (defos) { fprintf(stderr, - "%s: -I%s: Duplicate argument\n", + "%s: -I %s: Duplicate argument\n", progname, optarg); return((int)MANDOCLEVEL_BADARG); } @@ -232,9 +230,7 @@ main(int argc, char *argv[]) outmode = OUTMODE_ALL; break; case 'M': -#if HAVE_SQLITE3 defpaths = optarg; -#endif break; case 'm': auxpaths = optarg; @@ -261,9 +257,6 @@ main(int argc, char *argv[]) case 'w': outmode = OUTMODE_FLN; break; - case 'V': - version(); - /* NOTREACHED */ default: show_usage = 1; break; @@ -292,11 +285,11 @@ main(int argc, char *argv[]) /* Parse arguments. */ - argc -= optind; - argv += optind; -#if HAVE_SQLITE3 + if (argc > 0) { + argc -= optind; + argv += optind; + } resp = NULL; -#endif /* * Quirks for help(1) @@ -309,13 +302,19 @@ main(int argc, char *argv[]) argv = help_argv; argc = 1; } - } else if (argv[0] != NULL && - isdigit((unsigned char)argv[0][0]) && - (argv[0][1] == '\0' || !strcmp(argv[0], "3p"))) { - search.sec = argv[0]; + } else if (argc > 1 && + ((uc = argv[0]) != NULL) && + ((isdigit(uc[0]) && (uc[1] == '\0' || + (isalpha(uc[1]) && uc[2] == '\0'))) || + (uc[0] == 'n' && uc[1] == '\0'))) { + search.sec = uc; argv++; argc--; } + if (search.arch == NULL) + search.arch = getenv("MACHINE"); + if (search.arch == NULL) + search.arch = MACHINE; } rc = MANDOCLEVEL_OK; @@ -323,7 +322,6 @@ main(int argc, char *argv[]) /* man(1), whatis(1), apropos(1) */ if (search.argmode != ARG_FILE) { -#if HAVE_SQLITE3 if (argc == 0) usage(search.argmode); @@ -334,15 +332,23 @@ main(int argc, char *argv[]) /* Access the mandoc database. */ manpath_parse(&paths, conf_file, defpaths, auxpaths); +#if HAVE_SQLITE3 mansearch_setup(1); if( ! mansearch(&search, &paths, argc, argv, &res, &sz)) usage(search.argmode); - resp = res; +#else + if (search.argmode != ARG_NAME) { + fputs("mandoc: database support not compiled in\n", + stderr); + return((int)MANDOCLEVEL_BADARG); + } + sz = 0; +#endif + + if (sz == 0 && search.argmode == ARG_NAME) + fs_search(&search, &paths, argc, argv, &res, &sz); if (sz == 0) { - if (search.argmode == ARG_NAME) - fprintf(stderr, "%s: No entry for %s " - "in the manual.\n", progname, argv[0]); rc = MANDOCLEVEL_BADARG; goto out; } @@ -361,6 +367,7 @@ main(int argc, char *argv[]) /* Iterate all matching manuals. */ + resp = res; for (i = 0; i < sz; i++) { if (outmode == OUTMODE_FLN) puts(res[i].file); @@ -390,21 +397,13 @@ main(int argc, char *argv[]) if (outmode == OUTMODE_FLN || outmode == OUTMODE_LST) goto out; -#else - fputs("mandoc: database support not compiled in\n", - stderr); - return((int)MANDOCLEVEL_BADARG); -#endif } /* mandoc(1) */ - if ( ! moptions(&options, auxpaths)) + if (search.argmode == ARG_FILE && ! moptions(&options, auxpaths)) return((int)MANDOCLEVEL_BADARG); - if (use_pager && isatty(STDOUT_FILENO)) - spawn_pager(); - curp.mchars = mchars_alloc(); curp.mp = mparse_alloc(options, curp.wlevel, mmsg, curp.mchars, defos); @@ -415,37 +414,53 @@ main(int argc, char *argv[]) if (OUTT_MAN == curp.outtype) mparse_keep(curp.mp); - if (argc == 0) + if (argc < 1) { + if (use_pager && isatty(STDOUT_FILENO)) + spawn_pager(); parse(&curp, STDIN_FILENO, "<stdin>", &rc); + } - while (argc) { -#if HAVE_SQLITE3 - if (resp != NULL) { - rc = mparse_open(curp.mp, &fd, resp->file); - if (fd == -1) - /* nothing */; + while (argc > 0) { + rctmp = mparse_open(curp.mp, &fd, + resp != NULL ? resp->file : *argv); + if (rc < rctmp) + rc = rctmp; + + if (fd != -1) { + if (use_pager && isatty(STDOUT_FILENO)) + spawn_pager(); + use_pager = 0; + + if (resp == NULL) + parse(&curp, fd, *argv, &rc); else if (resp->form & FORM_SRC) { /* For .so only; ignore failure. */ chdir(paths.paths[resp->ipath]); parse(&curp, fd, resp->file, &rc); - } else - rc = passthrough(resp->file, fd, + } else { + rctmp = passthrough(resp->file, fd, synopsis_only); - resp++; - } else -#endif - { - rc = mparse_open(curp.mp, &fd, *argv++); - if (fd != -1) - parse(&curp, fd, argv[-1], &rc); - } + if (rc < rctmp) + rc = rctmp; + } + + rctmp = mparse_wait(curp.mp); + if (rc < rctmp) + rc = rctmp; - if (mparse_wait(curp.mp) != MANDOCLEVEL_OK) - rc = MANDOCLEVEL_SYSERR; + if (argc > 1 && curp.outtype <= OUTT_UTF8) + ascii_sepline(curp.outdata); + } if (MANDOCLEVEL_OK != rc && curp.wstop) break; - argc--; + + if (resp != NULL) + resp++; + else + argv++; + if (--argc) + mparse_reset(curp.mp); } if (curp.outfree) @@ -453,14 +468,14 @@ main(int argc, char *argv[]) mparse_free(curp.mp); mchars_free(curp.mchars); -#if HAVE_SQLITE3 out: if (search.argmode != ARG_FILE) { manpath_free(&paths); +#if HAVE_SQLITE3 mansearch_free(res, sz); mansearch_setup(0); - } #endif + } free(defos); @@ -468,35 +483,29 @@ out: } static void -version(void) -{ - - printf("mandoc %s\n", VERSION); - exit((int)MANDOCLEVEL_OK); -} - -static void usage(enum argmode argmode) { switch (argmode) { case ARG_FILE: - fputs("usage: mandoc [-acfhklV] [-Ios=name] " + fputs("usage: mandoc [-acfhkl] [-Ios=name] " "[-Kencoding] [-mformat] [-Ooption]\n" "\t [-Toutput] [-Wlevel] [file ...]\n", stderr); break; case ARG_NAME: - fputs("usage: man [-acfhklVw] [-C file] " - "[-M path] [-m path] [-S arch] [-s section]\n" + fputs("usage: man [-acfhklw] [-C file] [-I os=name] " + "[-K encoding] [-M path] [-m path]\n" + "\t [-O option=value] [-S subsection] [-s section] " + "[-T output] [-W level]\n" "\t [section] name ...\n", stderr); break; case ARG_WORD: - fputs("usage: whatis [-acfhklVw] [-C file] " + fputs("usage: whatis [-acfhklw] [-C file] " "[-M path] [-m path] [-O outkey] [-S arch]\n" "\t [-s section] name ...\n", stderr); break; case ARG_EXPR: - fputs("usage: apropos [-acfhklVw] [-C file] " + fputs("usage: apropos [-acfhklw] [-C file] " "[-M path] [-m path] [-O outkey] [-S arch]\n" "\t [-s section] expression ...\n", stderr); break; @@ -504,6 +513,108 @@ usage(enum argmode argmode) exit((int)MANDOCLEVEL_BADARG); } +static int +fs_lookup(const struct manpaths *paths, size_t ipath, + const char *sec, const char *arch, const char *name, + struct manpage **res, size_t *ressz) +{ + glob_t globinfo; + struct manpage *page; + char *file; + int form, globres; + + form = FORM_SRC; + mandoc_asprintf(&file, "%s/man%s/%s.%s", + paths->paths[ipath], sec, name, sec); + if (access(file, R_OK) != -1) + goto found; + free(file); + + mandoc_asprintf(&file, "%s/cat%s/%s.0", + paths->paths[ipath], sec, name); + if (access(file, R_OK) != -1) { + form = FORM_CAT; + goto found; + } + free(file); + + if (arch != NULL) { + mandoc_asprintf(&file, "%s/man%s/%s/%s.%s", + paths->paths[ipath], sec, arch, name, sec); + if (access(file, R_OK) != -1) + goto found; + free(file); + } + + mandoc_asprintf(&file, "%s/man%s/%s.*", + paths->paths[ipath], sec, name); + globres = glob(file, 0, NULL, &globinfo); + if (globres != 0 && globres != GLOB_NOMATCH) + fprintf(stderr, "%s: %s: glob: %s\n", + progname, file, strerror(errno)); + free(file); + if (globres == 0) + file = mandoc_strdup(*globinfo.gl_pathv); + globfree(&globinfo); + if (globres != 0) + return(0); + +found: +#if HAVE_SQLITE3 + fprintf(stderr, "%s: outdated mandoc.db lacks %s(%s) entry,\n" + " consider running # makewhatis %s\n", + progname, name, sec, paths->paths[ipath]); +#endif + + *res = mandoc_reallocarray(*res, ++*ressz, sizeof(struct manpage)); + page = *res + (*ressz - 1); + page->file = file; + page->names = NULL; + page->output = NULL; + page->ipath = ipath; + page->bits = NAME_FILE & NAME_MASK; + page->sec = (*sec >= '1' && *sec <= '9') ? *sec - '1' + 1 : 10; + page->form = form; + return(1); +} + +static void +fs_search(const struct mansearch *cfg, const struct manpaths *paths, + int argc, char **argv, struct manpage **res, size_t *ressz) +{ + const char *const sections[] = + {"1", "8", "6", "2", "3", "3p", "5", "7", "4", "9"}; + const size_t nsec = sizeof(sections)/sizeof(sections[0]); + + size_t ipath, isec, lastsz; + + assert(cfg->argmode == ARG_NAME); + + *res = NULL; + *ressz = lastsz = 0; + while (argc) { + for (ipath = 0; ipath < paths->sz; ipath++) { + if (cfg->sec != NULL) { + if (fs_lookup(paths, ipath, cfg->sec, + cfg->arch, *argv, res, ressz) && + cfg->firstmatch) + return; + } else for (isec = 0; isec < nsec; isec++) + if (fs_lookup(paths, ipath, sections[isec], + cfg->arch, *argv, res, ressz) && + cfg->firstmatch) + return; + } + if (*ressz == lastsz) + fprintf(stderr, + "%s: No entry for %s in the manual.\n", + progname, *argv); + lastsz = *ressz; + argv++; + argc--; + } +} + static void parse(struct curparse *curp, int fd, const char *file, enum mandoclevel *level) @@ -519,11 +630,6 @@ parse(struct curparse *curp, int fd, const char *file, rc = mparse_readfd(curp->mp, fd, file); - /* Stop immediately if the parse has failed. */ - - if (MANDOCLEVEL_FATAL <= rc) - goto cleanup; - /* * With -Wstop and warnings or errors of at least the requested * level, do not produce output. @@ -609,15 +715,11 @@ parse(struct curparse *curp, int fd, const char *file, if (mdoc && curp->outmdoc) (*curp->outmdoc)(curp->outdata, mdoc); - cleanup: - - mparse_reset(curp->mp); - +cleanup: if (*level < rc) *level = rc; } -#if HAVE_SQLITE3 static enum mandoclevel passthrough(const char *file, int fd, int synopsis_only) { @@ -631,6 +733,8 @@ passthrough(const char *file, int fd, int synopsis_only) ssize_t nw; int print; + fflush(stdout); + if ((stream = fdopen(fd, "r")) == NULL) { close(fd); syscall = "fdopen"; @@ -681,7 +785,6 @@ fail: progname, file, syscall, strerror(errno)); return(MANDOCLEVEL_SYSERR); } -#endif static int koptions(int *options, char *arg) @@ -696,7 +799,7 @@ koptions(int *options, char *arg) } else if ( ! strcmp(arg, "us-ascii")) { *options &= ~(MPARSE_UTF8 | MPARSE_LATIN1); } else { - fprintf(stderr, "%s: -K%s: Bad argument\n", + fprintf(stderr, "%s: -K %s: Bad argument\n", progname, arg); return(0); } @@ -716,7 +819,7 @@ moptions(int *options, char *arg) else if (0 == strcmp(arg, "an")) *options |= MPARSE_MAN; else { - fprintf(stderr, "%s: -m%s: Bad argument\n", + fprintf(stderr, "%s: -m %s: Bad argument\n", progname, arg); return(0); } @@ -750,7 +853,7 @@ toptions(struct curparse *curp, char *arg) else if (0 == strcmp(arg, "pdf")) curp->outtype = OUTT_PDF; else { - fprintf(stderr, "%s: -T%s: Bad argument\n", + fprintf(stderr, "%s: -T %s: Bad argument\n", progname, arg); return(0); } @@ -762,14 +865,15 @@ static int woptions(struct curparse *curp, char *arg) { char *v, *o; - const char *toks[6]; + const char *toks[7]; toks[0] = "stop"; toks[1] = "all"; toks[2] = "warning"; toks[3] = "error"; - toks[4] = "fatal"; - toks[5] = NULL; + toks[4] = "unsupp"; + toks[5] = "fatal"; + toks[6] = NULL; while (*arg) { o = arg; @@ -786,10 +890,13 @@ woptions(struct curparse *curp, char *arg) curp->wlevel = MANDOCLEVEL_ERROR; break; case 4: - curp->wlevel = MANDOCLEVEL_FATAL; + curp->wlevel = MANDOCLEVEL_UNSUPP; + break; + case 5: + curp->wlevel = MANDOCLEVEL_BADARG; break; default: - fprintf(stderr, "%s: -W%s: Bad argument\n", + fprintf(stderr, "%s: -W %s: Bad argument\n", progname, o); return(0); } diff --git a/contrib/mdocml/main.h b/contrib/mdocml/main.h index 147c22f59464..9b04a7816aec 100644 --- a/contrib/mdocml/main.h +++ b/contrib/mdocml/main.h @@ -1,6 +1,7 @@ -/* $Id: main.h,v 1.19 2014/12/01 08:05:52 schwarze Exp $ */ +/* $Id: main.h,v 1.20 2014/12/31 16:52:40 schwarze Exp $ */ /* * Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> + * Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org> * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -45,6 +46,7 @@ void *locale_alloc(const struct mchars *, char *); void *utf8_alloc(const struct mchars *, char *); void *ascii_alloc(const struct mchars *, char *); void ascii_free(void *); +void ascii_sepline(void *); void *pdf_alloc(const struct mchars *, char *); void *ps_alloc(const struct mchars *, char *); diff --git a/contrib/mdocml/man-cgi.css b/contrib/mdocml/man-cgi.css index 5300267cfbc1..256e8c6693ef 100644 --- a/contrib/mdocml/man-cgi.css +++ b/contrib/mdocml/man-cgi.css @@ -1,10 +1,10 @@ body { font-family: Helvetica, Arial, sans-serif; } -body > div { padding-left: 2em; +body > div { padding-left: 2em; padding-top: 1em; } -body > div#mancgi { padding-left: 0em; +body > div#mancgi { padding-left: 0em; padding-top: 0em; } body > div.results { font-size: smaller; } -#mancgi fieldset { text-align: center; +#mancgi fieldset { text-align: center; border: thin solid silver; border-radius: 1em; font-size: small; } diff --git a/contrib/mdocml/man.1 b/contrib/mdocml/man.1 index 0d26fd281e79..85802967e627 100644 --- a/contrib/mdocml/man.1 +++ b/contrib/mdocml/man.1 @@ -1,9 +1,9 @@ -.\" $Id: man.1,v 1.7 2014/11/11 02:43:41 schwarze Exp $ +.\" $Id: man.1,v 1.13 2015/02/16 16:23:54 schwarze Exp $ .\" .\" Copyright (c) 1989, 1990, 1993 .\" The Regents of the University of California. All rights reserved. .\" Copyright (c) 2003, 2007, 2008, 2014 Jason McIntyre <jmc@openbsd.org> -.\" Copyright (c) 2010, 2011 Ingo Schwarze <schwarze@openbsd.org> +.\" Copyright (c) 2010, 2011, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions @@ -31,7 +31,7 @@ .\" .\" @(#)man.1 8.2 (Berkeley) 1/2/94 .\" -.Dd $Mdocdate: November 11 2014 $ +.Dd $Mdocdate: February 16 2015 $ .Dt MAN 1 .Os .Sh NAME @@ -39,12 +39,17 @@ .Nd display manual pages .Sh SYNOPSIS .Nm man -.Op Fl acfhklVw +.Op Fl acfhklw .Op Fl C Ar file +.Op Fl I Cm os Ns = Ns Ar name +.Op Fl K Ar encoding .Op Fl M Ar path .Op Fl m Ar path +.Op Fl O Ar option Ns = Ns Ar value .Op Fl S Ar subsection .Op Fl s Ar section +.Op Fl T Ar output +.Op Fl W Ar level .Op Ar section .Ar name ... .Sh DESCRIPTION @@ -95,12 +100,34 @@ This overrides any earlier and .Fl l options. +.It Fl I Cm os Ns = Ns Ar name +Override the default operating system +.Ar name +for the +.Xr mdoc 7 +.Ic \&Os +and for the +.Xr man 7 +.Ic \&TH +macro. .It Fl h Display only the SYNOPSIS lines of the requested manual pages. Implies .Fl a and .Fl c . +.It Fl K Ar encoding +Specify the input encoding. +The supported +.Ar encoding +arguments are +.Cm us-ascii , +.Cm iso-8859-1 , +and +.Cm utf-8 . +By default, the encoding is automatically detected as described in the +.Xr mandoc 1 +manual. .It Fl k A synonym for .Xr apropos 1 . @@ -173,6 +200,11 @@ are specified by the line in the .Nm configuration file. +.It Fl O Ar option Ns = Ns Ar value +Comma-separated output options. +For each output format, the available options are described in the +.Xr mandoc 1 +manual. .It Fl S Ar subsection Restricts the directories that .Nm @@ -242,8 +274,43 @@ specifies the possible .Ar section values, and their search order. Additional sections may be specified. -.It Fl V -Print version and exit. +.It Fl T Ar output +Select the output format. +The default is +.Cm locale . +The other output modes +.Cm ascii , +.Cm html , +.Cm lint , +.Cm man , +.Cm pdf , +.Cm ps , +.Cm tree , +and +.Cm utf8 +are described in the +.Xr mandoc 1 +manual. +.It Fl W Ar level +Specify the minimum message +.Ar level +to be reported on the standard error output and to affect the exit status. +The +.Ar level +can be +.Cm warning , +.Cm error , +or +.Cm unsupp ; +.Cm all +is an alias for +.Cm warning . +By default, +.Nm +is silent. +See the +.Xr mandoc 1 +manual for details. .It Fl w List the pathnames of the manual pages which .Nm @@ -254,14 +321,6 @@ and combination. .El .Pp -The -.Nm -utility also supports the options -.Fl IKOTW -described in the -.Xr mandoc 1 -manual. -.Pp Guidelines for writing man pages can be found in .Xr mdoc 7 . @@ -355,7 +414,7 @@ utility is compliant with the specification. .Pp The flags -.Op Fl aCcfhMmSsw , +.Op Fl aCcfhIKlMmOSsTWw , as well as the environment variables .Ev MACHINE , .Ev MANPAGER , diff --git a/contrib/mdocml/man.7 b/contrib/mdocml/man.7 index 4b64d7f442f4..bfeec51650e4 100644 --- a/contrib/mdocml/man.7 +++ b/contrib/mdocml/man.7 @@ -1,7 +1,7 @@ -.\" $Id: man.7,v 1.127 2014/06/22 16:39:45 schwarze Exp $ +.\" $Id: man.7,v 1.132 2015/01/29 00:33:57 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> -.\" Copyright (c) 2011, 2012, 2013 Ingo Schwarze <schwarze@openbsd.org> +.\" Copyright (c) 2011-2015 Ingo Schwarze <schwarze@openbsd.org> .\" Copyright (c) 2010 Joerg Sonnenberger <joerg@netbsd.org> .\" .\" Permission to use, copy, modify, and distribute this software for any @@ -16,7 +16,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: June 22 2014 $ +.Dd $Mdocdate: January 29 2015 $ .Dt MAN 7 .Os .Sh NAME @@ -369,11 +369,11 @@ Begin a paragraph whose initial output line is left-justified, but subsequent output lines are indented, with the following syntax: .Bd -filled -offset indent .Pf \. Sx \&HP -.Op Cm width +.Op Ar width .Ed .Pp The -.Cm width +.Ar width argument is a .Xr roff 7 scaling width. @@ -413,11 +413,11 @@ and Begin an indented paragraph with the following syntax: .Bd -filled -offset indent .Pf \. Sx \&IP -.Op Cm head Op Cm width +.Op Ar head Op Ar width .Ed .Pp The -.Cm width +.Ar width argument is a .Xr roff 7 scaling width defining the left margin. @@ -425,7 +425,7 @@ It's saved for later paragraph left-margins; if unspecified, the saved or default width is used. .Pp The -.Cm head +.Ar head argument is used as a leading term, flushed to the left margin. This is useful for bulleted paragraphs and so on. .Pp @@ -470,13 +470,13 @@ This is a non-standard GNU extension, included only for compatibility. It has the following syntax: .Bd -filled -offset indent .Pf \. Sx \&OP -.Cm key Op Cm value +.Ar key Op Ar value .Ed .Pp The -.Cm key +.Ar key is usually a command-line flag and -.Cm value +.Ar value its argument. .Ss \&P Synonym for @@ -495,11 +495,11 @@ Specify the vertical space to be inserted before each new paragraph. The syntax is as follows: .Bd -filled -offset indent .Pf \. Sx \&PD -.Op Cm height +.Op Ar height .Ed .Pp The -.Cm height +.Ar height argument is a .Xr roff 7 scaling width. @@ -555,9 +555,29 @@ and .Ss \&RE Explicitly close out the scope of a prior .Sx \&RS . -The default left margin is restored to the state of the original +The default left margin is restored to the state before that .Sx \&RS invocation. +.Pp +The syntax is as follows: +.Bd -filled -offset indent +.Pf \. Sx \&RE +.Op Ar level +.Ed +.Pp +Without an argument, the most recent +.Sx \&RS +block is closed out. +If +.Ar level +is 1, all open +.Sx \&RS +blocks are closed out. +Otherwise, +.Ar level No \(mi 1 +nested +.Sx \&RS +blocks remain open. .Ss \&RI Text is rendered alternately in roman (the default font) and italics. Whitespace between arguments is omitted in output. @@ -578,11 +598,11 @@ Temporarily reset the default left margin. This has the following syntax: .Bd -filled -offset indent .Pf \. Sx \&RS -.Op Cm width +.Op Ar width .Ed .Pp The -.Cm width +.Ar width argument is a .Xr roff 7 scaling width. @@ -607,7 +627,8 @@ The scope of a sub-section is closed by a subsequent sub-section, section, or end of file. The paragraph left-margin width is reset to the default. .Ss \&TH -Sets the title of the manual page with the following syntax: +Sets the title of the manual page for use in the page header +and footer with the following syntax: .Bd -filled -offset indent .Pf \. Sx \&TH .Ar title section date @@ -629,6 +650,11 @@ is empty or not specified, the current date is used. The optional .Ar source string specifies the organisation providing the utility. +When unspecified, +.Xr mandoc 1 +uses its +.Fl Ios +argument. The .Ar volume string replaces the default rendered volume, which is dictated by the @@ -645,11 +671,11 @@ Subsequent output lines are indented. The syntax is as follows: .Bd -filled -offset indent .Pf \. Sx \&TP -.Op Cm width +.Op Ar width .Ed .Pp The -.Cm width +.Ar width argument is a .Xr roff 7 scaling width. @@ -694,15 +720,13 @@ End literal mode begun by .Ss \&in Indent relative to the current indentation: .Pp -.D1 Pf \. Sx \&in Op Cm width +.D1 Pf \. Sx \&in Op Ar width .Pp If -.Cm width +.Ar width is signed, the new offset is relative. Otherwise, it is absolute. This value is reset upon the next paragraph, section, or sub-section. -.Ss \&na -Don't align to the right margin. .Ss \&nf Begin literal mode: all subsequent free-form lines have their end of line boundaries preserved. @@ -716,11 +740,11 @@ or Insert vertical spaces into output with the following syntax: .Bd -filled -offset indent .Pf \. Sx \&sp -.Op Cm height +.Op Ar height .Ed .Pp The -.Cm height +.Ar height argument is a scaling width as described in .Xr roff 7 . If 0, this is equivalent to the @@ -754,10 +778,9 @@ is equivalent to If next-line macros are invoked consecutively, only the last is used. If a next-line macro is followed by a non-next-line macro, an error is raised, except for -.Sx \&br , -.Sx \&sp , +.Sx \&br and -.Sx \&na . +.Sx \&sp . .Pp The syntax is as follows: .Bd -literal -offset indent @@ -788,7 +811,6 @@ The syntax is as follows: .It Sx \&br Ta 0 Ta current Ta compat .It Sx \&fi Ta 0 Ta current Ta compat .It Sx \&in Ta 1 Ta current Ta compat -.It Sx \&na Ta 0 Ta current Ta compat .It Sx \&nf Ta 0 Ta current Ta compat .It Sx \&sp Ta 1 Ta current Ta compat .El @@ -872,53 +894,6 @@ until the end of the macro scope. Note that macros like .Sx \&BR open and close a font scope for each argument. -.Sh COMPATIBILITY -This section mentions some areas of questionable portability between -implementations of the -.Nm -language. -More incompatibilities exist. -.Pp -.Bl -dash -compact -.It -Do not depend on -.Sx \&SH -or -.Sx \&SS -to close out a literal context opened with -.Sx \&nf . -This behaviour may not be portable. -.It -troff suppresses a newline before -.Sq \(aq -macro output; in mandoc, it is an alias for the standard -.Sq \&. -control character. -.It -In page header lines, GNU troff versions up to and including 1.21 -only print -.Ar volume -names explicitly specified in the -.Sx \&TH -macro; mandoc and newer groff print the default volume name -corresponding to the -.Ar section -number when no -.Ar volume -is given, like in -.Xr mdoc 7 . -.El -.Pp -The -.Sx EE , -.Sx EX , -.Sx OP , -.Sx UE , -and -.Sx UR -macros are part of the GNU extended -.Nm -macro set, and may not be portable to non-GNU troff implementations. .Sh SEE ALSO .Xr man 1 , .Xr mandoc 1 , diff --git a/contrib/mdocml/man.c b/contrib/mdocml/man.c index 048db26f9a2b..4e7a398d9bbe 100644 --- a/contrib/mdocml/man.c +++ b/contrib/mdocml/man.c @@ -1,7 +1,7 @@ -/* $Id: man.c,v 1.145 2014/11/28 06:27:05 schwarze Exp $ */ +/* $Id: man.c,v 1.149 2015/01/30 21:28:46 schwarze Exp $ */ /* * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2013, 2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2013, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> * Copyright (c) 2011 Joerg Sonnenberger <joerg@netbsd.org> * * Permission to use, copy, modify, and distribute this software for any @@ -39,7 +39,7 @@ const char *const __man_macronames[MAN_MAX] = { "IP", "HP", "SM", "SB", "BI", "IB", "BR", "RB", "R", "B", "I", "IR", - "RI", "na", "sp", "nf", + "RI", "sp", "nf", "fi", "RE", "RS", "DT", "UC", "PD", "AT", "in", "ft", "OP", "EX", "EE", @@ -48,6 +48,10 @@ const char *const __man_macronames[MAN_MAX] = { const char * const *man_macronames = __man_macronames; +static void man_alloc1(struct man *); +static void man_breakscope(struct man *, enum mant); +static void man_descope(struct man *, int, int); +static void man_free1(struct man *); static struct man_node *man_node_alloc(struct man *, int, int, enum man_type, enum mant); static void man_node_append(struct man *, struct man_node *); @@ -56,9 +60,6 @@ static void man_node_unlink(struct man *, struct man_node *); static int man_ptext(struct man *, int, char *, int); static int man_pmacro(struct man *, int, char *, int); -static void man_free1(struct man *); -static void man_alloc1(struct man *); -static void man_descope(struct man *, int, int); const struct man_node * @@ -92,7 +93,8 @@ man_free(struct man *man) } struct man * -man_alloc(struct roff *roff, struct mparse *parse, int quick) +man_alloc(struct roff *roff, struct mparse *parse, + const char *defos, int quick) { struct man *p; @@ -100,6 +102,7 @@ man_alloc(struct roff *roff, struct mparse *parse, int quick) man_hash_init(); p->parse = parse; + p->defos = defos; p->quick = quick; p->roff = roff; @@ -107,12 +110,11 @@ man_alloc(struct roff *roff, struct mparse *parse, int quick) return(p); } -int +void man_endparse(struct man *man) { man_macroend(man); - return(1); } int @@ -336,6 +338,7 @@ man_addspan(struct man *man, const struct tbl_span *sp) { struct man_node *n; + man_breakscope(man, MAN_MAX); n = man_node_alloc(man, sp->line, 0, MAN_TBL, MAN_MAX); n->span = sp; man_node_append(man, n); @@ -492,62 +495,11 @@ man_pmacro(struct man *man, int ln, char *buf, int offs) ln, offs - 1, NULL); /* - * Remove prior ELINE macro, as it's being clobbered by a new - * macro. Note that NSCOPED macros do not close out ELINE - * macros---they don't print text---so we let those slip by. + * Some macros break next-line scopes; otherwise, remember + * whether we are in next-line scope for a block head. */ - if ( ! (man_macros[tok].flags & MAN_NSCOPED) && - man->flags & MAN_ELINE) { - n = man->last; - assert(MAN_TEXT != n->type); - - /* Remove repeated NSCOPED macros causing ELINE. */ - - if (man_macros[n->tok].flags & MAN_NSCOPED) - n = n->parent; - - mandoc_vmsg(MANDOCERR_BLK_LINE, man->parse, n->line, - n->pos, "%s breaks %s", man_macronames[tok], - man_macronames[n->tok]); - - man_node_delete(man, n); - man->flags &= ~MAN_ELINE; - } - - /* - * Remove prior BLINE macro that is being clobbered. - */ - if ((man->flags & MAN_BLINE) && - (man_macros[tok].flags & MAN_BSCOPE)) { - n = man->last; - - /* Might be a text node like 8 in - * .TP 8 - * .SH foo - */ - if (n->type == MAN_TEXT) - n = n->parent; - - /* Remove element that didn't end BLINE, if any. */ - if ( ! (man_macros[n->tok].flags & MAN_BSCOPE)) - n = n->parent; - - assert(n->type == MAN_HEAD); - n = n->parent; - assert(n->type == MAN_BLOCK); - assert(man_macros[n->tok].flags & MAN_SCOPED); - - mandoc_vmsg(MANDOCERR_BLK_LINE, man->parse, n->line, - n->pos, "%s breaks %s", man_macronames[tok], - man_macronames[n->tok]); - - man_node_delete(man, n); - man->flags &= ~MAN_BLINE; - } - - /* Remember whether we are in next-line scope for a block head. */ - + man_breakscope(man, tok); bline = man->flags & MAN_BLINE; /* Call to handler... */ @@ -582,6 +534,62 @@ man_pmacro(struct man *man, int ln, char *buf, int offs) return(1); } +void +man_breakscope(struct man *man, enum mant tok) +{ + struct man_node *n; + + /* + * An element next line scope is open, + * and the new macro is not allowed inside elements. + * Delete the element that is being broken. + */ + + if (man->flags & MAN_ELINE && (tok == MAN_MAX || + ! (man_macros[tok].flags & MAN_NSCOPED))) { + n = man->last; + assert(n->type != MAN_TEXT); + if (man_macros[n->tok].flags & MAN_NSCOPED) + n = n->parent; + + mandoc_vmsg(MANDOCERR_BLK_LINE, man->parse, + n->line, n->pos, "%s breaks %s", + tok == MAN_MAX ? "TS" : man_macronames[tok], + man_macronames[n->tok]); + + man_node_delete(man, n); + man->flags &= ~MAN_ELINE; + } + + /* + * A block header next line scope is open, + * and the new macro is not allowed inside block headers. + * Delete the block that is being broken. + */ + + if (man->flags & MAN_BLINE && (tok == MAN_MAX || + man_macros[tok].flags & MAN_BSCOPE)) { + n = man->last; + if (n->type == MAN_TEXT) + n = n->parent; + if ( ! (man_macros[n->tok].flags & MAN_BSCOPE)) + n = n->parent; + + assert(n->type == MAN_HEAD); + n = n->parent; + assert(n->type == MAN_BLOCK); + assert(man_macros[n->tok].flags & MAN_SCOPED); + + mandoc_vmsg(MANDOCERR_BLK_LINE, man->parse, + n->line, n->pos, "%s breaks %s", + tok == MAN_MAX ? "TS" : man_macronames[tok], + man_macronames[n->tok]); + + man_node_delete(man, n); + man->flags &= ~MAN_BLINE; + } +} + /* * Unlink a node from its context. If "man" is provided, the last parse * point will also be adjusted accordingly. diff --git a/contrib/mdocml/man.h b/contrib/mdocml/man.h index 08bfcc8e4de5..9e8eb03e5717 100644 --- a/contrib/mdocml/man.h +++ b/contrib/mdocml/man.h @@ -1,4 +1,4 @@ -/* $Id: man.h,v 1.67 2014/12/01 04:05:32 schwarze Exp $ */ +/* $Id: man.h,v 1.69 2015/01/24 02:41:49 schwarze Exp $ */ /* * Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> * Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org> @@ -38,7 +38,6 @@ enum mant { MAN_I, MAN_IR, MAN_RI, - MAN_na, MAN_sp, MAN_nf, MAN_fi, @@ -99,6 +98,7 @@ struct man_node { struct man_node *body; /* BLOCK node BODY ptr */ const struct tbl_span *span; /* TBL */ const struct eqn *eqn; /* EQN */ + int aux; /* decoded node data, type-dependent */ }; /* Names of macros. Index is enum mant. */ diff --git a/contrib/mdocml/man_html.c b/contrib/mdocml/man_html.c index 1455e1e4aec9..0e0fad9e3d73 100644 --- a/contrib/mdocml/man_html.c +++ b/contrib/mdocml/man_html.c @@ -1,7 +1,7 @@ -/* $Id: man_html.c,v 1.107 2014/12/04 02:05:42 schwarze Exp $ */ +/* $Id: man_html.c,v 1.111 2015/02/10 08:05:30 schwarze Exp $ */ /* * Copyright (c) 2008-2012, 2014 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2013, 2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2013, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -100,7 +100,6 @@ static const struct htmlman mans[MAN_MAX] = { { man_I_pre, NULL }, /* I */ { man_alt_pre, NULL }, /* IR */ { man_alt_pre, NULL }, /* RI */ - { man_ign_pre, NULL }, /* na */ { man_br_pre, NULL }, /* sp */ { man_literal_pre, NULL }, /* nf */ { man_literal_pre, NULL }, /* fi */ @@ -193,9 +192,10 @@ static void print_man_nodelist(MAN_ARGS) { - print_man_node(man, n, mh, h); - if (n->next) - print_man_nodelist(man, n->next, mh, h); + while (n != NULL) { + print_man_node(man, n, mh, h); + n = n->next; + } } static void @@ -216,7 +216,7 @@ print_man_node(MAN_ARGS) print_paragraph(h); return; } - if (n->flags & MAN_LINE && (*n->string == ' ' || + if (n->flags & MAN_LINE && (*n->string == ' ' || (n->prev != NULL && mh->fl & MANH_LITERAL && ! (h->flags & HTML_NONEWLINE)))) print_otag(h, TAG_BR, 0, NULL); @@ -362,7 +362,7 @@ man_br_pre(MAN_ARGS) if (MAN_sp == n->tok) { if (NULL != (n = n->child)) if ( ! a2roffsu(n->string, &su, SCALE_VS)) - SCALE_VS_INIT(&su, atoi(n->string)); + su.scale = 1.0; } else su.scale = 0.0; diff --git a/contrib/mdocml/man_macro.c b/contrib/mdocml/man_macro.c index 1b8965899edc..c86ab6f13f01 100644 --- a/contrib/mdocml/man_macro.c +++ b/contrib/mdocml/man_macro.c @@ -1,7 +1,7 @@ -/* $Id: man_macro.c,v 1.91 2014/11/28 05:51:32 schwarze Exp $ */ +/* $Id: man_macro.c,v 1.98 2015/02/06 11:54:36 schwarze Exp $ */ /* * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2012, 2013, 2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2012, 2013, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> * Copyright (c) 2013 Franco Fichtner <franco@lastsummer.de> * * Permission to use, copy, modify, and distribute this software for any @@ -72,11 +72,10 @@ const struct man_macro __man_macros[MAN_MAX] = { { in_line_eoln, MAN_SCOPED | MAN_JOIN }, /* I */ { in_line_eoln, 0 }, /* IR */ { in_line_eoln, 0 }, /* RI */ - { in_line_eoln, MAN_NSCOPED }, /* na */ { in_line_eoln, MAN_NSCOPED }, /* sp */ { in_line_eoln, MAN_BSCOPE }, /* nf */ { in_line_eoln, MAN_BSCOPE }, /* fi */ - { blk_close, 0 }, /* RE */ + { blk_close, MAN_BSCOPE }, /* RE */ { blk_exp, MAN_BSCOPE | MAN_EXPLICIT }, /* RS */ { in_line_eoln, 0 }, /* DT */ { in_line_eoln, 0 }, /* UC */ @@ -88,7 +87,7 @@ const struct man_macro __man_macros[MAN_MAX] = { { in_line_eoln, MAN_BSCOPE }, /* EX */ { in_line_eoln, MAN_BSCOPE }, /* EE */ { blk_exp, MAN_BSCOPE | MAN_EXPLICIT }, /* UR */ - { blk_close, 0 }, /* UE */ + { blk_close, MAN_BSCOPE }, /* UE */ { in_line_eoln, 0 }, /* ll */ }; @@ -279,10 +278,30 @@ blk_close(MACRO_PROT_ARGS) { enum mant ntok; const struct man_node *nn; + char *p; + int nrew, target; + nrew = 1; switch (tok) { case MAN_RE: ntok = MAN_RS; + if ( ! man_args(man, line, pos, buf, &p)) + break; + for (nn = man->last->parent; nn; nn = nn->parent) + if (nn->tok == ntok && nn->type == MAN_BLOCK) + nrew++; + target = strtol(p, &p, 10); + if (*p != '\0') + mandoc_vmsg(MANDOCERR_ARG_EXCESS, man->parse, + line, p - buf, "RE ... %s", p); + if (target == 0) + target = 1; + nrew -= target; + if (nrew < 1) { + mandoc_vmsg(MANDOCERR_RE_NOTOPEN, man->parse, + line, ppos, "RE %d", target); + return; + } break; case MAN_UE: ntok = MAN_UR; @@ -293,45 +312,50 @@ blk_close(MACRO_PROT_ARGS) } for (nn = man->last->parent; nn; nn = nn->parent) - if (nn->tok == ntok && nn->type == MAN_BLOCK) + if (nn->tok == ntok && nn->type == MAN_BLOCK && ! --nrew) break; if (nn == NULL) { mandoc_msg(MANDOCERR_BLK_NOTOPEN, man->parse, line, ppos, man_macronames[tok]); rew_scope(MAN_BLOCK, man, MAN_PP); - } else + } else { + line = man->last->line; + ppos = man->last->pos; + ntok = man->last->tok; man_unscope(man, nn); + + /* Move a trailing paragraph behind the block. */ + + if (ntok == MAN_LP || ntok == MAN_PP || ntok == MAN_P) { + *pos = strlen(buf); + blk_imp(man, ntok, line, ppos, pos, buf); + } + } } void blk_exp(MACRO_PROT_ARGS) { - struct man_node *n; - int la; + struct man_node *head; char *p; + int la; rew_scope(MAN_BLOCK, man, tok); man_block_alloc(man, line, ppos, tok); man_head_alloc(man, line, ppos, tok); + head = man->last; - for (;;) { - la = *pos; - if ( ! man_args(man, line, pos, buf, &p)) - break; + la = *pos; + if (man_args(man, line, pos, buf, &p)) man_word_alloc(man, line, la, p); - } - assert(man); - assert(tok != MAN_MAX); - - for (n = man->last; n; n = n->parent) - if (n->tok == tok) { - assert(n->type == MAN_HEAD); - man_unscope(man, n); - break; - } + if (buf[*pos] != '\0') + mandoc_vmsg(MANDOCERR_ARG_EXCESS, + man->parse, line, *pos, "%s ... %s", + man_macronames[tok], buf + *pos); + man_unscope(man, head); man_body_alloc(man, line, ppos, tok); } @@ -390,6 +414,20 @@ in_line_eoln(MACRO_PROT_ARGS) n = man->last; for (;;) { + if (buf[*pos] != '\0' && (tok == MAN_br || + tok == MAN_fi || tok == MAN_nf)) { + mandoc_vmsg(MANDOCERR_ARG_SKIP, + man->parse, line, *pos, "%s %s", + man_macronames[tok], buf + *pos); + break; + } + if (buf[*pos] != '\0' && man->last != n && + (tok == MAN_PD || tok == MAN_ft || tok == MAN_sp)) { + mandoc_vmsg(MANDOCERR_ARG_EXCESS, + man->parse, line, *pos, "%s ... %s", + man_macronames[tok], buf + *pos); + break; + } la = *pos; if ( ! man_args(man, line, pos, buf, &p)) break; diff --git a/contrib/mdocml/man_term.c b/contrib/mdocml/man_term.c index 9a9abafdbc5b..ab75851f2b28 100644 --- a/contrib/mdocml/man_term.c +++ b/contrib/mdocml/man_term.c @@ -1,7 +1,7 @@ -/* $Id: man_term.c,v 1.159 2014/12/04 02:05:42 schwarze Exp $ */ +/* $Id: man_term.c,v 1.168 2015/01/30 22:04:44 schwarze Exp $ */ /* * Copyright (c) 2008-2012 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2010-2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2010-2015 Ingo Schwarze <schwarze@openbsd.org> * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -21,6 +21,7 @@ #include <assert.h> #include <ctype.h> +#include <limits.h> #include <stdio.h> #include <stdlib.h> #include <string.h> @@ -37,7 +38,7 @@ struct mtermp { int fl; #define MANT_LITERAL (1 << 0) - size_t lmargin[MAXMARGINS]; /* margins (incl. visible page) */ + int lmargin[MAXMARGINS]; /* margins (incl. vis. page) */ int lmargincur; /* index of current margin */ int lmarginsz; /* actual number of nested margins */ size_t offset; /* default offset to visible page */ @@ -46,7 +47,7 @@ struct mtermp { #define DECL_ARGS struct termp *p, \ struct mtermp *mt, \ - const struct man_node *n, \ + struct man_node *n, \ const struct man_meta *meta struct termact { @@ -56,9 +57,6 @@ struct termact { #define MAN_NOTEXT (1 << 0) /* Never has text children. */ }; -static int a2width(const struct termp *, const char *); -static size_t a2height(const struct termp *, const char *); - static void print_man_nodelist(DECL_ARGS); static void print_man_node(DECL_ARGS); static void print_man_head(struct termp *, const void *); @@ -116,7 +114,6 @@ static const struct termact termacts[MAN_MAX] = { { pre_I, NULL, 0 }, /* I */ { pre_alternate, NULL, 0 }, /* IR */ { pre_alternate, NULL, 0 }, /* RI */ - { pre_ign, NULL, MAN_NOTEXT }, /* na */ { pre_sp, NULL, MAN_NOTEXT }, /* sp */ { pre_literal, NULL, 0 }, /* nf */ { pre_literal, NULL, 0 }, /* fi */ @@ -184,29 +181,6 @@ terminal_man(void *arg, const struct man *man) } } - -static size_t -a2height(const struct termp *p, const char *cp) -{ - struct roffsu su; - - if ( ! a2roffsu(cp, &su, SCALE_VS)) - SCALE_VS_INIT(&su, atoi(cp)); - - return(term_vspan(p, &su)); -} - -static int -a2width(const struct termp *p, const char *cp) -{ - struct roffsu su; - - if ( ! a2roffsu(cp, &su, SCALE_EN)) - return(-1); - - return((int)term_hspan(p, &su)); -} - /* * Printing leading vertical space before a block. * This is used for the paragraph macros. @@ -288,14 +262,16 @@ pre_literal(DECL_ARGS) static int pre_PD(DECL_ARGS) { + struct roffsu su; n = n->child; - if (0 == n) { + if (n == NULL) { mt->pardist = 1; return(0); } assert(MAN_TEXT == n->type); - mt->pardist = atoi(n->string); + if (a2roffsu(n->string, &su, SCALE_VS)) + mt->pardist = term_vspan(p, &su); return(0); } @@ -303,7 +279,7 @@ static int pre_alternate(DECL_ARGS) { enum termfont font[2]; - const struct man_node *nn; + struct man_node *nn; int savelit, i; switch (n->tok) { @@ -423,9 +399,10 @@ pre_ft(DECL_ARGS) static int pre_in(DECL_ARGS) { - int len, less; - size_t v; + struct roffsu su; const char *cp; + size_t v; + int less; term_newln(p); @@ -444,10 +421,10 @@ pre_in(DECL_ARGS) else cp--; - if ((len = a2width(p, ++cp)) < 0) + if ( ! a2roffsu(++cp, &su, SCALE_EN)) return(0); - v = (size_t)len; + v = term_hspan(p, &su); if (less < 0) p->offset -= p->offset > v ? v : p->offset; @@ -455,6 +432,8 @@ pre_in(DECL_ARGS) p->offset += v; else p->offset = v; + if (p->offset > SHRT_MAX) + p->offset = term_len(p, p->defindent); return(0); } @@ -462,9 +441,8 @@ pre_in(DECL_ARGS) static int pre_sp(DECL_ARGS) { - char *s; - size_t i, len; - int neg; + struct roffsu su; + int i, len; if ((NULL == n->prev && n->parent)) { switch (n->parent->tok) { @@ -484,29 +462,20 @@ pre_sp(DECL_ARGS) } } - neg = 0; - switch (n->tok) { - case MAN_br: + if (n->tok == MAN_br) len = 0; - break; - default: - if (NULL == n->child) { - len = 1; - break; - } - s = n->child->string; - if ('-' == *s) { - neg = 1; - s++; - } - len = a2height(p, s); - break; + else if (n->child == NULL) + len = 1; + else { + if ( ! a2roffsu(n->child->string, &su, SCALE_VS)) + su.scale = 1.0; + len = term_vspan(p, &su); } - if (0 == len) + if (len == 0) term_newln(p); - else if (neg) - p->skipvsp += len; + else if (len < 0) + p->skipvsp -= len; else for (i = 0; i < len; i++) term_vspace(p); @@ -517,9 +486,9 @@ pre_sp(DECL_ARGS) static int pre_HP(DECL_ARGS) { - size_t len, one; - int ival; + struct roffsu su; const struct man_node *nn; + int len; switch (n->type) { case MAN_BLOCK: @@ -536,25 +505,21 @@ pre_HP(DECL_ARGS) p->trailspace = 2; } - len = mt->lmargin[mt->lmargincur]; - ival = -1; - /* Calculate offset. */ - if (NULL != (nn = n->parent->head->child)) - if ((ival = a2width(p, nn->string)) >= 0) - len = (size_t)ival; - - one = term_len(p, 1); - if (len < one) - len = one; + if ((nn = n->parent->head->child) != NULL && + a2roffsu(nn->string, &su, SCALE_EN)) { + len = term_hspan(p, &su); + if (len < 0 && (size_t)(-len) > mt->offset) + len = -mt->offset; + else if (len > SHRT_MAX) + len = term_len(p, p->defindent); + mt->lmargin[mt->lmargincur] = len; + } else + len = mt->lmargin[mt->lmargincur]; p->offset = mt->offset; p->rmargin = mt->offset + len; - - if (ival >= 0) - mt->lmargin[mt->lmargincur] = (size_t)ival; - return(1); } @@ -595,9 +560,9 @@ pre_PP(DECL_ARGS) static int pre_IP(DECL_ARGS) { + struct roffsu su; const struct man_node *nn; - size_t len; - int savelit, ival; + int len, savelit; switch (n->type) { case MAN_BODY: @@ -614,28 +579,23 @@ pre_IP(DECL_ARGS) return(1); } - len = mt->lmargin[mt->lmargincur]; - ival = -1; - /* Calculate the offset from the optional second argument. */ - if (NULL != (nn = n->parent->head->child)) - if (NULL != (nn = nn->next)) - if ((ival = a2width(p, nn->string)) >= 0) - len = (size_t)ival; + if ((nn = n->parent->head->child) != NULL && + (nn = nn->next) != NULL && + a2roffsu(nn->string, &su, SCALE_EN)) { + len = term_hspan(p, &su); + if (len < 0 && (size_t)(-len) > mt->offset) + len = -mt->offset; + else if (len > SHRT_MAX) + len = term_len(p, p->defindent); + mt->lmargin[mt->lmargincur] = len; + } else + len = mt->lmargin[mt->lmargincur]; switch (n->type) { case MAN_HEAD: - /* Handle zero-width lengths. */ - if (0 == len) - len = term_len(p, 1); - p->offset = mt->offset; p->rmargin = mt->offset + len; - if (ival < 0) - break; - - /* Set the saved left-margin. */ - mt->lmargin[mt->lmargincur] = (size_t)ival; savelit = MANT_LITERAL & mt->fl; mt->fl &= ~MANT_LITERAL; @@ -681,9 +641,9 @@ post_IP(DECL_ARGS) static int pre_TP(DECL_ARGS) { - const struct man_node *nn; - size_t len; - int savelit, ival; + struct roffsu su; + struct man_node *nn; + int len, savelit; switch (n->type) { case MAN_HEAD: @@ -700,22 +660,22 @@ pre_TP(DECL_ARGS) return(1); } - len = (size_t)mt->lmargin[mt->lmargincur]; - ival = -1; - /* Calculate offset. */ - if (NULL != (nn = n->parent->head->child)) - if (nn->string && 0 == (MAN_LINE & nn->flags)) - if ((ival = a2width(p, nn->string)) >= 0) - len = (size_t)ival; + if ((nn = n->parent->head->child) != NULL && + nn->string != NULL && ! (MAN_LINE & nn->flags) && + a2roffsu(nn->string, &su, SCALE_EN)) { + len = term_hspan(p, &su); + if (len < 0 && (size_t)(-len) > mt->offset) + len = -mt->offset; + else if (len > SHRT_MAX) + len = term_len(p, p->defindent); + mt->lmargin[mt->lmargincur] = len; + } else + len = mt->lmargin[mt->lmargincur]; switch (n->type) { case MAN_HEAD: - /* Handle zero-length properly. */ - if (0 == len) - len = term_len(p, 1); - p->offset = mt->offset; p->rmargin = mt->offset + len; @@ -734,9 +694,6 @@ pre_TP(DECL_ARGS) if (savelit) mt->fl |= MANT_LITERAL; - if (ival >= 0) - mt->lmargin[mt->lmargincur] = (size_t)ival; - return(0); case MAN_BODY: p->offset = mt->offset + len; @@ -881,8 +838,7 @@ post_SH(DECL_ARGS) static int pre_RS(DECL_ARGS) { - int ival; - size_t sz; + struct roffsu su; switch (n->type) { case MAN_BLOCK: @@ -894,13 +850,16 @@ pre_RS(DECL_ARGS) break; } - sz = term_len(p, p->defindent); + n = n->parent->head; + n->aux = SHRT_MAX + 1; + if (n->child != NULL && a2roffsu(n->child->string, &su, SCALE_EN)) + n->aux = term_hspan(p, &su); + if (n->aux < 0 && (size_t)(-n->aux) > mt->offset) + n->aux = -mt->offset; + else if (n->aux > SHRT_MAX) + n->aux = term_len(p, p->defindent); - if (NULL != (n = n->parent->head->child)) - if ((ival = a2width(p, n->string)) >= 0) - sz = (size_t)ival; - - mt->offset += sz; + mt->offset += n->aux; p->offset = mt->offset; p->rmargin = p->maxrmargin; @@ -914,8 +873,6 @@ pre_RS(DECL_ARGS) static void post_RS(DECL_ARGS) { - int ival; - size_t sz; switch (n->type) { case MAN_BLOCK: @@ -927,13 +884,7 @@ post_RS(DECL_ARGS) break; } - sz = term_len(p, p->defindent); - - if (NULL != (n = n->parent->head->child)) - if ((ival = a2width(p, n->string)) >= 0) - sz = (size_t)ival; - - mt->offset = mt->offset < sz ? 0 : mt->offset - sz; + mt->offset -= n->parent->head->aux; p->offset = mt->offset; if (--mt->lmarginsz < MAXMARGINS) @@ -998,7 +949,7 @@ print_man_node(DECL_ARGS) * Tables are preceded by a newline. Then process a * table line, which will cause line termination, */ - if (TBL_SPAN_FIRST & n->span->flags) + if (n->span->prev == NULL) term_newln(p); term_tbl(p, n->span); return; @@ -1056,10 +1007,10 @@ static void print_man_nodelist(DECL_ARGS) { - print_man_node(p, mt, n, meta); - if ( ! n->next) - return; - print_man_nodelist(p, mt, n->next, meta); + while (n != NULL) { + print_man_node(p, mt, n, meta); + n = n->next; + } } static void diff --git a/contrib/mdocml/man_validate.c b/contrib/mdocml/man_validate.c index 5688bb548aaf..93ee9b3f208b 100644 --- a/contrib/mdocml/man_validate.c +++ b/contrib/mdocml/man_validate.c @@ -1,7 +1,7 @@ /* $OpenBSD$ */ /* * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2010, 2012, 2013, 2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2010, 2012-2015 Ingo Schwarze <schwarze@openbsd.org> * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -38,10 +38,6 @@ typedef void (*v_check)(CHKARGS); -static void check_eq0(CHKARGS); -static void check_eq2(CHKARGS); -static void check_le1(CHKARGS); -static void check_le5(CHKARGS); static void check_par(CHKARGS); static void check_part(CHKARGS); static void check_root(CHKARGS); @@ -53,6 +49,7 @@ static void post_vs(CHKARGS); static void post_fi(CHKARGS); static void post_ft(CHKARGS); static void post_nf(CHKARGS); +static void post_OP(CHKARGS); static void post_TH(CHKARGS); static void post_UC(CHKARGS); static void post_UR(CHKARGS); @@ -79,7 +76,6 @@ static v_check man_valids[MAN_MAX] = { NULL, /* I */ NULL, /* IR */ NULL, /* RI */ - check_eq0, /* na */ post_vs, /* sp */ post_nf, /* nf */ post_fi, /* fi */ @@ -87,11 +83,11 @@ static v_check man_valids[MAN_MAX] = { check_part, /* RS */ NULL, /* DT */ post_UC, /* UC */ - check_le1, /* PD */ + NULL, /* PD */ post_AT, /* AT */ NULL, /* in */ post_ft, /* ft */ - check_eq2, /* OP */ + post_OP, /* OP */ post_nf, /* EX */ post_fi, /* EE */ post_UR, /* UR */ @@ -172,29 +168,27 @@ check_text(CHKARGS) n->line, n->pos + (p - cp), NULL); } -#define INEQ_DEFINE(x, ineq, name) \ -static void \ -check_##name(CHKARGS) \ -{ \ - if (n->nchild ineq (x)) \ - return; \ - mandoc_vmsg(MANDOCERR_ARGCOUNT, man->parse, n->line, n->pos, \ - "line arguments %s %d (have %d)", \ - #ineq, (x), n->nchild); \ -} +static void +post_OP(CHKARGS) +{ -INEQ_DEFINE(0, ==, eq0) -INEQ_DEFINE(2, ==, eq2) -INEQ_DEFINE(1, <=, le1) -INEQ_DEFINE(5, <=, le5) + if (n->nchild == 0) + mandoc_msg(MANDOCERR_OP_EMPTY, man->parse, + n->line, n->pos, "OP"); + else if (n->nchild > 2) { + n = n->child->next->next; + mandoc_vmsg(MANDOCERR_ARG_EXCESS, man->parse, + n->line, n->pos, "OP ... %s", n->string); + } +} static void post_UR(CHKARGS) { - if (MAN_HEAD == n->type && 1 != n->nchild) - mandoc_vmsg(MANDOCERR_ARGCOUNT, man->parse, n->line, - n->pos, "line arguments eq 1 (have %d)", n->nchild); + if (n->type == MAN_HEAD && n->child == NULL) + mandoc_vmsg(MANDOCERR_UR_NOHEAD, man->parse, + n->line, n->pos, "UR"); check_part(man, n); } @@ -243,19 +237,15 @@ post_ft(CHKARGS) n->line, n->pos, "ft %s", cp); *cp = '\0'; } - - if (1 < n->nchild) - mandoc_vmsg(MANDOCERR_ARGCOUNT, man->parse, n->line, - n->pos, "want one child (have %d)", n->nchild); } static void check_part(CHKARGS) { - if (MAN_BODY == n->type && 0 == n->nchild) - mandoc_msg(MANDOCERR_ARGCWARN, man->parse, n->line, - n->pos, "want children (have none)"); + if (n->type == MAN_BODY && n->child == NULL) + mandoc_msg(MANDOCERR_BLK_EMPTY, man->parse, + n->line, n->pos, man_macronames[n->tok]); } static void @@ -312,8 +302,6 @@ post_TH(CHKARGS) struct man_node *nb; const char *p; - check_le5(man, n); - free(man->meta.title); free(man->meta.vol); free(man->meta.source); @@ -379,6 +367,8 @@ post_TH(CHKARGS) if (n && (n = n->next)) man->meta.source = mandoc_strdup(n->string); + else if (man->defos != NULL) + man->meta.source = mandoc_strdup(man->defos); /* TITLE MSEC DATE SOURCE ->VOL<- */ /* If missing, use the default VOL name for MSEC. */ @@ -389,6 +379,10 @@ post_TH(CHKARGS) (NULL != (p = mandoc_a2msec(man->meta.msec)))) man->meta.vol = mandoc_strdup(p); + if (n != NULL && (n = n->next) != NULL) + mandoc_vmsg(MANDOCERR_ARG_EXCESS, man->parse, + n->line, n->pos, "TH ... %s", n->string); + /* * Remove the `TH' node after we've processed it for our * meta-data. @@ -400,9 +394,7 @@ static void post_nf(CHKARGS) { - check_eq0(man, n); - - if (MAN_LITERAL & man->flags) + if (man->flags & MAN_LITERAL) mandoc_msg(MANDOCERR_NF_SKIP, man->parse, n->line, n->pos, "nf"); @@ -413,8 +405,6 @@ static void post_fi(CHKARGS) { - check_eq0(man, n); - if ( ! (MAN_LITERAL & man->flags)) mandoc_msg(MANDOCERR_FI_SKIP, man->parse, n->line, n->pos, "fi"); @@ -500,11 +490,6 @@ static void post_vs(CHKARGS) { - if (n->tok == MAN_br) - check_eq0(man, n); - else - check_le1(man, n); - if (NULL != n->prev) return; diff --git a/contrib/mdocml/mandoc.1 b/contrib/mdocml/mandoc.1 index 45a6b0cf7e64..e218ed7af89c 100644 --- a/contrib/mdocml/mandoc.1 +++ b/contrib/mdocml/mandoc.1 @@ -1,7 +1,7 @@ -.\" $Id: mandoc.1,v 1.128 2014/12/02 11:31:51 schwarze Exp $ +.\" $Id: mandoc.1,v 1.155 2015/02/23 13:31:03 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> -.\" Copyright (c) 2012, 2014 Ingo Schwarze <schwarze@openbsd.org> +.\" Copyright (c) 2012, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -15,7 +15,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: December 2 2014 $ +.Dd $Mdocdate: February 23 2015 $ .Dt MANDOC 1 .Os .Sh NAME @@ -23,7 +23,7 @@ .Nd format and display UNIX manuals .Sh SYNOPSIS .Nm mandoc -.Op Fl acfhklV +.Op Fl acfhkl .Sm off .Op Fl I Cm os Li = Ar name .Sm on @@ -85,6 +85,9 @@ Override the default operating system for the .Xr mdoc 7 .Sq \&Os +and for the +.Xr man 7 +.Sq \&TH macro. .It Fl h Display only the SYNOPSIS lines. @@ -147,8 +150,6 @@ See for available formats. Defaults to .Fl T Ns Cm locale . -.It Fl V -Print version and exit. .It Fl W Ns Ar level Specify the minimum message .Ar level @@ -159,12 +160,13 @@ can be .Cm warning , .Cm error , or -.Cm fatal . -The default is -.Fl W Ns Cm fatal ; -.Fl W Ns Cm all +.Cm unsupp ; +.Cm all is an alias for -.Fl W Ns Cm warning . +.Cm warning . +By default, +.Nm +is silent. See .Sx EXIT STATUS and @@ -317,9 +319,6 @@ Emboldened characters are rendered as The special characters documented in .Xr mandoc_char 7 are rendered best-effort in an ASCII equivalent. -If no equivalent is found, -.Sq \&? -is used instead. .Pp Output width is limited to 78 visible columns unless literal input lines exceed this limit. @@ -340,7 +339,7 @@ for example overfull lines or ugly line breaks. .It Cm width Ns = Ns Ar width The output width is set to .Ar width , -which will normalise to \(>=60. +which will normalise to \(>=58. .El .Ss HTML Output Output produced by @@ -529,19 +528,25 @@ At least one warning occurred, but no error, and .Fl W Ns Cm warning was specified. .It 3 -At least one parsing error occurred, but no fatal error, and +At least one parsing error occurred, +but no unsupported feature was encountered, and .Fl W Ns Cm error or .Fl W Ns Cm warning was specified. .It 4 -A fatal parsing error occurred. +At least one unsupported feature was encountered, and +.Fl W Ns Cm unsupp , +.Fl W Ns Cm error +or +.Fl W Ns Cm warning +was specified. .It 5 Invalid command line arguments were specified. No input files have been read. .It 6 -An operating system error occurred, for example memory exhaustion or an -error accessing input files. +An operating system error occurred, for example exhaustion +of memory, file descriptors, or process table entries. Such errors cause .Nm to exit at once, possibly in the middle of parsing or formatting a file. @@ -600,22 +605,34 @@ fields. .Pp Message levels have the following meanings: .Bl -tag -width "warning" -.It Cm syserr -Opening or reading an input file failed, so the parser cannot -even be started and no output is produced from that input file. -.It Cm fatal -The parser is unable to parse a given input file at all. -No formatted output is produced from that input file. -.It Cm error -An input file contains syntax that cannot be safely interpreted, -either because it is invalid or because +.It Cm unsupp +An input file uses unsupported low-level +.Xr roff 7 +features. +The output may be incomplete and/or misformatted, +so using GNU troff instead of .Nm -does not implement it yet. +to process the file may be preferable. +.It Cm error +An input file contains invalid syntax that cannot be safely interpreted. By discarding part of the input or inserting missing tokens, the parser is able to continue, and the error does not prevent generation of formatted output, but typically, preparing that output involves information loss, broken document structure -or unintended formatting. +or unintended formatting, no matter whether +.Nm +or GNU troff is used. +In many cases, the output of +.Nm +and GNU troff is identical, but in some, +.Nm +is more resilient than GNU troff with respect to malformed input. +.Pp +Non-existent or unreadable input files are also reported on the +.Cm error +level. +In that case, the parser cannot even be started and no output +is produced from those input files. .It Cm warning An input file uses obsolete, discouraged or non-portable syntax. All the same, the meaning of the input is unambiguous and a correct @@ -626,10 +643,12 @@ formatting tools instead of .El .Pp Messages of the -.Cm warning +.Cm warning , +.Cm error , and -.Cm error -levels are hidden unless their level, or a lower level, is requested using a +.Cm unsupp +levels except those about non-existent or unreadable input files +are hidden unless their level, or a lower level, is requested using a .Fl W option or .Fl T Ns Cm lint @@ -708,9 +727,9 @@ macro occurs after some non-prologue macro, but still takes effect. .Pq mdoc The .Ic \&Dt -macro can only occur before the first non-prologue macro -because traditional formatters write the page header -before parsing the document body. +macro appears after the first non-prologue macro. +Traditional formatters cannot handle this because +they write the page header before parsing the document body. Even though this technical restriction does not apply to .Nm , traditional semantics is preserved. @@ -752,17 +771,33 @@ This may confuse .Xr makewhatis 8 and .Xr apropos 1 . -.It Sy "bad NAME section contents" +.It Sy "NAME section without name" +.Pq mdoc +The NAME section does not contain any +.Ic \&Nm +child macro. +.It Sy "NAME section without description" .Pq mdoc -The last node in the NAME section is not an +The NAME section lacks the mandatory .Ic \&Nd -macro, or any preceding macro is not -.Ic \&Nm , -or the NAME section is completely empty. -This may confuse -.Xr makewhatis 8 +child macro. +.It Sy "description not at the end of NAME" +.Pq mdoc +The NAME section does contain an +.Ic \&Nd +child macro, but other content follows it. +.It Sy "bad NAME section content" +.Pq mdoc +The NAME section contains plain text or macros other than +.Ic \&Nm and -.Xr apropos 1 . +.Ic \&Nd . +.It Sy "missing description line, using \(dq\(dq" +.Pq mdoc +The +.Ic \&Nd +macro lacks the required argument. +The title line of the manual will end after the dash. .It Sy "sections out of conventional order" .Pq mdoc A standard section occurs after another section it usually precedes. @@ -809,7 +844,7 @@ manual for replacements. .Pq mdoc The name of a macro that is not callable appears on a macro line. It is printed verbatim. -If the intention is to call it, move it to its own line; +If the intention is to call it, move it to its own input line; otherwise, escape it by prepending .Sq \e& . .It Sy "skipping paragraph macro" @@ -968,6 +1003,18 @@ clause. .It Sy "skipping empty macro" .Pq mdoc The indicated macro has no arguments and hence no effect. +.It Sy "empty block" +.Pq mdoc , man +A +.Ic \&Bd , +.Ic \&Bk , +.Ic \&Bl , +.Ic \&D1 , +.Ic \&Dl , +.Ic \&RS , +or +.Ic \&UR +block contains nothing in its body and will produce no output. .It Sy "empty argument, using 0n" .Pq mdoc The required width is missing after @@ -977,12 +1024,6 @@ or .Fl offset or .Fl width. -.It Sy "argument count wrong" -.Pq mdoc , man -The indicated macro has too few or too many arguments. -The syntax tree will contain the wrong number of arguments as given. -Formatting behaviour depends on the specific macro in question. -Note that the same message may also occur as an ERROR, see below. .It Sy "missing display type, using -ragged" .Pq mdoc The @@ -1014,6 +1055,12 @@ The macro is called without an argument before .Ic \&Nm has first been called with an argument. +.It Sy "missing function name, using \(dq\(dq" +.Pq mdoc +The +.Ic \&Fo +macro is called without an argument. +No function name is printed. .It Sy "empty head in list item" .Pq mdoc In a @@ -1041,21 +1088,18 @@ list, an .Ic \&It block is empty. An empty list item is shown. -.It Sy "missing font type" +.It Sy "missing font type, using \efR" .Pq mdoc A .Ic \&Bf macro has no argument. -It switches to the default font, -.Cm \efR . -.It Sy "unknown font type" +It switches to the default font. +.It Sy "unknown font type, using \efR" .Pq mdoc The .Ic \&Bf argument is invalid. -The default font -.Cm \efR -is used instead. +The default font is used instead. .It Sy "nothing follows prefix" .Pq mdoc A @@ -1064,6 +1108,14 @@ macro has no argument, or only one argument and no macro follows on the same input line. This defeats its purpose; in particular, spacing is not suppressed before the text or macros following on the next input line. +.It Sy "empty reference block" +.Pq mdoc +An +.Ic \&Rs +macro is immediately followed by an +.Ic \&Re +macro on the next input line. +Such an empty block does not produce any output. .It Sy "missing -std argument, adding it" .Pq mdoc An @@ -1078,6 +1130,18 @@ The utility assumes .Fl std even when it is not specified, but other implementations may not. +.It Sy "missing option string, using \(dq\(dq" +.Pq man +The +.Ic \&OP +macro is invoked without any argument. +An empty pair of square brackets is shown. +.It Sy "missing resource identifier, using \(dq\(dq" +.Pq man +The +.Ic \&UR +macro is invoked without any argument. +An empty pair of angle brackets is shown. .It Sy "missing eqn box, using \(dq\(dq" .Pq eqn A diacritic mark or a binary operator is found, @@ -1142,6 +1206,15 @@ list has a .Fl width argument. That has no effect. +.It Sy "wrong number of cells" +In a line of a +.Ic \&Bl Fl column +list, the number of tabs or +.Ic \&Ta +macros is less than the number expected from the list header line +or exceeds the expected number by more than one. +Missing cells remain empty, and all cells exceeding the number of +columns are joined into one single cell. .It Sy "unknown AT&T UNIX version" .Pq mdoc An @@ -1193,6 +1266,12 @@ request or a layout modifier has an unknown .Ar font argument. +.It Sy "odd number of characters in request" +.Pq roff +A +.Ic \&tr +request contains an odd number of characters. +The last character is mapped to the blank character. .El .Ss "Warnings related to plain text" .Bl -ohang @@ -1249,23 +1328,86 @@ its value is implicitly set to the empty string. However, defining strings explicitly before use keeps the code more readable. .El -.Ss "Errors related to equations" -.Bl -inset -compact -.It "unexpected equation scope closure" -.It "equation scope open on exit" -.It "overlapping equation scopes" -.It "unexpected end of equation" +.Ss "Warnings related to tables" +.Bl -ohang +.It Sy "tbl line starts with span" +.Pq tbl +The first cell in a table layout line is a horizontal span +.Pq Sq Cm s . +Data provided for this cell is ignored, and nothing is printed in the cell. +.It Sy "tbl column starts with span" +.Pq tbl +The first line of a table layout specification +requests a vertical span +.Pq Sq Cm ^ . +Data provided for this cell is ignored, and nothing is printed in the cell. +.It Sy "skipping vertical bar in tbl layout" +.Pq tbl +A table layout specification contains more than two consecutive vertical bars. +A double bar is printed, all additional bars are discarded. .El .Ss "Errors related to tables" -.Bl -inset -compact -.It "bad table syntax" -.It "bad table option" -.It "bad table layout" -.It "no table layout cells specified" -.It "no table data cells specified" -.It "ignore data in cell" -.It "data block still open" -.It "ignoring extra data cells" +.Bl -ohang +.It Sy "non-alphabetic character in tbl options" +.Pq tbl +The table options line contains a character other than a letter, +blank, or comma where the beginning of an option name is expected. +The character is ignored. +.It Sy "skipping unknown tbl option" +.Pq tbl +The table options line contains a string of letters that does not +match any known option name. +The word is ignored. +.It Sy "missing tbl option argument" +.Pq tbl +A table option that requires an argument is not followed by an +opening parenthesis, or the opening parenthesis is immediately +followed by a closing parenthesis. +The option is ignored. +.It Sy "wrong tbl option argument size" +.Pq tbl +A table option argument contains an invalid number of characters. +Both the option and the argument are ignored. +.It Sy "empty tbl layout" +.Pq tbl +A table layout specification is completely empty, +specifying zero lines and zero columns. +As a fallback, a single left-justified column is used. +.It Sy "invalid character in tbl layout" +.Pq tbl +A table layout specification contains a character that can neither +be interpreted as a layout key character nor as a layout modifier, +or a modifier precedes the first key. +The invalid character is discarded. +.It Sy "unmatched parenthesis in tbl layout" +.Pq tbl +A table layout specification contains an opening parenthesis, +but no matching closing parenthesis. +The rest of the input line, starting from the parenthesis, has no effect. +.It Sy "tbl without any data cells" +.Pq tbl +A table does not contain any data cells. +It will probably produce no output. +.It Sy "ignoring data in spanned tbl cell" +.Pq tbl +A table cell is marked as a horizontal span +.Pq Sq Cm s +or vertical span +.Pq Sq Cm ^ +in the table layout, but it contains data. +The data is ignored. +.It Sy "ignoring extra tbl data cells" +.Pq tbl +A data line contains more cells than the corresponding layout line. +The data in the extra cells is ignored. +.It Sy "data block open at end of tbl" +.Pq tbl +A data block is opened with +.Cm T{ , +but never closed with a matching +.Cm T} . +The remaining data lines of the table are all put into one cell, +and any remaining cells stay empty. .El .Ss "Errors related to roff, mdoc, and man code" .Bl -ohang @@ -1307,6 +1449,11 @@ or macro. It may be mistyped or unsupported. The request or macro is discarded including its arguments. +.It Sy "skipping insecure request" +.Pq roff +An input file attempted to run a shell command +or to read or write an external file. +Such attempts are denied for security reasons. .It Sy "skipping item outside list" .Pq mdoc , eqn An @@ -1343,6 +1490,16 @@ right delimiter or closing brace, or the end of an equation, table, or .Xr roff 7 conditional request is encountered but no matching block is open. The offending request or macro is discarded. +.It Sy "fewer RS blocks open, skipping" +.Pq man +The +.Ic \&RE +macro is invoked with an argument, but less than the specified number of +.Ic \&RS +blocks is open. +The +.Ic \&RE +macro is discarded. .It Sy "inserting missing end of block" .Pq mdoc , tbl Various @@ -1351,7 +1508,7 @@ macros as well as tables require explicit closing by dedicated macros. A block that doesn't support bad nesting ends before all of its children are properly closed. The open child nodes are closed implicitly. -.It Sy "scope open on exit" +.It Sy "appending missing end of block" .Pq mdoc , man , eqn , tbl , roff At the end of the document, an explicit .Xr mdoc 7 @@ -1401,12 +1558,6 @@ When parsing for a request or a user-defined macro name to be called, only the escape sequence is discarded. The characters preceding it are used as the request or macro name, the characters following it are used as the arguments to the request or macro. -.It Sy "argument count wrong" -.Pq mdoc , man , roff -The indicated request or macro has too few or too many arguments. -The syntax tree will contain the wrong number of arguments as given. -Formatting behaviour depends on the specific request or macro in question. -Note that the same message may also occur as a WARNING, see above. .It Sy "NOT IMPLEMENTED: Bd -file" .Pq mdoc For security reasons, the @@ -1457,6 +1608,29 @@ or .Ic \&gsize statement has a non-numeric or negative argument or no argument at all. The invalid request or statement is ignored. +.It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq" +.Pq roff +For security reasons, +.Nm +allows +.Ic \&so +file inclusion requests only with relative paths +and only without ascending to any parent directory. +By requesting the inclusion of a sensitive file, a malicious document +might otherwise trick a privileged user into inadvertently displaying +the file on the screen, revealing the file content to bystanders. +.Nm +only shows the path as it appears behind +.Ic \&so . +.It Sy ".so request failed" +.Pq roff +Servicing a +.Ic \&so +request requires reading an external file, but the file could not be +opened. +.Nm +only shows the path as it appears behind +.Ic \&so . .It Sy "skipping all arguments" .Pq mdoc , man , eqn , roff An @@ -1466,7 +1640,10 @@ An .Ic \&Ef , .Ic \&Ek , .Ic \&El , +.Ic \&Lp , +.Ic \&Pp , .Ic \&Re , +.Ic \&Rs , or .Ic \&Ud macro, an @@ -1484,19 +1661,57 @@ or .Ic \&EN macro, or a .Xr roff 7 +.Ic \&br , +.Ic \&fi , +or +.Ic \&nf +request or .Sq \&.. block closing request is invoked with at least one argument. All arguments are ignored. .It Sy "skipping excess arguments" -.Pq mdoc , roff -The -.Ic \&Bf -macro is invoked with more than one argument, or a request of the +.Pq mdoc , man , roff +A macro or request is invoked with too many arguments: +.Bl -dash -offset 2n -width 2n -compact +.It +.Ic \&Fo , +.Ic \&PD , +.Ic \&RS , +.Ic \&UR , +.Ic \&ft , +or +.Ic \&sp +with more than one argument +.It +.Ic \&An +with another argument after +.Fl split +or +.Fl nosplit +.It +.Ic \&RE +with more than one argument or with a non-integer argument +.It +.Ic \&OP +or a request of the .Ic \&de -family is invoked with more than two arguments. +family with more than two arguments +.It +.Ic \&Dt +with more than three arguments +.It +.Ic \&TH +with more than five arguments +.It +.Ic \&Bd , +.Ic \&Bk , +or +.Ic \&Bl +with invalid arguments +.El The excess arguments are ignored. .El -.Ss FATAL errors +.Ss Unsupported features .Bl -ohang .It Sy "input too large" .Pq mdoc , man @@ -1506,116 +1721,45 @@ cannot handle input files larger than its arbitrary size limit of 2^31 bytes (2 Gigabytes). Since useful manuals are always small, this is not a problem in practice. Parsing is aborted as soon as the condition is detected. -.It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq" +.It Sy "unsupported control character" .Pq roff -For security reasons, +An ASCII control character supported by other +.Xr roff 7 +implementations but not by .Nm -allows -.Ic \&so -file inclusion requests only with relative paths -and only without ascending to any parent directory. -By requesting the inclusion of a sensitive file, a malicious document -might otherwise trick a privileged user into inadvertently displaying -the file on the screen, revealing the file content to bystanders. -The parser exits immediately. -.It Sy ".so request failed" +was found in an input file. +It is replaced by a question mark. +.It Sy "unsupported roff request" .Pq roff -Servicing a -.Ic \&so -request requires reading an external file. -While trying to do so, an -.Xr open 2 , -.Xr stat 2 , -or -.Xr read 2 -system call failed. -The parser exits immediately. -Before showing this message, -.Nm -always shows another message explaining why the system call failed. -.El -.Sh COMPATIBILITY -This section summarises -.Nm -compatibility with GNU troff. -Each input and output format is separately noted. -.Ss ASCII Compatibility -.Bl -bullet -compact -.It -Unrenderable unicode codepoints specified with -.Sq \e[uNNNN] -escapes are printed as -.Sq \&? -in mandoc. -In GNU troff, these raise an error. -.It -The -.Sq \&Bd \-literal -and -.Sq \&Bd \-unfilled -macros of -.Xr mdoc 7 -in -.Fl T Ns Cm ascii -are synonyms, as are \-filled and \-ragged. -.It -In historic GNU troff, the -.Sq \&Pa -.Xr mdoc 7 -macro does not underline when scoped under an -.Sq \&It -in the FILES section. -This behaves correctly in -.Nm . -.It -A list or display following the -.Sq \&Ss -.Xr mdoc 7 -macro in -.Fl T Ns Cm ascii -does not assert a prior vertical break, just as it doesn't with -.Sq \&Sh . -.It -The -.Sq \&na -.Xr man 7 -macro in -.Fl T Ns Cm ascii -has no effect. -.It -Words aren't hyphenated. -.El -.Ss HTML Compatibility -.Bl -bullet -compact -.It -The -.Sq \efP -escape will revert the font to the previous -.Sq \ef -escape, not to the last rendered decoration, which is now dictated by -CSS instead of hard-coded. -It also will not span past the current scope, -for the same reason. -Note that in -.Sx ASCII Output -mode, this will work fine. -.It -The +An input file contains a +.Xr roff 7 +request supported by GNU troff or Heirloom troff but not by +.Nm , +and it is likely that this will cause information loss +or considerable misformatting. +.It Sy "eqn delim option in tbl" +.Pq eqn , tbl +The options line of a table defines equation delimiters. +Any equation source code contained in the table will be printed unformatted. +.It Sy "unsupported table layout modifier" +.Pq tbl +A table layout specification contains an +.Sq Cm m +modifier. +The modifier is discarded. +.It Sy "ignoring macro in table" +.Pq tbl , mdoc , man +A table contains an invocation of an .Xr mdoc 7 -.Sq \&Bl \-hang -and -.Sq \&Bl \-tag -list types render similarly (no break following overreached left-hand -side) due to the expressive constraints of HTML. -.It -The +or .Xr man 7 -.Sq IP -and -.Sq TP -lists render similarly. +macro or of an undefined macro. +The macro is ignored, and its arguments are handled +as if they were a text line. .El .Sh SEE ALSO +.Xr apropos 1 , +.Xr man 1 , .Xr eqn 7 , .Xr man 7 , .Xr mandoc_char 7 , @@ -1626,32 +1770,15 @@ lists render similarly. The .Nm utility was written by -.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . -.Sh CAVEATS +.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv +and is maintained by +.An Ingo Schwarze Aq Mt schwarze@openbsd.org . +.Sh BUGS In -.Fl T Ns Cm html -and -.Fl T Ns Cm xhtml , +.Fl T Ns Cm html , the maximum size of an element attribute is determined by .Dv BUFSIZ , which is usually 1024 bytes. Be aware of this when setting long link formats such as .Fl O Ns Cm style Ns = Ns Ar really/long/link . -.Pp -Nesting elements within next-line element scopes of -.Fl m Ns Cm an , -such as -.Sq br -within an empty -.Sq B , -will confuse -.Fl T Ns Cm html -and -.Fl T Ns Cm xhtml -and cause them to forget the formatting of the prior next-line scope. -.Pp -The -.Sq \(aq -control character is an alias for the standard macro control character -and does not emit a line-break as stipulated in GNU troff. diff --git a/contrib/mdocml/mandoc.3 b/contrib/mdocml/mandoc.3 index f05fdac997bf..a41e25b934d0 100644 --- a/contrib/mdocml/mandoc.3 +++ b/contrib/mdocml/mandoc.3 @@ -1,7 +1,7 @@ -.\" $Id: mandoc.3,v 1.29 2014/11/26 23:42:14 schwarze Exp $ +.\" $Id: mandoc.3,v 1.31 2015/01/15 04:26:40 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> -.\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org> +.\" Copyright (c) 2010, 2013, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -15,7 +15,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: November 26 2014 $ +.Dd $Mdocdate: January 15 2015 $ .Dt MANDOC 3 .Os .Sh NAME @@ -39,11 +39,10 @@ .Nm mparse_strlevel .Nm mparse_wait , .Nd mandoc macro compiler library -.Sh LIBRARY -.Lb libmandoc .Sh SYNOPSIS .In sys/types.h .In mandoc.h +.Pp .Fd "#define ASCII_NBRSP" .Fd "#define ASCII_HYPH" .Fd "#define ASCII_BREAK" @@ -176,10 +175,15 @@ initiate a parsing sequence with and .Fn mparse_alloc ; .It -parse files or file descriptors with +open a file with +.Xr open 2 +or +.Fn mparse_open ; +.It +parse it with .Fn mparse_readfd ; .It -retrieve a parsed syntax tree, if the parse was successful, with +retrieve the syntax tree with .Fn mparse_result ; .It iterate over parse nodes with @@ -206,7 +210,7 @@ and .Ss Types .Bl -ohang .It Vt "enum mandocerr" -A fatal error, error, or warning message during parsing. +An error or warning message during parsing. .It Vt "enum mandoclevel" A classification of an .Vt "enum mandocerr" @@ -227,7 +231,7 @@ This may be used across parsed input if .Fn mparse_reset is called between parses. .It Vt "mandocmsg" -A prototype for a function to handle fatal error, error, and warning +A prototype for a function to handle error and warning messages emitted by the parser. .El .Ss Functions @@ -331,7 +335,7 @@ This is for example useful in to quickly build minimal databases. .It Ar wlevel Can be set to -.Dv MANDOCLEVEL_FATAL , +.Dv MANDOCLEVEL_BADARG , .Dv MANDOCLEVEL_ERROR , or .Dv MANDOCLEVEL_WARNING . @@ -413,17 +417,12 @@ Declared in implemented in .Pa read.c . .It Fn mparse_readfd -Parse a file or file descriptor. -If -.Va fd -is -1, open -.Va fname -with +Parse a file descriptor opened with +.Xr open 2 +or .Fn mparse_open . -Otherwise, -.Va fname -is assumed to be the name associated with -.Va fd . +Pass the associated filename in +.Va fname . Calls .Fn mparse_wait before returning. @@ -444,14 +443,7 @@ implemented in .Pa read.c . .It Fn mparse_result Obtain the result of a parse. -Only successful parses -.Po -i.e., those where -.Fn mparse_readfd -returned less than MANDOCLEVEL_FATAL -.Pc -should invoke this function, in which case one of the three pointers will -be filled in. +One of the three pointers will be filled in. Declared in .In mandoc.h , implemented in diff --git a/contrib/mdocml/mandoc.c b/contrib/mdocml/mandoc.c index 2ec179ea2302..0619420cb196 100644 --- a/contrib/mdocml/mandoc.c +++ b/contrib/mdocml/mandoc.c @@ -1,7 +1,7 @@ -/* $Id: mandoc.c,v 1.88 2014/10/28 13:24:44 schwarze Exp $ */ +/* $Id: mandoc.c,v 1.92 2015/02/20 23:55:10 schwarze Exp $ */ /* - * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2011, 2012, 2013, 2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2008-2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv> + * Copyright (c) 2011-2015 Ingo Schwarze <schwarze@openbsd.org> * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -156,16 +156,18 @@ mandoc_escape(const char **end, const char **start, int *sz) /* FALLTHROUGH */ case 'D': /* FALLTHROUGH */ - case 'o': - /* FALLTHROUGH */ case 'R': /* FALLTHROUGH */ case 'X': /* FALLTHROUGH */ case 'Z': - if ('\0' == **start) - return(ESCAPE_ERROR); gly = ESCAPE_IGNORE; + /* FALLTHROUGH */ + case 'o': + if (**start == '\0') + return(ESCAPE_ERROR); + if (gly == ESCAPE_ERROR) + gly = ESCAPE_OVERSTRIKE; term = **start; *start = ++*end; break; @@ -225,7 +227,7 @@ mandoc_escape(const char **end, const char **start, int *sz) /* See +/- counts as a sign. */ if ('+' == **end || '-' == **end || ASCII_HYPH == **end) - (*end)++; + *start = ++*end; switch (**end) { case '(': @@ -240,6 +242,14 @@ mandoc_escape(const char **end, const char **start, int *sz) *start = ++*end; term = '\''; break; + case '3': + /* FALLTHROUGH */ + case '2': + /* FALLTHROUGH */ + case '1': + *sz = (*end)[-1] == 's' && + isdigit((unsigned char)(*end)[1]) ? 2 : 1; + break; default: *sz = 1; break; @@ -480,6 +490,8 @@ time2a(time_t t) int isz; tm = localtime(&t); + if (tm == NULL) + return(NULL); /* * Reserve space: diff --git a/contrib/mdocml/mandoc.db.5 b/contrib/mdocml/mandoc.db.5 index e3452ffe89db..60908bc4d397 100644 --- a/contrib/mdocml/mandoc.db.5 +++ b/contrib/mdocml/mandoc.db.5 @@ -1,4 +1,4 @@ -.\" $Id: mandoc.db.5,v 1.2 2014/09/03 18:09:14 schwarze Exp $ +.\" $Id: mandoc.db.5,v 1.3 2014/12/30 21:34:57 schwarze Exp $ .\" .\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org> .\" @@ -14,7 +14,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: September 3 2014 $ +.Dd $Mdocdate: December 30 2014 $ .Dt MANDOC.DB 5 .Os .Sh NAME @@ -117,14 +117,14 @@ documented in The string found in those contexts. .El .Sh FILES -.Bl -tag -width /usr/share/mandoc.db -compact -.It Pa /usr/share/mandoc.db +.Bl -tag -width /usr/share/man/mandoc.db -compact +.It Pa /usr/share/man/mandoc.db The manual page database for the base system. -.It Pa /usr/X11R6/mandoc.db +.It Pa /usr/X11R6/man/mandoc.db The same for the .Xr X 7 Window System. -.It Pa /usr/local/mandoc.db +.It Pa /usr/local/man/mandoc.db The same for .Xr packages 7 . .El diff --git a/contrib/mdocml/mandoc.h b/contrib/mdocml/mandoc.h index e4cdccbc43f3..eb8a1aa6f298 100644 --- a/contrib/mdocml/mandoc.h +++ b/contrib/mdocml/mandoc.h @@ -1,7 +1,7 @@ -/* $Id: mandoc.h,v 1.176 2014/12/01 08:05:52 schwarze Exp $ */ +/* $Id: mandoc.h,v 1.201 2015/02/23 13:31:04 schwarze Exp $ */ /* * Copyright (c) 2010, 2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2010-2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2010-2015 Ingo Schwarze <schwarze@openbsd.org> * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -31,7 +31,7 @@ enum mandoclevel { MANDOCLEVEL_RESERVED, MANDOCLEVEL_WARNING, /* warnings: syntax, whitespace, etc. */ MANDOCLEVEL_ERROR, /* input has been thrown away */ - MANDOCLEVEL_FATAL, /* input is borked */ + MANDOCLEVEL_UNSUPP, /* input needs unimplemented features */ MANDOCLEVEL_BADARG, /* bad argument in invocation */ MANDOCLEVEL_SYSERR, /* system error */ MANDOCLEVEL_MAX @@ -65,7 +65,11 @@ enum mandocerr { MANDOCERR_DOC_EMPTY, /* no document body */ MANDOCERR_SEC_BEFORE, /* content before first section header: macro */ MANDOCERR_NAMESEC_FIRST, /* first section is not NAME: Sh title */ - MANDOCERR_NAMESEC_BAD, /* bad NAME section contents: macro */ + MANDOCERR_NAMESEC_NONM, /* NAME section without name */ + MANDOCERR_NAMESEC_NOND, /* NAME section without description */ + MANDOCERR_NAMESEC_ND, /* description not at the end of NAME */ + MANDOCERR_NAMESEC_BAD, /* bad NAME section content: macro */ + MANDOCERR_ND_EMPTY, /* missing description line, using "" */ MANDOCERR_SEC_ORDER, /* sections out of conventional order: Sh title */ MANDOCERR_SEC_REP, /* duplicate section title: Sh title */ MANDOCERR_SEC_MSEC, /* unexpected section: Sh title for ... only */ @@ -91,18 +95,22 @@ enum mandocerr { MANDOCERR_REQ_EMPTY, /* skipping empty request: request */ MANDOCERR_COND_EMPTY, /* conditional request controls empty scope */ MANDOCERR_MACRO_EMPTY, /* skipping empty macro: macro */ + MANDOCERR_BLK_EMPTY, /* empty block: macro */ MANDOCERR_ARG_EMPTY, /* empty argument, using 0n: macro arg */ - MANDOCERR_ARGCWARN, /* argument count wrong */ MANDOCERR_BD_NOTYPE, /* missing display type, using -ragged: Bd */ MANDOCERR_BL_LATETYPE, /* list type is not the first argument: Bl arg */ MANDOCERR_BL_NOWIDTH, /* missing -width in -tag list, using 8n */ MANDOCERR_EX_NONAME, /* missing utility name, using "": Ex */ + MANDOCERR_FO_NOHEAD, /* missing function name, using "": Fo */ MANDOCERR_IT_NOHEAD, /* empty head in list item: Bl -type It */ MANDOCERR_IT_NOBODY, /* empty list item: Bl -type It */ MANDOCERR_BF_NOFONT, /* missing font type, using \fR: Bf */ MANDOCERR_BF_BADFONT, /* unknown font type, using \fR: Bf font */ MANDOCERR_PF_SKIP, /* nothing follows prefix: Pf arg */ + MANDOCERR_RS_EMPTY, /* empty reference block: Rs */ MANDOCERR_ARG_STD, /* missing -std argument, adding it: macro */ + MANDOCERR_OP_EMPTY, /* missing option string, using "": OP */ + MANDOCERR_UR_NOHEAD, /* missing resource identifier, using "": UR */ MANDOCERR_EQN_NOBOX, /* missing eqn box, using "": op */ /* related to bad arguments */ @@ -112,12 +120,14 @@ enum mandocerr { MANDOCERR_BD_REP, /* skipping duplicate display type: Bd -type */ MANDOCERR_BL_REP, /* skipping duplicate list type: Bl -type */ MANDOCERR_BL_SKIPW, /* skipping -width argument: Bl -type */ + MANDOCERR_BL_COL, /* wrong number of cells */ MANDOCERR_AT_BAD, /* unknown AT&T UNIX version: At version */ MANDOCERR_FA_COMMA, /* comma in function argument: arg */ MANDOCERR_FN_PAREN, /* parenthesis in function name: arg */ MANDOCERR_RS_BAD, /* invalid content in Rs block: macro */ MANDOCERR_SM_BAD, /* invalid Boolean argument: macro arg */ MANDOCERR_FT_BAD, /* unknown font, skipping request: ft font */ + MANDOCERR_TR_ODD, /* odd number of characters in request: tr char */ /* related to plain text */ MANDOCERR_FI_BLANK, /* blank line in fill mode, using .sp */ @@ -127,65 +137,61 @@ enum mandocerr { MANDOCERR_ESC_BAD, /* invalid escape sequence: esc */ MANDOCERR_STR_UNDEF, /* undefined string, using "": name */ - MANDOCERR_ERROR, /* ===== start of errors ===== */ + /* related to tables */ + MANDOCERR_TBLLAYOUT_SPAN, /* tbl line starts with span */ + MANDOCERR_TBLLAYOUT_DOWN, /* tbl column starts with span */ + MANDOCERR_TBLLAYOUT_VERT, /* skipping vertical bar in tbl layout */ - /* related to equations */ - MANDOCERR_EQNNSCOPE, /* unexpected equation scope closure*/ - MANDOCERR_EQNSCOPE, /* equation scope open on exit */ - MANDOCERR_EQNBADSCOPE, /* overlapping equation scopes */ - MANDOCERR_EQNEOF, /* unexpected end of equation */ + MANDOCERR_ERROR, /* ===== start of errors ===== */ /* related to tables */ - MANDOCERR_TBL, /* bad table syntax */ - MANDOCERR_TBLOPT, /* bad table option */ - MANDOCERR_TBLLAYOUT, /* bad table layout */ - MANDOCERR_TBLNOLAYOUT, /* no table layout cells specified */ - MANDOCERR_TBLNODATA, /* no table data cells specified */ - MANDOCERR_TBLIGNDATA, /* ignore data in cell */ - MANDOCERR_TBLBLOCK, /* data block still open */ - MANDOCERR_TBLEXTRADAT, /* ignoring extra data cells */ + MANDOCERR_TBLOPT_ALPHA, /* non-alphabetic character in tbl options */ + MANDOCERR_TBLOPT_BAD, /* skipping unknown tbl option: option */ + MANDOCERR_TBLOPT_NOARG, /* missing tbl option argument: option */ + MANDOCERR_TBLOPT_ARGSZ, /* wrong tbl option argument size: option */ + MANDOCERR_TBLLAYOUT_NONE, /* empty tbl layout */ + MANDOCERR_TBLLAYOUT_CHAR, /* invalid character in tbl layout: char */ + MANDOCERR_TBLLAYOUT_PAR, /* unmatched parenthesis in tbl layout */ + MANDOCERR_TBLDATA_NONE, /* tbl without any data cells */ + MANDOCERR_TBLDATA_SPAN, /* ignoring data in spanned tbl cell: data */ + MANDOCERR_TBLDATA_EXTRA, /* ignoring extra tbl data cells: data */ + MANDOCERR_TBLDATA_BLK, /* data block open at end of tbl: macro */ /* related to document structure and macros */ + MANDOCERR_FILE, /* cannot open file */ MANDOCERR_ROFFLOOP, /* input stack limit exceeded, infinite loop? */ - MANDOCERR_BADCHAR, /* skipping bad character: number */ + MANDOCERR_CHAR_BAD, /* skipping bad character: number */ MANDOCERR_MACRO, /* skipping unknown macro: macro */ + MANDOCERR_REQ_INSEC, /* skipping insecure request: request */ MANDOCERR_IT_STRAY, /* skipping item outside list: It ... */ MANDOCERR_TA_STRAY, /* skipping column outside column list: Ta */ MANDOCERR_BLK_NOTOPEN, /* skipping end of block that is not open */ + MANDOCERR_RE_NOTOPEN, /* fewer RS blocks open, skipping: RE arg */ MANDOCERR_BLK_BROKEN, /* inserting missing end of block: macro ... */ MANDOCERR_BLK_NOEND, /* appending missing end of block: macro */ /* related to request and macro arguments */ MANDOCERR_NAMESC, /* escaped character not allowed in a name: name */ - MANDOCERR_ARGCOUNT, /* argument count wrong */ MANDOCERR_BD_FILE, /* NOT IMPLEMENTED: Bd -file */ MANDOCERR_BL_NOTYPE, /* missing list type, using -item: Bl */ MANDOCERR_NM_NONAME, /* missing manual name, using "": Nm */ MANDOCERR_OS_UNAME, /* uname(3) system call failed, using UNKNOWN */ MANDOCERR_ST_BAD, /* unknown standard specifier: St standard */ MANDOCERR_IT_NONUM, /* skipping request without numeric argument */ + MANDOCERR_SO_PATH, /* NOT IMPLEMENTED: .so with absolute path or ".." */ + MANDOCERR_SO_FAIL, /* .so request failed */ MANDOCERR_ARG_SKIP, /* skipping all arguments: macro args */ MANDOCERR_ARG_EXCESS, /* skipping excess arguments: macro ... args */ MANDOCERR_DIVZERO, /* divide by zero */ - MANDOCERR_FATAL, /* ===== start of fatal errors ===== */ + MANDOCERR_UNSUPP, /* ===== start of unsupported features ===== */ MANDOCERR_TOOLARGE, /* input too large */ - MANDOCERR_SO_PATH, /* NOT IMPLEMENTED: .so with absolute path or ".." */ - MANDOCERR_SO_FAIL, /* .so request failed */ - - /* ===== system errors ===== */ - - MANDOCERR_SYSDUP, /* cannot dup file descriptor */ - MANDOCERR_SYSEXEC, /* cannot exec */ - MANDOCERR_SYSEXIT, /* gunzip failed with code */ - MANDOCERR_SYSFORK, /* cannot fork */ - MANDOCERR_SYSOPEN, /* cannot open file */ - MANDOCERR_SYSPIPE, /* cannot open pipe */ - MANDOCERR_SYSREAD, /* cannot read file */ - MANDOCERR_SYSSIG, /* gunzip died from signal */ - MANDOCERR_SYSSTAT, /* cannot stat file */ - MANDOCERR_SYSWAIT, /* wait failed */ + MANDOCERR_CHAR_UNSUPP, /* unsupported control character: number */ + MANDOCERR_REQ_UNSUPP, /* unsupported roff request: request */ + MANDOCERR_TBLOPT_EQN, /* eqn delim option in tbl: arg */ + MANDOCERR_TBLLAYOUT_MOD, /* unsupported tbl layout modifier: m */ + MANDOCERR_TBLMACRO, /* ignoring macro in table: macro */ MANDOCERR_MAX }; @@ -193,7 +199,6 @@ enum mandocerr { struct tbl_opts { char tab; /* cell-separator */ char decimal; /* decimal point */ - int linesize; int opts; #define TBL_OPT_CENTRE (1 << 0) #define TBL_OPT_EXPAND (1 << 1) @@ -202,19 +207,10 @@ struct tbl_opts { #define TBL_OPT_ALLBOX (1 << 4) #define TBL_OPT_NOKEEP (1 << 5) #define TBL_OPT_NOSPACE (1 << 6) +#define TBL_OPT_NOWARN (1 << 7) int cols; /* number of columns */ -}; - -/* - * The head of a table specifies all of its columns. When formatting a - * tbl_span, iterate over these and plug in data from the tbl_span when - * appropriate, using tbl_cell as a guide to placement. - */ -struct tbl_head { - int ident; /* 0 <= unique id < cols */ - int vert; /* width of preceding vertical line */ - struct tbl_head *next; - struct tbl_head *prev; + int lvert; /* width of left vertical line */ + int rvert; /* width of right vertical line */ }; enum tbl_cellt { @@ -235,9 +231,10 @@ enum tbl_cellt { */ struct tbl_cell { struct tbl_cell *next; - int vert; /* width of preceding vertical line */ + int vert; /* width of subsequent vertical line */ enum tbl_cellt pos; size_t spacing; + int col; /* column number, starting from 0 */ int flags; #define TBL_CELL_TALIGN (1 << 0) /* t, T */ #define TBL_CELL_BALIGN (1 << 1) /* d, D */ @@ -247,7 +244,6 @@ struct tbl_cell { #define TBL_CELL_UP (1 << 5) /* u, U */ #define TBL_CELL_WIGN (1 << 6) /* z, Z */ #define TBL_CELL_WMAX (1 << 7) /* x, X */ - struct tbl_head *head; }; /* @@ -257,7 +253,7 @@ struct tbl_row { struct tbl_row *next; struct tbl_cell *first; struct tbl_cell *last; - int vert; /* trailing vertical line */ + int vert; /* width of left vertical line */ }; enum tbl_datt { @@ -292,16 +288,13 @@ enum tbl_spant { */ struct tbl_span { struct tbl_opts *opts; - struct tbl_head *head; struct tbl_row *layout; /* layout row */ struct tbl_dat *first; struct tbl_dat *last; + struct tbl_span *prev; + struct tbl_span *next; int line; /* parse line */ - int flags; -#define TBL_SPAN_FIRST (1 << 0) -#define TBL_SPAN_LAST (1 << 1) enum tbl_spant pos; - struct tbl_span *next; }; enum eqn_boxt { @@ -408,7 +401,8 @@ enum mandoc_esc { ESCAPE_NUMBERED, /* a numbered glyph */ ESCAPE_UNICODE, /* a unicode codepoint */ ESCAPE_NOSPACE, /* suppress space if the last on a line */ - ESCAPE_SKIPCHAR /* skip the next character */ + ESCAPE_SKIPCHAR, /* skip the next character */ + ESCAPE_OVERSTRIKE /* overstrike all chars in the argument */ }; typedef void (*mandocmsg)(enum mandocerr, enum mandoclevel, diff --git a/contrib/mdocml/mandoc_char.7 b/contrib/mdocml/mandoc_char.7 index 8d8356652ef5..806b990f1755 100644 --- a/contrib/mdocml/mandoc_char.7 +++ b/contrib/mdocml/mandoc_char.7 @@ -1,4 +1,4 @@ -.\" $Id: mandoc_char.7,v 1.56 2013/12/26 17:23:42 schwarze Exp $ +.\" $Id: mandoc_char.7,v 1.59 2015/01/20 19:39:34 schwarze Exp $ .\" .\" Copyright (c) 2003 Jason McIntyre <jmc@openbsd.org> .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> @@ -16,7 +16,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: December 26 2013 $ +.Dd $Mdocdate: January 20 2015 $ .Dt MANDOC_CHAR 7 .Os .Sh NAME @@ -210,7 +210,7 @@ Lines: .It \e(ba Ta \(ba Ta bar .It \e(br Ta \(br Ta box rule .It \e(ul Ta \(ul Ta underscore -.It \e(rl Ta \(rl Ta overline +.It \e(rn Ta \(rn Ta overline .It \e(bb Ta \(bb Ta broken bar .It \e(sl Ta \(sl Ta forward slash .It \e(rs Ta \(rs Ta backward slash @@ -273,7 +273,7 @@ Quotes: .El .Pp Brackets: -.Bl -column "xxbracketrightbpx" Rendered Description -offset indent -compact +.Bl -column "xxbracketrightbtx" Rendered Description -offset indent -compact .It Em Input Ta Em Rendered Ta Em Description .It \e(lB Ta \(lB Ta left bracket .It \e(rB Ta \(rB Ta right bracket @@ -284,30 +284,30 @@ Brackets: .It \e(bv Ta \(bv Ta brace extension .It \e[braceex] Ta \[braceex] Ta brace extension .It \e[bracketlefttp] Ta \[bracketlefttp] Ta top-left hooked bracket -.It \e[bracketleftbp] Ta \[bracketleftbp] Ta bottom-left hooked bracket +.It \e[bracketleftbt] Ta \[bracketleftbt] Ta bottom-left hooked bracket .It \e[bracketleftex] Ta \[bracketleftex] Ta left hooked bracket extension .It \e[bracketrighttp] Ta \[bracketrighttp] Ta top-right hooked bracket -.It \e[bracketrightbp] Ta \[bracketrightbp] Ta bottom-right hooked bracket +.It \e[bracketrightbt] Ta \[bracketrightbt] Ta bottom-right hooked bracket .It \e[bracketrightex] Ta \[bracketrightex] Ta right hooked bracket extension .It \e(lt Ta \(lt Ta top-left hooked brace .It \e[bracelefttp] Ta \[bracelefttp] Ta top-left hooked brace .It \e(lk Ta \(lk Ta mid-left hooked brace .It \e[braceleftmid] Ta \[braceleftmid] Ta mid-left hooked brace .It \e(lb Ta \(lb Ta bottom-left hooked brace -.It \e[braceleftbp] Ta \[braceleftbp] Ta bottom-left hooked brace +.It \e[braceleftbt] Ta \[braceleftbt] Ta bottom-left hooked brace .It \e[braceleftex] Ta \[braceleftex] Ta left hooked brace extension .It \e(rt Ta \(rt Ta top-left hooked brace .It \e[bracerighttp] Ta \[bracerighttp] Ta top-right hooked brace .It \e(rk Ta \(rk Ta mid-right hooked brace .It \e[bracerightmid] Ta \[bracerightmid] Ta mid-right hooked brace .It \e(rb Ta \(rb Ta bottom-right hooked brace -.It \e[bracerightbp] Ta \[bracerightbp] Ta bottom-right hooked brace +.It \e[bracerightbt] Ta \[bracerightbt] Ta bottom-right hooked brace .It \e[bracerightex] Ta \[bracerightex] Ta right hooked brace extension .It \e[parenlefttp] Ta \[parenlefttp] Ta top-left hooked parenthesis -.It \e[parenleftbp] Ta \[parenleftbp] Ta bottom-left hooked parenthesis +.It \e[parenleftbt] Ta \[parenleftbt] Ta bottom-left hooked parenthesis .It \e[parenleftex] Ta \[parenleftex] Ta left hooked parenthesis extension .It \e[parenrighttp] Ta \[parenrighttp] Ta top-right hooked parenthesis -.It \e[parenrightbp] Ta \[parenrightbp] Ta bottom-right hooked parenthesis +.It \e[parenrightbt] Ta \[parenrightbt] Ta bottom-right hooked parenthesis .It \e[parenrightex] Ta \[parenrightex] Ta right hooked parenthesis extension .El .Pp @@ -352,7 +352,7 @@ Mathematical: .It \e(-+ Ta \(-+ Ta minus-plus .It \e(+- Ta \(+- Ta plus-minus .It \e[t+-] Ta \[t+-] Ta plus-minus (text) -.It \e(pc Ta \(pc Ta centre-dot +.It \e(pc Ta \(pc Ta center-dot .It \e(mu Ta \(mu Ta multiply .It \e[tmu] Ta \[tmu] Ta multiply (text) .It \e(c* Ta \(c* Ta circle-multiply @@ -369,11 +369,11 @@ Mathematical: .It \e(!= Ta \(!= Ta not equal .It \e(== Ta \(== Ta equivalent .It \e(ne Ta \(ne Ta not equivalent -.It \e(=~ Ta \(=~ Ta congruent -.It \e(-~ Ta \(-~ Ta asymptotically congruent -.It \e(ap Ta \(ap Ta asymptotically similar -.It \e(~~ Ta \(~~ Ta approximately similar -.It \e(~= Ta \(~= Ta approximately equal +.It \e(ap Ta \(ap Ta tilde operator +.It \e(|= Ta \(|= Ta asymptotically equal +.It \e(=~ Ta \(=~ Ta approximately equal +.It \e(~~ Ta \(~~ Ta almost equal +.It \e(~= Ta \(~= Ta almost equal .It \e(pt Ta \(pt Ta proportionate .It \e(es Ta \(es Ta empty set .It \e(mo Ta \(mo Ta element diff --git a/contrib/mdocml/mandoc_escape.3 b/contrib/mdocml/mandoc_escape.3 index f381b6297fd0..fec298b87a04 100644 --- a/contrib/mdocml/mandoc_escape.3 +++ b/contrib/mdocml/mandoc_escape.3 @@ -1,4 +1,4 @@ -.\" $Id: mandoc_escape.3,v 1.2 2014/10/28 14:06:31 schwarze Exp $ +.\" $Id: mandoc_escape.3,v 1.3 2015/01/21 20:33:25 schwarze Exp $ .\" .\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org> .\" @@ -14,14 +14,12 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: October 28 2014 $ +.Dd $Mdocdate: January 21 2015 $ .Dt MANDOC_ESCAPE 3 .Os .Sh NAME .Nm mandoc_escape .Nd parse roff escape sequences -.Sh LIBRARY -.Lb libmandoc .Sh SYNOPSIS .In sys/types.h .In mandoc.h @@ -119,8 +117,8 @@ in turn contain other escape sequences, for error detection internally by the .Xr roff 7 parser part of the -.Lb libmandoc , -see the file +.Xr mandoc 3 +library, see the file .Pa roff.c , .It above all externally by the @@ -256,6 +254,10 @@ Such ASCII character escape sequences can be rendered using the function described in the .Xr mchars_alloc 3 manual. +.It Dv ESCAPE_OVERSTRIKE +The escape sequence +.Ic \eo +followed by an argument delimited by an arbitrary character. .It Dv ESCAPE_IGNORE .Bl -bullet -width 2n .It @@ -288,7 +290,6 @@ The escape sequences .Ic \eA , .Ic \eb , .Ic \eD , -.Ic \eo , .Ic \eR , .Ic \eX , and diff --git a/contrib/mdocml/mandoc_headers.3 b/contrib/mdocml/mandoc_headers.3 index aa8754e46ec8..79d90fff58d2 100644 --- a/contrib/mdocml/mandoc_headers.3 +++ b/contrib/mdocml/mandoc_headers.3 @@ -47,7 +47,7 @@ HTML formatters search tools .El .Pp -Note that mere usage of an opaque type does +Note that mere usage of an opaque struct type does .Em not require inclusion of the header where that type is defined. .Ss Parser interface @@ -204,7 +204,11 @@ are included, the same file should not include any formatter headers. Requires .In sys/types.h for -.Vt size_t . +.Vt size_t +and +.Qq Pa mandoc.h +for +.Vt enum mandocerr . .Pp Provides .Vt enum rofferr , @@ -222,8 +226,7 @@ from .Pa roff.c for function prototypes. Uses the types -.Vt enum mandocerr , -.Vt struct tbl_span , +.Vt struct tbl_span and .Vt struct eqn from diff --git a/contrib/mdocml/mandocdb.c b/contrib/mdocml/mandocdb.c index a2fac2027d50..9270e5cd1afe 100644 --- a/contrib/mdocml/mandocdb.c +++ b/contrib/mdocml/mandocdb.c @@ -1,7 +1,7 @@ -/* $Id: mandocdb.c,v 1.179 2014/12/09 07:29:42 schwarze Exp $ */ +/* $Id: mandocdb.c,v 1.185 2015/02/27 16:22:09 schwarze Exp $ */ /* * Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2011, 2012, 2013, 2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2011-2015 Ingo Schwarze <schwarze@openbsd.org> * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -350,7 +350,8 @@ mandocdb(int argc, char *argv[]) mpages_info.alloc = mlinks_info.alloc = hash_alloc; mpages_info.calloc = mlinks_info.calloc = hash_calloc; - mpages_info.free = mlinks_info.free = hash_free; + mpages_info.free = mlinks_info.free = hash_free; + mpages_info.data = mlinks_info.data = NULL; mpages_info.key_offset = offsetof(struct mpage, inodev); mlinks_info.key_offset = offsetof(struct mlink, file); @@ -441,7 +442,7 @@ mandocdb(int argc, char *argv[]) exitcode = (int)MANDOCLEVEL_OK; mchars = mchars_alloc(); - mp = mparse_alloc(mparse_options, MANDOCLEVEL_FATAL, NULL, + mp = mparse_alloc(mparse_options, MANDOCLEVEL_BADARG, NULL, mchars, NULL); ohash_init(&mpages, 6, &mpages_info); ohash_init(&mlinks, 6, &mlinks_info); @@ -612,7 +613,11 @@ treescan(void) say(path, "&realpath"); continue; } - if (strstr(buf, basedir) != buf) { + if (strstr(buf, basedir) != buf +#ifdef HOMEBREWDIR + && strstr(buf, HOMEBREWDIR) != buf +#endif + ) { if (warnings) say("", "%s: outside base directory", buf); continue; @@ -667,7 +672,8 @@ treescan(void) say(path, "Skip pdf"); continue; } else if ( ! use_all && - ((FORM_SRC == dform && strcmp(fsec, dsec)) || + ((FORM_SRC == dform && + strncmp(fsec, dsec, strlen(dsec))) || (FORM_CAT == dform && strcmp(fsec, "0")))) { if (warnings) say(path, "Wrong filename suffix"); @@ -817,6 +823,10 @@ filescan(const char *file) start = buf; else if (strstr(buf, basedir) == buf) start = buf + strlen(basedir); +#ifdef HOMEBREWDIR + else if (strstr(buf, HOMEBREWDIR) == buf) + start = buf; +#endif else { exitcode = (int)MANDOCLEVEL_BADARG; say("", "%s: outside base directory", buf); @@ -852,6 +862,7 @@ filescan(const char *file) if (strlcpy(mlink->file, start, sizeof(mlink->file)) >= sizeof(mlink->file)) { say(start, "Filename too long"); + free(mlink); return; } @@ -1100,11 +1111,11 @@ mpages_merge(struct mparse *mp) char *cp; int fd; unsigned int pslot; - enum mandoclevel lvl; str_info.alloc = hash_alloc; str_info.calloc = hash_calloc; str_info.free = hash_free; + str_info.data = NULL; str_info.key_offset = offsetof(struct str, key); if ( ! nodb) @@ -1113,7 +1124,7 @@ mpages_merge(struct mparse *mp) mpage = ohash_first(&mpages, &pslot); while (mpage != NULL) { mlinks_undupe(mpage); - if (mpage->mlinks == NULL) { + if ((mlink = mpage->mlinks) == NULL) { mpage = ohash_next(&mpages, &pslot); continue; } @@ -1126,22 +1137,19 @@ mpages_merge(struct mparse *mp) man = NULL; sodest = NULL; - mparse_open(mp, &fd, mpage->mlinks->file); + mparse_open(mp, &fd, mlink->file); if (fd == -1) { - say(mpage->mlinks->file, "&open"); + say(mlink->file, "&open"); goto nextpage; } /* - * Try interpreting the file as mdoc(7) or man(7) - * source code, unless it is already known to be - * formatted. Fall back to formatted mode. + * Interpret the file as mdoc(7) or man(7) source + * code, unless it is known to be formatted. */ - if (mpage->mlinks->dform != FORM_CAT || - mpage->mlinks->fform != FORM_CAT) { - lvl = mparse_readfd(mp, fd, mpage->mlinks->file); - if (lvl < MANDOCLEVEL_FATAL) - mparse_result(mp, &mdoc, &man, &sodest); + if (mlink->dform != FORM_CAT || mlink->fform != FORM_CAT) { + mparse_readfd(mp, fd, mlink->file); + mparse_result(mp, &mdoc, &man, &sodest); } if (sodest != NULL) { @@ -1158,7 +1166,6 @@ mpages_merge(struct mparse *mp) /* The .so target exists. */ mpage_dest = mlink_dest->mpage; - mlink = mpage->mlinks; while (1) { mlink->mpage = mpage_dest; @@ -1198,26 +1205,20 @@ mpages_merge(struct mparse *mp) mandoc_strdup(mdoc_meta(mdoc)->title); } else if (man != NULL) { mpage->form = FORM_SRC; - mpage->sec = - mandoc_strdup(man_meta(man)->msec); - mpage->arch = - mandoc_strdup(mpage->mlinks->arch); - mpage->title = - mandoc_strdup(man_meta(man)->title); + mpage->sec = mandoc_strdup(man_meta(man)->msec); + mpage->arch = mandoc_strdup(mlink->arch); + mpage->title = mandoc_strdup(man_meta(man)->title); } else { mpage->form = FORM_CAT; - mpage->sec = - mandoc_strdup(mpage->mlinks->dsec); - mpage->arch = - mandoc_strdup(mpage->mlinks->arch); - mpage->title = - mandoc_strdup(mpage->mlinks->name); + mpage->sec = mandoc_strdup(mlink->dsec); + mpage->arch = mandoc_strdup(mlink->arch); + mpage->title = mandoc_strdup(mlink->name); } putkey(mpage, mpage->sec, TYPE_sec); if (*mpage->arch != '\0') putkey(mpage, mpage->arch, TYPE_arch); - for (mlink = mpage->mlinks; mlink; mlink = mlink->next) { + for ( ; mlink != NULL; mlink = mlink->next) { if ('\0' != *mlink->dsec) putkey(mpage, mlink->dsec, TYPE_sec); if ('\0' != *mlink->fsec) @@ -1243,11 +1244,12 @@ mpages_merge(struct mparse *mp) mlink_check(mpage, mlink); dbadd(mpage); + mlink = mpage->mlinks; nextpage: if (mparse_wait(mp) != MANDOCLEVEL_OK) { exitcode = (int)MANDOCLEVEL_SYSERR; - say(mpage->mlinks->file, "&wait gunzip"); + say(mlink->file, "&wait gunzip"); } ohash_delete(&strings); ohash_delete(&names); diff --git a/contrib/mdocml/manpage.c b/contrib/mdocml/manpage.c index 70eb06b69ceb..999f3d324762 100644 --- a/contrib/mdocml/manpage.c +++ b/contrib/mdocml/manpage.c @@ -1,4 +1,4 @@ -/* $Id: manpage.c,v 1.9 2014/08/17 03:24:47 schwarze Exp $ */ +/* $Id: manpage.c,v 1.10 2015/02/10 08:05:30 schwarze Exp $ */ /* * Copyright (c) 2012 Kristaps Dzonsons <kristaps@bsd.lv> * Copyright (c) 2013 Ingo Schwarze <schwarze@openbsd.org> @@ -107,7 +107,7 @@ main(int argc, char *argv[]) return(EXIT_FAILURE); for (i = 0; i < sz; i++) { - printf("%6zu %s: %s\n", + printf("%6zu %s: %s\n", i + 1, res[i].names, res[i].output); free(res[i].names); free(res[i].output); @@ -148,11 +148,11 @@ show: /* NOTREACHED */ usage: fprintf(stderr, "usage: %s [-C conf] " - "[-M paths] " + "[-M paths] " "[-m paths] " "[-S arch] " "[-s section] " - "expr ...\n", + "expr ...\n", progname); return(EXIT_FAILURE); } @@ -174,9 +174,9 @@ show(const char *cmd, const char *file) } else if (pid > 0) { dup2(fds[0], STDIN_FILENO); close(fds[1]); - cmd = NULL != getenv("MANPAGER") ? + cmd = NULL != getenv("MANPAGER") ? getenv("MANPAGER") : - (NULL != getenv("PAGER") ? + (NULL != getenv("PAGER") ? getenv("PAGER") : "more"); execlp(cmd, cmd, (char *)NULL); perror(cmd); diff --git a/contrib/mdocml/mansearch.c b/contrib/mdocml/mansearch.c index dbfbe0255fd4..27cfa65568a1 100644 --- a/contrib/mdocml/mansearch.c +++ b/contrib/mdocml/mansearch.c @@ -1,7 +1,7 @@ -/* $Id: mansearch.c,v 1.52 2014/12/06 01:23:24 schwarze Exp $ */ +/* $Id: mansearch.c,v 1.54 2015/02/27 16:02:10 schwarze Exp $ */ /* * Copyright (c) 2012 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2013, 2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2013, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -24,6 +24,7 @@ #include <errno.h> #include <fcntl.h> #include <getopt.h> +#include <glob.h> #include <limits.h> #include <regex.h> #include <stdio.h> @@ -85,7 +86,8 @@ struct match { int form; /* bit field: formatted, zipped? */ }; -static void buildnames(struct manpage *, sqlite3 *, +static void buildnames(const struct mansearch *, + struct manpage *, sqlite3 *, sqlite3_stmt *, uint64_t, const char *, int form); static char *buildoutput(sqlite3 *, sqlite3_stmt *, @@ -96,8 +98,6 @@ static void *hash_calloc(size_t, size_t, void *); static struct expr *exprcomp(const struct mansearch *, int, char *[]); static void exprfree(struct expr *); -static struct expr *exprspec(struct expr *, uint64_t, - const char *, const char *); static struct expr *exprterm(const struct mansearch *, char *, int); static int manpage_compare(const void *, const void *); static void sql_append(char **sql, size_t *sz, @@ -343,14 +343,16 @@ mansearch(const struct mansearch *search, mpage->bits = mp->bits; mpage->sec = 10; mpage->form = mp->form; - buildnames(mpage, db, s, mp->pageid, + buildnames(search, mpage, db, s, mp->pageid, paths->paths[i], mp->form); - mpage->output = TYPE_Nd & outbit ? - mp->desc : outbit ? - buildoutput(db, s2, mp->pageid, outbit) : NULL; - + if (mpage->names != NULL) { + mpage->output = TYPE_Nd & outbit ? + mp->desc : outbit ? + buildoutput(db, s2, mp->pageid, outbit) : + NULL; + cur++; + } free(mp); - cur++; } sqlite3_finalize(s); @@ -407,17 +409,19 @@ manpage_compare(const void *vp1, const void *vp2) } static void -buildnames(struct manpage *mpage, sqlite3 *db, sqlite3_stmt *s, +buildnames(const struct mansearch *search, struct manpage *mpage, + sqlite3 *db, sqlite3_stmt *s, uint64_t pageid, const char *path, int form) { - char *newnames, *prevsec, *prevarch; + glob_t globinfo; + char *firstname, *newnames, *prevsec, *prevarch; const char *oldnames, *sep1, *name, *sec, *sep2, *arch, *fsec; size_t i; - int c; + int c, globres; mpage->file = NULL; mpage->names = NULL; - prevsec = prevarch = NULL; + firstname = prevsec = prevarch = NULL; i = 1; SQL_BIND_INT64(db, s, i, pageid); while (SQLITE_ROW == (c = sqlite3_step(s))) { @@ -432,10 +436,15 @@ buildnames(struct manpage *mpage, sqlite3 *db, sqlite3_stmt *s, sep1 = ", "; } - /* Fetch the next name. */ + /* Fetch the next name, rejecting sec/arch mismatches. */ sec = (const char *)sqlite3_column_text(s, 0); + if (search->sec != NULL && strcasecmp(sec, search->sec)) + continue; arch = (const char *)sqlite3_column_text(s, 1); + if (search->arch != NULL && *arch != '\0' && + strcasecmp(arch, search->arch)) + continue; name = (const char *)sqlite3_column_text(s, 2); /* Remember the first section found. */ @@ -487,11 +496,34 @@ buildnames(struct manpage *mpage, sqlite3 *db, sqlite3_stmt *s, sep2 = *arch == '\0' ? "" : "/"; mandoc_asprintf(&mpage->file, "%s/%s%s%s%s/%s.%s", path, sep1, sec, sep2, arch, name, fsec); + if (access(mpage->file, R_OK) != -1) + continue; + + /* Handle unusual file name extensions. */ + + if (firstname == NULL) + firstname = mpage->file; + else + free(mpage->file); + mandoc_asprintf(&mpage->file, "%s/%s%s%s%s/%s.*", + path, sep1, sec, sep2, arch, name); + globres = glob(mpage->file, 0, NULL, &globinfo); + free(mpage->file); + mpage->file = globres ? NULL : + mandoc_strdup(*globinfo.gl_pathv); + globfree(&globinfo); } if (c != SQLITE_DONE) fprintf(stderr, "%s\n", sqlite3_errmsg(db)); sqlite3_reset(s); + /* If none of the files is usable, use the first name. */ + + if (mpage->file == NULL) + mpage->file = firstname; + else if (mpage->file != firstname) + free(firstname); + /* Append one final section to the names. */ if (prevsec != NULL) { @@ -645,8 +677,7 @@ exprcomp(const struct mansearch *search, int argc, char *argv[]) struct expr *first, *prev, *cur, *next; first = cur = NULL; - logic = igncase = toclose = 0; - toopen = NULL != search->sec || NULL != search->arch; + logic = igncase = toopen = toclose = 0; for (i = 0; i < argc; i++) { if (0 == strcmp("(", argv[i])) { @@ -712,17 +743,8 @@ exprcomp(const struct mansearch *search, int argc, char *argv[]) toopen = logic = igncase = 0; } - if (toopen || logic || igncase || toclose) - goto fail; - - if (NULL != search->sec || NULL != search->arch) - cur->close++; - if (NULL != search->arch) - cur = exprspec(cur, TYPE_arch, search->arch, "^(%s|any)$"); - if (NULL != search->sec) - exprspec(cur, TYPE_sec, search->sec, "^%s$"); - - return(first); + if ( ! (toopen || logic || igncase || toclose)) + return(first); fail: if (NULL != first) @@ -731,29 +753,6 @@ fail: } static struct expr * -exprspec(struct expr *cur, uint64_t key, const char *value, - const char *format) -{ - char errbuf[BUFSIZ]; - char *cp; - int irc; - - mandoc_asprintf(&cp, format, value); - cur->next = mandoc_calloc(1, sizeof(struct expr)); - cur = cur->next; - cur->and = 1; - cur->bits = key; - if (0 != (irc = regcomp(&cur->regexp, cp, - REG_EXTENDED | REG_NOSUB | REG_ICASE))) { - regerror(irc, &cur->regexp, errbuf, sizeof(errbuf)); - fprintf(stderr, "regcomp: %s\n", errbuf); - cur->substr = value; - } - free(cp); - return(cur); -} - -static struct expr * exprterm(const struct mansearch *search, char *buf, int cs) { char errbuf[BUFSIZ]; diff --git a/contrib/mdocml/mdoc.7 b/contrib/mdocml/mdoc.7 index a9b0fe2f3ac2..d4c8ccd11c4b 100644 --- a/contrib/mdocml/mdoc.7 +++ b/contrib/mdocml/mdoc.7 @@ -1,4 +1,4 @@ -.\" $Id: mdoc.7,v 1.245 2014/11/30 21:56:18 schwarze Exp $ +.\" $Id: mdoc.7,v 1.252 2015/02/23 13:31:04 schwarze Exp $ .\" .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> .\" Copyright (c) 2010, 2011, 2013 Ingo Schwarze <schwarze@openbsd.org> @@ -15,7 +15,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: November 30 2014 $ +.Dd $Mdocdate: February 23 2015 $ .Dt MDOC 7 .Os .Sh NAME @@ -454,6 +454,7 @@ in the alphabetical .Op Fl compact .It Sx \&D1 Ta indented display (one line) .It Sx \&Dl Ta indented literal display (one line) +.It Sx \&Ql Ta in-line literal display: Ql text .It Sx \&Bl , \&El Ta list block: .Fl Ar type .Op Fl width Ar val @@ -528,7 +529,6 @@ in the alphabetical .It Sx \&Dq , \&Do , \&Dc Ta enclose in typographic double quotes: Dq text .It Sx \&Qq , \&Qo , \&Qc Ta enclose in typewriter double quotes: Qq text .It Sx \&Sq , \&So , \&Sc Ta enclose in single quotes: Sq text -.It Sx \&Ql Ta single-quoted literal text: Ql text .It Sx \&Pq , \&Po , \&Pc Ta enclose in parentheses: Pq text .It Sx \&Bq , \&Bo , \&Bc Ta enclose in square brackets: Bq text .It Sx \&Brq , \&Bro , \&Brc Ta enclose in curly braces: Brq text @@ -777,7 +777,7 @@ The must be one of the following: .Bl -tag -width 13n -offset indent .It Fl centered -Produce one output line from each input line, and centre-justify each line. +Produce one output line from each input line, and center-justify each line. Using this display type is not recommended; many .Nm implementations render it poorly. @@ -822,7 +822,7 @@ which has no effect; .Cm right , which justifies to the right margin; or .Cm center , -which aligns around an imagined centre axis. +which aligns around an imagined center axis. .It A macro invocation, which selects a predefined width associated with that macro. @@ -1256,7 +1256,9 @@ Examples: .Dl \&.Dl % mandoc mdoc.7 \e(ba less .Pp See also +.Sx \&Ql , .Sx \&Bd +.Fl literal , and .Sx \&D1 . .Ss \&Do @@ -1314,38 +1316,26 @@ it should by convention be all caps. The manual section. This may be one of .Cm 1 -.Pq utilities , +.Pq General Commands , .Cm 2 -.Pq system calls , +.Pq System Calls , .Cm 3 -.Pq libraries , +.Pq Library Functions , .Cm 3p -.Pq Perl libraries , +.Pq Perl Library , .Cm 4 -.Pq devices , +.Pq Device Drivers , .Cm 5 -.Pq file formats , +.Pq File Formats , .Cm 6 -.Pq games , +.Pq Games , .Cm 7 -.Pq miscellaneous , +.Pq Miscellaneous Information , .Cm 8 -.Pq system utilities , -.Cm 9 -.Pq kernel functions , -.Cm X11 -.Pq X Window System , -.Cm X11R6 -.Pq X Window System , -.Cm unass -.Pq unassociated , -.Cm local -.Pq local system , -.Cm draft -.Pq draft manual , +.Pq System Manager's Manual , or -.Cm paper -.Pq paper . +.Cm 9 +.Pq Kernel Developer's Manual . It should correspond to the manual's filename suffix and defaults to the empty string if unspecified. .It Ar arch @@ -1768,17 +1758,18 @@ is preferred for displaying code; the .Sx \&Ic macro is used when referring to specific instructions. .Ss \&In -An -.Dq include -file. +The name of an include file. +This macro is most often used in section 2, 3, and 9 manual pages. +.Pp When invoked as the first macro on an input line in the .Em SYNOPSIS section, the argument is displayed in angle brackets and preceded by -.Dq #include , +.Qq #include , and a blank line is inserted in front if there is a preceding function declaration. -This is most often used in section 2, 3, and 9 manual pages. +In other sections, it only encloses its argument in angle brackets +and causes no line break. .Pp Examples: .Dl \&.In sys/types.h @@ -1939,11 +1930,9 @@ Examples: .Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv .Ss \&Nd A one line description of the manual's content. -This may only be invoked in the -.Em SYNOPSIS -section subsequent the -.Sx \&Nm -macro. +This is the mandatory last macro of the +.Em NAME +section and not appropriate for other sections. .Pp Examples: .Dl Pf . Sx \&Nd mdoc language reference @@ -2100,8 +2089,16 @@ Its syntax is as follows: The optional .Ar system parameter specifies the relevant operating system or environment. -Left unspecified, it defaults to the local operating system version. -This is the suggested form. +It is suggested to leave it unspecified, in which case +.Xr mandoc 1 +uses its +.Fl Ios +argument, or, if that isn't specified either, +.Fa sysname +and +.Fa release +as returned by +.Xr uname 3 . .Pp Examples: .Dl \&.Os @@ -2205,11 +2202,21 @@ See also Close quoted context opened by .Sx \&Qo . .Ss \&Ql -Format a single-quoted literal. +In-line literal display. +This can for example be used for complete command invocations and +for multi-word code fragments when more specific markup is not +appropriate and an indented display is not desired. +While +.Xr mandoc 1 +always encloses the arguments in single quotes, other formatters +usually omit the quotes on non-terminal output devices when the +arguments have three or more characters. +.Pp See also -.Sx \&Qq +.Sx \&Dl and -.Sx \&Sq . +.Sx \&Bd +.Fl literal . .Ss \&Qo Multi-line version of .Sx \&Qq . @@ -3125,50 +3132,13 @@ Manually switching the font using the font escape sequences is never required. .Sh COMPATIBILITY This section provides an incomplete list of compatibility issues -between mandoc and other troff implementations, at this time limited -to GNU troff +between mandoc and GNU troff .Pq Qq groff . -The term -.Qq historic groff -refers to groff versions before 1.17, -which featured a significant update of the -.Pa doc.tmac -file. -.Pp -Heirloom troff, the other significant troff implementation accepting -\-mdoc, is similar to historic groff. .Pp The following problematic behaviour is found in groff: -.ds hist (Historic groff only.) .Pp .Bl -dash -compact .It -Display macros -.Po -.Sx \&Bd , -.Sx \&Dl , -and -.Sx \&D1 -.Pc -may not be nested. -\*[hist] -.It -.Sx \&At -with unknown arguments produces no output at all. -\*[hist] -Newer groff and mandoc print -.Qq AT&T UNIX -and the arguments. -.It -.Sx \&Bl Fl column -does not recognise trailing punctuation characters when they immediately -precede tabulator characters, but treats them as normal text and -outputs a space before them. -.It -.Sx \&Bd Fl ragged compact -does not start a new line. -\*[hist] -.It .Sx \&Dd with non-standard arguments behaves very strangely. When there are three arguments, they are printed verbatim. @@ -3177,53 +3147,6 @@ but without any arguments the string .Dq Epoch is printed. .It -.Sx \&Fl -does not print a dash for an empty argument. -\*[hist] -.It -.Sx \&Fn -does not start a new line unless invoked as the line macro in the -.Em SYNOPSIS -section. -\*[hist] -.It -.Sx \&Fo -with -.Pf non- Sx \&Fa -children causes inconsistent spacing between arguments. -In mandoc, a single space is always inserted between arguments. -.It -.Sx \&Ft -in the -.Em SYNOPSIS -causes inconsistent vertical spacing, depending on whether a prior -.Sx \&Fn -has been invoked. -See -.Sx \&Ft -and -.Sx \&Fn -for the normalised behaviour in mandoc. -.It -.Sx \&In -ignores additional arguments and is not treated specially in the -.Em SYNOPSIS . -\*[hist] -.It -.Sx \&It -sometimes requires a -.Fl nested -flag. -\*[hist] -In new groff and mandoc, any list may be nested by default and -.Fl enum -lists will restart the sequence only for the sub-list. -.It -.Sx \&Li -followed by a delimiter is incorrectly used in some manuals -instead of properly quoting that character, which sometimes works with -historic groff. -.It .Sx \&Lk only accepts a single link-name argument; the remainder is misformatted. .It @@ -3237,19 +3160,6 @@ can only be called by other macros, but not at the beginning of a line. .Sx \&%C is not implemented (up to and including groff-1.22.2). .It -Historic groff only allows up to eight or nine arguments per macro input -line, depending on the exact situation. -Providing more arguments causes garbled output. -The number of arguments on one input line is not limited with mandoc. -.It -Historic groff has many un-callable macros. -Most of these (excluding some block-level macros) are callable -in new groff and mandoc. -.It -.Sq \(ba -(vertical bar) is not fully supported as a delimiter. -\*[hist] -.It .Sq \ef .Pq font face and @@ -3267,13 +3177,27 @@ The following features are unimplemented in mandoc: .Bl -dash -compact .It .Sx \&Bd -.Fl file Ar file . +.Fl file Ar file +is unsupported for security reasons. +.It +.Sx \&Bd +.Fl filled +does not adjust the right margin, but is an alias for +.Sx \&Bd +.Fl ragged . +.It +.Sx \&Bd +.Fl literal +does not use a literal font, but is an alias for +.Sx \&Bd +.Fl unfilled . .It .Sx \&Bd .Fl offset Cm center and -.Fl offset Cm right . -Groff does not implement centred and flush-right rendering either, +.Fl offset Cm right +don't work. +Groff does not implement centered and flush-right rendering either, but produces large indentations. .El .Sh SEE ALSO diff --git a/contrib/mdocml/mdoc.c b/contrib/mdocml/mdoc.c index 3e80bc7786a5..027ecbeb317f 100644 --- a/contrib/mdocml/mdoc.c +++ b/contrib/mdocml/mdoc.c @@ -1,7 +1,7 @@ -/* $Id: mdoc.c,v 1.233 2014/11/28 06:27:05 schwarze Exp $ */ +/* $Id: mdoc.c,v 1.238 2015/02/12 13:00:52 schwarze Exp $ */ /* * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2010, 2012, 2013, 2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2010, 2012-2015 Ingo Schwarze <schwarze@openbsd.org> * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -190,12 +190,11 @@ mdoc_alloc(struct roff *roff, struct mparse *parse, return(p); } -int +void mdoc_endparse(struct mdoc *mdoc) { mdoc_macroend(mdoc); - return(1); } void @@ -364,7 +363,6 @@ node_alloc(struct mdoc *mdoc, int line, int pos, p->sec = mdoc->lastsec; p->line = line; p->pos = pos; - p->lastline = line; p->tok = tok; p->type = type; @@ -415,18 +413,21 @@ mdoc_body_alloc(struct mdoc *mdoc, int line, int pos, enum mdoct tok) return(p); } -void +struct mdoc_node * mdoc_endbody_alloc(struct mdoc *mdoc, int line, int pos, enum mdoct tok, struct mdoc_node *body, enum mdoc_endbody end) { struct mdoc_node *p; + body->flags |= MDOC_ENDED; + body->parent->flags |= MDOC_ENDED; p = node_alloc(mdoc, line, pos, tok, MDOC_BODY); - p->pending = body; + p->body = body; p->norm = body->norm; p->end = end; node_append(mdoc, p); mdoc->next = MDOC_NEXT_SIBLING; + return(p); } struct mdoc_node * @@ -600,8 +601,8 @@ mdoc_ptext(struct mdoc *mdoc, int line, char *buf, int offs) * process within its context in the normal way). */ - if (MDOC_Bl == n->tok && MDOC_BODY == n->type && - LIST_column == n->norm->Bl.type) { + if (n->tok == MDOC_Bl && n->type == MDOC_BODY && + n->end == ENDBODY_NOT && n->norm->Bl.type == LIST_column) { /* `Bl' is open without any children. */ mdoc->flags |= MDOC_FREECOL; mdoc_macro(mdoc, MDOC_It, line, offs, &offs, buf); @@ -777,8 +778,8 @@ mdoc_pmacro(struct mdoc *mdoc, int ln, char *buf, int offs) * context around the parsed macro. */ - if (MDOC_Bl == n->tok && MDOC_BODY == n->type && - LIST_column == n->norm->Bl.type) { + if (n->tok == MDOC_Bl && n->type == MDOC_BODY && + n->end == ENDBODY_NOT && n->norm->Bl.type == LIST_column) { mdoc->flags |= MDOC_FREECOL; mdoc_macro(mdoc, MDOC_It, ln, sv, &sv, buf); return(1); diff --git a/contrib/mdocml/mdoc.h b/contrib/mdocml/mdoc.h index f7c933d562e9..e45786d4aa6a 100644 --- a/contrib/mdocml/mdoc.h +++ b/contrib/mdocml/mdoc.h @@ -1,6 +1,7 @@ -/* $Id: mdoc.h,v 1.132 2014/12/01 04:05:32 schwarze Exp $ */ +/* $Id: mdoc.h,v 1.136 2015/02/12 12:24:33 schwarze Exp $ */ /* * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> + * Copyright (c) 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -352,25 +353,24 @@ struct mdoc_node { int nchild; /* number children */ int line; /* parse line */ int pos; /* parse column */ - int lastline; /* the node ends on this line */ enum mdoct tok; /* tok or MDOC__MAX if none */ int flags; #define MDOC_VALID (1 << 0) /* has been validated */ +#define MDOC_ENDED (1 << 1) /* gone past body end mark */ #define MDOC_EOS (1 << 2) /* at sentence boundary */ #define MDOC_LINE (1 << 3) /* first macro/text on line */ #define MDOC_SYNPRETTY (1 << 4) /* SYNOPSIS-style formatting */ -#define MDOC_ENDED (1 << 5) /* rendering has been ended */ +#define MDOC_BROKEN (1 << 5) /* must validate parent when ending */ #define MDOC_DELIMO (1 << 6) #define MDOC_DELIMC (1 << 7) enum mdoc_type type; /* AST node type */ enum mdoc_sec sec; /* current named section */ union mdoc_data *norm; /* normalised args */ - const void *prev_font; /* before entering this node */ + int prev_font; /* before entering this node */ /* FIXME: these can be union'd to shave a few bytes. */ struct mdoc_arg *args; /* BLOCK/ELEM */ - struct mdoc_node *pending; /* BLOCK */ struct mdoc_node *head; /* BLOCK */ - struct mdoc_node *body; /* BLOCK */ + struct mdoc_node *body; /* BLOCK/ENDBODY */ struct mdoc_node *tail; /* BLOCK */ char *string; /* TEXT */ const struct tbl_span *span; /* TBL */ diff --git a/contrib/mdocml/mdoc_argv.c b/contrib/mdocml/mdoc_argv.c index 3e7fabd2ae1c..a53389bf99cc 100644 --- a/contrib/mdocml/mdoc_argv.c +++ b/contrib/mdocml/mdoc_argv.c @@ -1,4 +1,4 @@ -/* $OpenBSD$ */ +/* $Id: mdoc_argv.c,v 1.100 2015/02/04 18:59:45 schwarze Exp $ */ /* * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> * Copyright (c) 2012, 2014 Ingo Schwarze <schwarze@openbsd.org> @@ -339,7 +339,7 @@ mdoc_argv(struct mdoc *mdoc, int line, enum mdoct tok, /* Parse the arguments of the flag. */ tmpv.line = line; - tmpv.pos = ipos; + tmpv.pos = *pos; tmpv.sz = 0; tmpv.value = NULL; diff --git a/contrib/mdocml/mdoc_html.c b/contrib/mdocml/mdoc_html.c index ca51049eec53..09104f8f142a 100644 --- a/contrib/mdocml/mdoc_html.c +++ b/contrib/mdocml/mdoc_html.c @@ -1,7 +1,7 @@ -/* $Id: mdoc_html.c,v 1.216 2014/12/02 10:08:06 schwarze Exp $ */ +/* $Id: mdoc_html.c,v 1.225 2015/02/12 12:24:33 schwarze Exp $ */ /* * Copyright (c) 2008-2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -35,7 +35,7 @@ #define INDENT 5 #define MDOC_ARGS const struct mdoc_meta *meta, \ - const struct mdoc_node *n, \ + struct mdoc_node *n, \ struct html *h #ifndef MIN @@ -81,6 +81,8 @@ static int mdoc_fl_pre(MDOC_ARGS); static int mdoc_fn_pre(MDOC_ARGS); static int mdoc_ft_pre(MDOC_ARGS); static int mdoc_em_pre(MDOC_ARGS); +static void mdoc_eo_post(MDOC_ARGS); +static int mdoc_eo_pre(MDOC_ARGS); static int mdoc_er_pre(MDOC_ARGS); static int mdoc_ev_pre(MDOC_ARGS); static int mdoc_ex_pre(MDOC_ARGS); @@ -189,7 +191,7 @@ static const struct htmlmdoc mdocs[MDOC_MAX] = { {NULL, NULL}, /* Ec */ /* FIXME: no space */ {NULL, NULL}, /* Ef */ {mdoc_em_pre, NULL}, /* Em */ - {mdoc_quote_pre, mdoc_quote_post}, /* Eo */ + {mdoc_eo_pre, mdoc_eo_post}, /* Eo */ {mdoc_xx_pre, NULL}, /* Fx */ {mdoc_ms_pre, NULL}, /* Ms */ {mdoc_no_pre, NULL}, /* No */ @@ -265,7 +267,7 @@ void html_mdoc(void *arg, const struct mdoc *mdoc) { - print_mdoc(mdoc_meta(mdoc), mdoc_node(mdoc), + print_mdoc(mdoc_meta(mdoc), mdoc_node(mdoc)->child, (struct html *)arg); putchar('\n'); } @@ -279,10 +281,11 @@ static void a2width(const char *p, struct roffsu *su) { - if ( ! a2roffsu(p, su, SCALE_MAX)) { + if (a2roffsu(p, su, SCALE_MAX) < 2) { su->unit = SCALE_EN; su->scale = html_strlen(p); - } + } else if (su->scale < 0.0) + su->scale = 0.0; } /* @@ -370,9 +373,10 @@ static void print_mdoc_nodelist(MDOC_ARGS) { - print_mdoc_node(meta, n, h); - if (n->next) - print_mdoc_nodelist(meta, n->next, h); + while (n != NULL) { + print_mdoc_node(meta, n, h); + n = n->next; + } } static void @@ -383,6 +387,7 @@ print_mdoc_node(MDOC_ARGS) child = 1; t = h->tags.head; + n->flags &= ~MDOC_ENDED; switch (n->type) { case MDOC_ROOT: @@ -432,12 +437,9 @@ print_mdoc_node(MDOC_ARGS) break; } - if (HTML_KEEP & h->flags) { - if (n->prev ? (n->prev->lastline != n->line) : - (n->parent && n->parent->line != n->line)) { - h->flags &= ~HTML_KEEP; - h->flags |= HTML_PREKEEP; - } + if (h->flags & HTML_KEEP && n->flags & MDOC_LINE) { + h->flags &= ~HTML_KEEP; + h->flags |= HTML_PREKEEP; } if (child && n->child) @@ -456,7 +458,7 @@ print_mdoc_node(MDOC_ARGS) break; (*mdocs[n->tok].post)(meta, n, h); if (n->end != ENDBODY_NOT) - n->pending->flags |= MDOC_ENDED; + n->body->flags |= MDOC_ENDED; if (n->end == ENDBODY_NOSPACE) h->flags |= HTML_NOSPACE; break; @@ -1121,7 +1123,7 @@ mdoc_bd_pre(MDOC_ARGS) { struct htmlpair tag[2]; int comp, sv; - const struct mdoc_node *nn; + struct mdoc_node *nn; struct roffsu su; if (MDOC_HEAD == n->type) @@ -1252,9 +1254,6 @@ mdoc_an_pre(MDOC_ARGS) return(0); } - if (n->child == NULL) - return(0); - if (h->flags & HTML_SPLIT) print_otag(h, TAG_BR, 0, NULL); @@ -1566,9 +1565,12 @@ mdoc_sp_pre(MDOC_ARGS) SCALE_VS_INIT(&su, 1); if (MDOC_sp == n->tok) { - if (NULL != (n = n->child)) + if (NULL != (n = n->child)) { if ( ! a2roffsu(n->string, &su, SCALE_VS)) - SCALE_VS_INIT(&su, atoi(n->string)); + su.scale = 1.0; + else if (su.scale < 0.0) + su.scale = 0.0; + } } else su.scale = 0.0; @@ -2080,8 +2082,8 @@ mdoc_quote_pre(MDOC_ARGS) case MDOC_Ao: /* FALLTHROUGH */ case MDOC_Aq: - print_text(h, n->parent->prev != NULL && - n->parent->prev->tok == MDOC_An ? "<" : "\\(la"); + print_text(h, n->nchild == 1 && + n->child->tok == MDOC_Mt ? "<" : "\\(la"); break; case MDOC_Bro: /* FALLTHROUGH */ @@ -2107,8 +2109,6 @@ mdoc_quote_pre(MDOC_ARGS) return(1); print_text(h, n->norm->Es->child->string); break; - case MDOC_Eo: - break; case MDOC_Do: /* FALLTHROUGH */ case MDOC_Dq: @@ -2150,16 +2150,14 @@ mdoc_quote_post(MDOC_ARGS) if (n->type != MDOC_BODY && n->type != MDOC_ELEM) return; - if ( ! (n->tok == MDOC_En || - (n->tok == MDOC_Eo && n->end == ENDBODY_SPACE))) - h->flags |= HTML_NOSPACE; + h->flags |= HTML_NOSPACE; switch (n->tok) { case MDOC_Ao: /* FALLTHROUGH */ case MDOC_Aq: - print_text(h, n->parent->prev != NULL && - n->parent->prev->tok == MDOC_An ? ">" : "\\(ra"); + print_text(h, n->nchild == 1 && + n->child->tok == MDOC_Mt ? ">" : "\\(ra"); break; case MDOC_Bro: /* FALLTHROUGH */ @@ -2176,14 +2174,12 @@ mdoc_quote_post(MDOC_ARGS) print_text(h, "\\(rB"); break; case MDOC_En: - if (NULL != n->norm->Es && - NULL != n->norm->Es->child && - NULL != n->norm->Es->child->next) { - h->flags |= HTML_NOSPACE; + if (n->norm->Es == NULL || + n->norm->Es->child == NULL || + n->norm->Es->child->next == NULL) + h->flags &= ~HTML_NOSPACE; + else print_text(h, n->norm->Es->child->next->string); - } - break; - case MDOC_Eo: break; case MDOC_Qo: /* FALLTHROUGH */ @@ -2211,3 +2207,44 @@ mdoc_quote_post(MDOC_ARGS) /* NOTREACHED */ } } + +static int +mdoc_eo_pre(MDOC_ARGS) +{ + + if (n->type != MDOC_BODY) + return(1); + + if (n->end == ENDBODY_NOT && + n->parent->head->child == NULL && + n->child != NULL && + n->child->end != ENDBODY_NOT) + print_text(h, "\\&"); + else if (n->end != ENDBODY_NOT ? n->child != NULL : + n->parent->head->child != NULL && (n->child != NULL || + (n->parent->tail != NULL && n->parent->tail->child != NULL))) + h->flags |= HTML_NOSPACE; + return(1); +} + +static void +mdoc_eo_post(MDOC_ARGS) +{ + int body, tail; + + if (n->type != MDOC_BODY) + return; + + if (n->end != ENDBODY_NOT) { + h->flags &= ~HTML_NOSPACE; + return; + } + + body = n->child != NULL || n->parent->head->child != NULL; + tail = n->parent->tail != NULL && n->parent->tail->child != NULL; + + if (body && tail) + h->flags |= HTML_NOSPACE; + else if ( ! tail) + h->flags &= ~HTML_NOSPACE; +} diff --git a/contrib/mdocml/mdoc_macro.c b/contrib/mdocml/mdoc_macro.c index b354e540a1bf..efb48d023f83 100644 --- a/contrib/mdocml/mdoc_macro.c +++ b/contrib/mdocml/mdoc_macro.c @@ -1,7 +1,7 @@ -/* $Id: mdoc_macro.c,v 1.157 2014/12/13 13:14:39 schwarze Exp $ */ +/* $Id: mdoc_macro.c,v 1.183 2015/02/12 12:24:33 schwarze Exp $ */ /* * Copyright (c) 2008-2012 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2010, 2012, 2013, 2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2010, 2012-2015 Ingo Schwarze <schwarze@openbsd.org> * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -31,15 +31,6 @@ #include "libmdoc.h" #include "libmandoc.h" -enum rew { /* see rew_dohalt() */ - REWIND_NONE, - REWIND_THIS, - REWIND_MORE, - REWIND_FORCE, - REWIND_LATER, - REWIND_ERROR -}; - static void blk_full(MACRO_PROT_ARGS); static void blk_exp_close(MACRO_PROT_ARGS); static void blk_part_exp(MACRO_PROT_ARGS); @@ -56,17 +47,12 @@ static void append_delims(struct mdoc *, int, int *, char *); static enum mdoct lookup(struct mdoc *, enum mdoct, int, int, const char *); static int macro_or_word(MACRO_PROT_ARGS, int); -static int make_pending(struct mdoc_node *, enum mdoct, - struct mdoc *, int, int); static int parse_rest(struct mdoc *, enum mdoct, int, int *, char *); static enum mdoct rew_alt(enum mdoct); -static enum rew rew_dohalt(enum mdoct, enum mdoc_type, - const struct mdoc_node *); static void rew_elem(struct mdoc *, enum mdoct); static void rew_last(struct mdoc *, const struct mdoc_node *); -static void rew_sub(enum mdoc_type, struct mdoc *, - enum mdoct, int, int); +static void rew_pending(struct mdoc *, const struct mdoc_node *); const struct mdoc_macro __mdoc_macros[MDOC_MAX] = { { in_line_argn, MDOC_CALLABLE | MDOC_PARSED | MDOC_JOIN }, /* Ap */ @@ -263,6 +249,9 @@ lookup(struct mdoc *mdoc, enum mdoct from, int line, int ppos, const char *p) return(MDOC_MAX); } +/* + * Rewind up to and including a specific node. + */ static void rew_last(struct mdoc *mdoc, const struct mdoc_node *to) { @@ -288,6 +277,44 @@ rew_last(struct mdoc *mdoc, const struct mdoc_node *to) } /* + * Rewind up to a specific block, including all blocks that broke it. + */ +static void +rew_pending(struct mdoc *mdoc, const struct mdoc_node *n) +{ + + for (;;) { + rew_last(mdoc, n); + + switch (n->type) { + case MDOC_HEAD: + mdoc_body_alloc(mdoc, n->line, n->pos, n->tok); + return; + case MDOC_BLOCK: + break; + default: + return; + } + + if ( ! (n->flags & MDOC_BROKEN)) + return; + + for (;;) { + if ((n = n->parent) == NULL) + return; + + if (n->type == MDOC_BLOCK || + n->type == MDOC_HEAD) { + if (n->flags & MDOC_ENDED) + break; + else + return; + } + } + } +} + +/* * For a block closing macro, return the corresponding opening one. * Otherwise, return the macro itself. */ @@ -333,119 +360,6 @@ rew_alt(enum mdoct tok) /* NOTREACHED */ } -/* - * Rewinding to tok, how do we have to handle *p? - * REWIND_NONE: *p would delimit tok, but no tok scope is open - * inside *p, so there is no need to rewind anything at all. - * REWIND_THIS: *p matches tok, so rewind *p and nothing else. - * REWIND_MORE: *p is implicit, rewind it and keep searching for tok. - * REWIND_FORCE: *p is explicit, but tok is full, force rewinding *p. - * REWIND_LATER: *p is explicit and still open, postpone rewinding. - * REWIND_ERROR: No tok block is open at all. - */ -static enum rew -rew_dohalt(enum mdoct tok, enum mdoc_type type, - const struct mdoc_node *p) -{ - - /* - * No matching token, no delimiting block, no broken block. - * This can happen when full implicit macros are called for - * the first time but try to rewind their previous - * instance anyway. - */ - if (MDOC_ROOT == p->type) - return(MDOC_BLOCK == type && - MDOC_EXPLICIT & mdoc_macros[tok].flags ? - REWIND_ERROR : REWIND_NONE); - - /* - * When starting to rewind, skip plain text - * and nodes that have already been rewound. - */ - if (MDOC_TEXT == p->type || MDOC_VALID & p->flags) - return(REWIND_MORE); - - /* - * The easiest case: Found a matching token. - * This applies to both blocks and elements. - */ - tok = rew_alt(tok); - if (tok == p->tok) - return(p->end ? REWIND_NONE : - type == p->type ? REWIND_THIS : REWIND_MORE); - - /* - * While elements do require rewinding for themselves, - * they never affect rewinding of other nodes. - */ - if (MDOC_ELEM == p->type) - return(REWIND_MORE); - - /* - * Blocks delimited by our target token get REWIND_MORE. - * Blocks delimiting our target token get REWIND_NONE. - */ - switch (tok) { - case MDOC_Bl: - if (MDOC_It == p->tok) - return(REWIND_MORE); - break; - case MDOC_It: - if (MDOC_BODY == p->type && MDOC_Bl == p->tok) - return(REWIND_NONE); - break; - /* - * XXX Badly nested block handling still fails badly - * when one block is breaking two blocks of the same type. - * This is an incomplete and extremely ugly workaround, - * required to let the OpenBSD tree build. - */ - case MDOC_Oo: - if (MDOC_Op == p->tok) - return(REWIND_MORE); - break; - case MDOC_Nm: - return(REWIND_NONE); - case MDOC_Nd: - /* FALLTHROUGH */ - case MDOC_Ss: - if (MDOC_BODY == p->type && MDOC_Sh == p->tok) - return(REWIND_NONE); - /* FALLTHROUGH */ - case MDOC_Sh: - if (MDOC_ROOT == p->parent->type) - return(REWIND_THIS); - if (MDOC_Nd == p->tok || MDOC_Ss == p->tok || - MDOC_Sh == p->tok) - return(REWIND_MORE); - break; - default: - break; - } - - /* - * Default block rewinding rules. - * In particular, always skip block end markers, - * and let all blocks rewind Nm children. - * Do not warn again when closing a block, - * since closing the body already warned. - */ - if (ENDBODY_NOT != p->end || MDOC_Nm == p->tok || - MDOC_BLOCK == type || (MDOC_BLOCK == p->type && - ! (MDOC_EXPLICIT & mdoc_macros[tok].flags))) - return(REWIND_MORE); - - /* - * By default, closing out full blocks - * forces closing of broken explicit blocks, - * while closing out partial blocks - * allows delayed rewinding by default. - */ - return (&blk_full == mdoc_macros[tok].fp ? - REWIND_FORCE : REWIND_LATER); -} - static void rew_elem(struct mdoc *mdoc, enum mdoct tok) { @@ -460,136 +374,6 @@ rew_elem(struct mdoc *mdoc, enum mdoct tok) } /* - * We are trying to close a block identified by tok, - * but the child block *broken is still open. - * Thus, postpone closing the tok block - * until the rew_sub call closing *broken. - */ -static int -make_pending(struct mdoc_node *broken, enum mdoct tok, - struct mdoc *mdoc, int line, int ppos) -{ - struct mdoc_node *breaker; - - /* - * Iterate backwards, searching for the block matching tok, - * that is, the block breaking the *broken block. - */ - for (breaker = broken->parent; breaker; breaker = breaker->parent) { - - /* - * If the *broken block had already been broken before - * and we encounter its breaker, make the tok block - * pending on the inner breaker. - * Graphically, "[A breaker=[B broken=[C->B B] tok=A] C]" - * becomes "[A broken=[B [C->B B] tok=A] C]" - * and finally "[A [B->A [C->B B] A] C]". - */ - if (breaker == broken->pending) { - broken = breaker; - continue; - } - - if (REWIND_THIS != rew_dohalt(tok, MDOC_BLOCK, breaker)) - continue; - if (MDOC_BODY == broken->type) - broken = broken->parent; - - /* - * Found the breaker. - * If another, outer breaker is already pending on - * the *broken block, we must not clobber the link - * to the outer breaker, but make it pending on the - * new, now inner breaker. - * Graphically, "[A breaker=[B broken=[C->A A] tok=B] C]" - * becomes "[A breaker=[B->A broken=[C A] tok=B] C]" - * and finally "[A [B->A [C->B A] B] C]". - */ - if (broken->pending) { - struct mdoc_node *taker; - - /* - * If the breaker had also been broken before, - * it cannot take on the outer breaker itself, - * but must hand it on to its own breakers. - * Graphically, this is the following situation: - * "[A [B breaker=[C->B B] broken=[D->A A] tok=C] D]" - * "[A taker=[B->A breaker=[C->B B] [D->C A] C] D]" - */ - taker = breaker; - while (taker->pending) - taker = taker->pending; - taker->pending = broken->pending; - } - broken->pending = breaker; - mandoc_vmsg(MANDOCERR_BLK_NEST, mdoc->parse, line, ppos, - "%s breaks %s", mdoc_macronames[tok], - mdoc_macronames[broken->tok]); - return(1); - } - - /* - * Found no matching block for tok. - * Are you trying to close a block that is not open? - */ - return(0); -} - -static void -rew_sub(enum mdoc_type t, struct mdoc *mdoc, - enum mdoct tok, int line, int ppos) -{ - struct mdoc_node *n; - - n = mdoc->last; - while (n) { - switch (rew_dohalt(tok, t, n)) { - case REWIND_NONE: - return; - case REWIND_THIS: - n->lastline = line - - (mdoc->flags & MDOC_NEWLINE && - ! (mdoc_macros[tok].flags & MDOC_EXPLICIT)); - break; - case REWIND_FORCE: - mandoc_vmsg(MANDOCERR_BLK_BROKEN, mdoc->parse, - line, ppos, "%s breaks %s", - mdoc_macronames[tok], - mdoc_macronames[n->tok]); - /* FALLTHROUGH */ - case REWIND_MORE: - n->lastline = line - - (mdoc->flags & MDOC_NEWLINE ? 1 : 0); - n = n->parent; - continue; - case REWIND_LATER: - if (make_pending(n, tok, mdoc, line, ppos) || - t != MDOC_BLOCK) - return; - /* FALLTHROUGH */ - case REWIND_ERROR: - mandoc_msg(MANDOCERR_BLK_NOTOPEN, - mdoc->parse, line, ppos, - mdoc_macronames[tok]); - return; - } - break; - } - assert(n); - rew_last(mdoc, n); - - /* - * The current block extends an enclosing block. - * Now that the current block ends, close the enclosing block, too. - */ - while ((n = n->pending) != NULL) { - rew_last(mdoc, n); - if (n->type == MDOC_HEAD) - mdoc_body_alloc(mdoc, n->line, n->pos, n->tok); - } -} - -/* * Allocate a word and check whether it's punctuation or not. * Punctuation consists of those tokens found in mdoc_isdelim(). */ @@ -699,10 +483,11 @@ blk_exp_close(MACRO_PROT_ARGS) { struct mdoc_node *body; /* Our own body. */ struct mdoc_node *endbody; /* Our own end marker. */ + struct mdoc_node *itblk; /* An It block starting later. */ struct mdoc_node *later; /* A sub-block starting later. */ - struct mdoc_node *n; /* For searching backwards. */ + struct mdoc_node *n; /* Search back to our block. */ - int j, lastarg, maxargs, flushed, nl; + int j, lastarg, maxargs, nl; enum margserr ac; enum mdoct atok, ntok; char *p; @@ -727,10 +512,13 @@ blk_exp_close(MACRO_PROT_ARGS) */ atok = rew_alt(tok); - body = endbody = later = NULL; + body = endbody = itblk = later = NULL; for (n = mdoc->last; n; n = n->parent) { - if (n->flags & MDOC_VALID) + if (n->flags & MDOC_ENDED) { + if ( ! (n->flags & MDOC_VALID)) + n->flags |= MDOC_BROKEN; continue; + } /* Remember the start of our own body. */ @@ -742,6 +530,12 @@ blk_exp_close(MACRO_PROT_ARGS) if (n->type != MDOC_BLOCK || n->tok == MDOC_Nm) continue; + + if (n->tok == MDOC_It) { + itblk = n; + continue; + } + if (atok == n->tok) { assert(body); @@ -751,52 +545,70 @@ blk_exp_close(MACRO_PROT_ARGS) * just proceed to closing out. */ - if (later == NULL) + if (later == NULL || + (tok == MDOC_El && itblk == NULL)) break; /* - * When there is a pending sub block, - * postpone closing out the current block - * until the rew_sub() closing out the sub-block. - */ - - make_pending(later, tok, mdoc, line, ppos); - - /* + * When there is a pending sub block, postpone + * closing out the current block until the + * rew_pending() closing out the sub-block. * Mark the place where the formatting - but not * the scope - of the current block ends. */ - mdoc_endbody_alloc(mdoc, line, ppos, + mandoc_vmsg(MANDOCERR_BLK_NEST, mdoc->parse, + line, ppos, "%s breaks %s", + mdoc_macronames[atok], + mdoc_macronames[later->tok]); + + endbody = mdoc_endbody_alloc(mdoc, line, ppos, atok, body, ENDBODY_SPACE); + if (tok == MDOC_El) + itblk->flags |= MDOC_ENDED | MDOC_BROKEN; + /* * If a block closing macro taking arguments * breaks another block, put the arguments - * into the end marker and remeber the - * end marker in order to close it out. + * into the end marker. */ - if (maxargs) { - endbody = mdoc->last; + if (maxargs) mdoc->next = MDOC_NEXT_CHILD; - } break; } - /* - * When finding an open sub block, remember the last - * open explicit block, or, in case there are only - * implicit ones, the first open implicit block. - */ + /* Explicit blocks close out description lines. */ - if (later && - mdoc_macros[later->tok].flags & MDOC_EXPLICIT) + if (n->tok == MDOC_Nd) { + rew_last(mdoc, n); continue; - if (n->tok != MDOC_It) + } + + /* Breaking an open sub block. */ + + n->flags |= MDOC_BROKEN; + if (later == NULL) later = n; } - rew_sub(MDOC_BODY, mdoc, tok, line, ppos); + + if (body == NULL) { + mandoc_msg(MANDOCERR_BLK_NOTOPEN, mdoc->parse, + line, ppos, mdoc_macronames[tok]); + if (maxargs && endbody == NULL) { + /* + * Stray .Ec without previous .Eo: + * Break the output line, keep the arguments. + */ + mdoc_elem_alloc(mdoc, line, ppos, MDOC_br, NULL); + rew_elem(mdoc, MDOC_br); + } + } else if (endbody == NULL) { + rew_last(mdoc, body); + if (maxargs) + mdoc_tail_alloc(mdoc, line, ppos, atok); + } if ( ! (mdoc_macros[tok].flags & MDOC_PARSED)) { if (buf[*pos] != '\0') @@ -804,32 +616,19 @@ blk_exp_close(MACRO_PROT_ARGS) mdoc->parse, line, ppos, "%s %s", mdoc_macronames[tok], buf + *pos); - rew_sub(MDOC_BLOCK, mdoc, tok, line, ppos); + if (endbody == NULL && n != NULL) + rew_pending(mdoc, n); return; } - if (maxargs && endbody == NULL) { - if (n == NULL) { - /* - * Stray .Ec without previous .Eo: - * Break the output line, ignore any arguments. - */ - mdoc_elem_alloc(mdoc, line, ppos, MDOC_br, NULL); - rew_elem(mdoc, MDOC_br); - } else - mdoc_tail_alloc(mdoc, line, ppos, atok); - } - - flushed = n == NULL; + if (endbody != NULL) + n = endbody; for (j = 0; ; j++) { lastarg = *pos; - if (j == maxargs && ! flushed) { - if (endbody == NULL) - rew_sub(MDOC_BLOCK, mdoc, tok, line, ppos); - else - rew_last(mdoc, endbody); - flushed = 1; + if (j == maxargs && n != NULL) { + rew_pending(mdoc, n); + n = NULL; } ac = mdoc_args(mdoc, line, pos, buf, tok, &p); @@ -845,24 +644,17 @@ blk_exp_close(MACRO_PROT_ARGS) continue; } - if ( ! flushed) { - if (endbody == NULL) - rew_sub(MDOC_BLOCK, mdoc, tok, line, ppos); - else - rew_last(mdoc, endbody); - flushed = 1; + if (n != NULL) { + rew_pending(mdoc, n); + n = NULL; } mdoc->flags &= ~MDOC_NEWLINE; mdoc_macro(mdoc, ntok, line, lastarg, pos, buf); break; } - if ( ! flushed) { - if (endbody == NULL) - rew_sub(MDOC_BLOCK, mdoc, tok, line, ppos); - else - rew_last(mdoc, endbody); - } + if (n != NULL) + rew_pending(mdoc, n); if (nl) append_delims(mdoc, line, pos, buf); } @@ -932,7 +724,7 @@ in_line(MACRO_PROT_ARGS) */ if (ac == ARGS_PUNCT) { - if (cnt == 0 && nc == 0) + if (cnt == 0 && (nc == 0 || tok == MDOC_An)) mdoc->flags |= MDOC_NODELIMC; break; } @@ -1055,22 +847,95 @@ blk_full(MACRO_PROT_ARGS) { int la, nl, parsed; struct mdoc_arg *arg; - struct mdoc_node *head; /* save of head macro */ - struct mdoc_node *body; /* save of body macro */ + struct mdoc_node *blk; /* Our own or a broken block. */ + struct mdoc_node *head; /* Our own head. */ + struct mdoc_node *body; /* Our own body. */ struct mdoc_node *n; enum margserr ac, lac; char *p; nl = MDOC_NEWLINE & mdoc->flags; - /* Skip items outside lists. */ + if (buf[*pos] == '\0' && (tok == MDOC_Sh || tok == MDOC_Ss)) { + mandoc_msg(MANDOCERR_MACRO_EMPTY, mdoc->parse, + line, ppos, mdoc_macronames[tok]); + return; + } - if (tok == MDOC_It) { - for (n = mdoc->last; n; n = n->parent) - if (n->tok == MDOC_Bl && - ! (n->flags & MDOC_VALID)) + if ( ! (mdoc_macros[tok].flags & MDOC_EXPLICIT)) { + + /* Here, tok is one of Sh Ss Nm Nd It. */ + + blk = NULL; + for (n = mdoc->last; n != NULL; n = n->parent) { + if (n->flags & MDOC_ENDED) { + if ( ! (n->flags & MDOC_VALID)) + n->flags |= MDOC_BROKEN; + continue; + } + if (n->type != MDOC_BLOCK) + continue; + + if (tok == MDOC_It && n->tok == MDOC_Bl) { + if (blk != NULL) { + mandoc_vmsg(MANDOCERR_BLK_BROKEN, + mdoc->parse, line, ppos, + "It breaks %s", + mdoc_macronames[blk->tok]); + rew_pending(mdoc, blk); + } + break; + } + + if (mdoc_macros[n->tok].flags & MDOC_EXPLICIT) { + switch (tok) { + case MDOC_Sh: + /* FALLTHROUGH */ + case MDOC_Ss: + mandoc_vmsg(MANDOCERR_BLK_BROKEN, + mdoc->parse, line, ppos, + "%s breaks %s", + mdoc_macronames[tok], + mdoc_macronames[n->tok]); + rew_pending(mdoc, n); + n = mdoc->last; + continue; + case MDOC_It: + /* Delay in case it's astray. */ + blk = n; + continue; + default: + break; + } + break; + } + + /* Here, n is one of Sh Ss Nm Nd It. */ + + if (tok != MDOC_Sh && (n->tok == MDOC_Sh || + (tok != MDOC_Ss && (n->tok == MDOC_Ss || + (tok != MDOC_It && n->tok == MDOC_It))))) break; - if (n == NULL) { + + /* Item breaking an explicit block. */ + + if (blk != NULL) { + mandoc_vmsg(MANDOCERR_BLK_BROKEN, + mdoc->parse, line, ppos, + "It breaks %s", + mdoc_macronames[blk->tok]); + rew_pending(mdoc, blk); + blk = NULL; + } + + /* Close out prior implicit scopes. */ + + rew_last(mdoc, n); + } + + /* Skip items outside lists. */ + + if (tok == MDOC_It && (n == NULL || n->tok != MDOC_Bl)) { mandoc_vmsg(MANDOCERR_IT_STRAY, mdoc->parse, line, ppos, "It %s", buf + *pos); mdoc_elem_alloc(mdoc, line, ppos, MDOC_br, NULL); @@ -1079,13 +944,6 @@ blk_full(MACRO_PROT_ARGS) } } - /* Close out prior implicit scope. */ - - if ( ! (mdoc_macros[tok].flags & MDOC_EXPLICIT)) { - rew_sub(MDOC_BODY, mdoc, tok, line, ppos); - rew_sub(MDOC_BLOCK, mdoc, tok, line, ppos); - } - /* * This routine accommodates implicitly- and explicitly-scoped * macro openings. Implicit ones first close out prior scope @@ -1096,7 +954,7 @@ blk_full(MACRO_PROT_ARGS) */ mdoc_argv(mdoc, line, tok, &arg, pos, buf); - mdoc_block_alloc(mdoc, line, ppos, tok, arg); + blk = mdoc_block_alloc(mdoc, line, ppos, tok, arg); head = body = NULL; /* @@ -1115,7 +973,7 @@ blk_full(MACRO_PROT_ARGS) if (tok == MDOC_Nd) { head = mdoc_head_alloc(mdoc, line, ppos, tok); - rew_sub(MDOC_HEAD, mdoc, tok, line, ppos); + rew_last(mdoc, head); body = mdoc_body_alloc(mdoc, line, ppos, tok); } @@ -1127,8 +985,6 @@ blk_full(MACRO_PROT_ARGS) la = *pos; lac = ac; ac = mdoc_args(mdoc, line, pos, buf, tok, &p); - if (ac == ARGS_PUNCT) - break; if (ac == ARGS_EOLN) { if (lac != ARGS_PPHRASE && lac != ARGS_PHRASE) break; @@ -1139,10 +995,24 @@ blk_full(MACRO_PROT_ARGS) * reopen our scope if the last parse was a * phrase or partial phrase. */ - rew_sub(MDOC_BODY, mdoc, tok, line, ppos); + if (body != NULL) + rew_last(mdoc, body); body = mdoc_body_alloc(mdoc, line, ppos, tok); break; } + if (tok == MDOC_Bd || tok == MDOC_Bk) { + mandoc_vmsg(MANDOCERR_ARG_EXCESS, + mdoc->parse, line, la, "%s ... %s", + mdoc_macronames[tok], buf + la); + break; + } + if (tok == MDOC_Rs) { + mandoc_vmsg(MANDOCERR_ARG_SKIP, mdoc->parse, + line, la, "Rs %s", buf + la); + break; + } + if (ac == ARGS_PUNCT) + break; /* * Emit leading punctuation (i.e., punctuation before @@ -1173,8 +1043,7 @@ blk_full(MACRO_PROT_ARGS) * head; if we have, rewind that instead. */ - rew_sub(body ? MDOC_BODY : MDOC_HEAD, - mdoc, tok, line, ppos); + rew_last(mdoc, body == NULL ? head : body); body = mdoc_body_alloc(mdoc, line, ppos, tok); /* @@ -1196,9 +1065,11 @@ blk_full(MACRO_PROT_ARGS) break; } + if (blk->flags & MDOC_VALID) + return; if (head == NULL) head = mdoc_head_alloc(mdoc, line, ppos, tok); - if (nl) + if (nl && tok != MDOC_Bd && tok != MDOC_Bl && tok != MDOC_Rs) append_delims(mdoc, line, pos, buf); if (body != NULL) goto out; @@ -1206,26 +1077,32 @@ blk_full(MACRO_PROT_ARGS) /* * If there is an open (i.e., unvalidated) sub-block requiring * explicit close-out, postpone switching the current block from - * head to body until the rew_sub() call closing out that + * head to body until the rew_pending() call closing out that * sub-block. */ for (n = mdoc->last; n && n != head; n = n->parent) { + if (n->flags & MDOC_ENDED) { + if ( ! (n->flags & MDOC_VALID)) + n->flags |= MDOC_BROKEN; + continue; + } if (n->type == MDOC_BLOCK && - mdoc_macros[n->tok].flags & MDOC_EXPLICIT && - ! (n->flags & MDOC_VALID)) { - n->pending = head; - return; + mdoc_macros[n->tok].flags & MDOC_EXPLICIT) { + n->flags = MDOC_BROKEN; + head->flags = MDOC_ENDED; } } + if (head->flags & MDOC_ENDED) + return; /* Close out scopes to remain in a consistent state. */ - rew_sub(MDOC_HEAD, mdoc, tok, line, ppos); - mdoc_body_alloc(mdoc, line, ppos, tok); + rew_last(mdoc, head); + body = mdoc_body_alloc(mdoc, line, ppos, tok); out: if (mdoc->flags & MDOC_FREECOL) { - rew_sub(MDOC_BODY, mdoc, tok, line, ppos); - rew_sub(MDOC_BLOCK, mdoc, tok, line, ppos); + rew_last(mdoc, body); + rew_last(mdoc, blk); mdoc->flags &= ~MDOC_FREECOL; } } @@ -1252,8 +1129,7 @@ blk_part_imp(MACRO_PROT_ARGS) */ blk = mdoc_block_alloc(mdoc, line, ppos, tok, NULL); - mdoc_head_alloc(mdoc, line, ppos, tok); - rew_sub(MDOC_HEAD, mdoc, tok, line, ppos); + rew_last(mdoc, mdoc_head_alloc(mdoc, line, ppos, tok)); /* * Open the body scope "on-demand", that is, after we've @@ -1284,26 +1160,38 @@ blk_part_imp(MACRO_PROT_ARGS) /* * If there is an open sub-block requiring explicit close-out, - * postpone closing out the current block - * until the rew_sub() call closing out the sub-block. + * postpone closing out the current block until the + * rew_pending() call closing out the sub-block. */ for (n = mdoc->last; n && n != body && n != blk->parent; n = n->parent) { + if (n->flags & MDOC_ENDED) { + if ( ! (n->flags & MDOC_VALID)) + n->flags |= MDOC_BROKEN; + continue; + } if (n->type == MDOC_BLOCK && - mdoc_macros[n->tok].flags & MDOC_EXPLICIT && - ! (n->flags & MDOC_VALID)) { - make_pending(n, tok, mdoc, line, ppos); - mdoc_endbody_alloc(mdoc, line, ppos, - tok, body, ENDBODY_NOSPACE); - return; + mdoc_macros[n->tok].flags & MDOC_EXPLICIT) { + n->flags |= MDOC_BROKEN; + if ( ! (body->flags & MDOC_ENDED)) { + mandoc_vmsg(MANDOCERR_BLK_NEST, + mdoc->parse, line, ppos, + "%s breaks %s", mdoc_macronames[tok], + mdoc_macronames[n->tok]); + mdoc_endbody_alloc(mdoc, line, ppos, + tok, body, ENDBODY_NOSPACE); + } } } assert(n == body); - rew_sub(MDOC_BODY, mdoc, tok, line, ppos); + if (body->flags & MDOC_ENDED) + return; + + rew_last(mdoc, body); if (nl) append_delims(mdoc, line, pos, buf); - rew_sub(MDOC_BLOCK, mdoc, tok, line, ppos); + rew_pending(mdoc, blk); /* Move trailing .Ns out of scope. */ @@ -1319,7 +1207,6 @@ blk_part_exp(MACRO_PROT_ARGS) int la, nl; enum margserr ac; struct mdoc_node *head; /* keep track of head */ - struct mdoc_node *body; /* keep track of body */ char *p; nl = MDOC_NEWLINE & mdoc->flags; @@ -1331,7 +1218,8 @@ blk_part_exp(MACRO_PROT_ARGS) */ mdoc_block_alloc(mdoc, line, ppos, tok, NULL); - for (head = body = NULL; ; ) { + head = NULL; + for (;;) { la = *pos; ac = mdoc_args(mdoc, line, pos, buf, tok, &p); if (ac == ARGS_PUNCT || ac == ARGS_EOLN) @@ -1341,32 +1229,19 @@ blk_part_exp(MACRO_PROT_ARGS) if (head == NULL && ac != ARGS_QWORD && mdoc_isdelim(p) == DELIM_OPEN) { - assert(NULL == body); dword(mdoc, line, la, p, DELIM_OPEN, 0); continue; } if (head == NULL) { - assert(body == NULL); head = mdoc_head_alloc(mdoc, line, ppos, tok); - } - - /* - * `Eo' gobbles any data into the head, but most other - * macros just immediately close out and begin the body. - */ - - if (body == NULL) { - assert(head); - /* No check whether it's a macro! */ - if (tok == MDOC_Eo) + if (tok == MDOC_Eo) /* Not parsed. */ dword(mdoc, line, la, p, DELIM_MAX, 0); - rew_sub(MDOC_HEAD, mdoc, tok, line, ppos); - body = mdoc_body_alloc(mdoc, line, ppos, tok); + rew_last(mdoc, head); + mdoc_body_alloc(mdoc, line, ppos, tok); if (tok == MDOC_Eo) continue; } - assert(head != NULL && body != NULL); if (macro_or_word(mdoc, tok, line, la, pos, buf, 1)) break; @@ -1374,11 +1249,8 @@ blk_part_exp(MACRO_PROT_ARGS) /* Clean-up to leave in a consistent state. */ - if (head == NULL) - mdoc_head_alloc(mdoc, line, ppos, tok); - - if (body == NULL) { - rew_sub(MDOC_HEAD, mdoc, tok, line, ppos); + if (head == NULL) { + rew_last(mdoc, mdoc_head_alloc(mdoc, line, ppos, tok)); mdoc_body_alloc(mdoc, line, ppos, tok); } if (nl) @@ -1388,11 +1260,12 @@ blk_part_exp(MACRO_PROT_ARGS) static void in_line_argn(MACRO_PROT_ARGS) { - int la, flushed, j, maxargs, nl; - enum margserr ac; struct mdoc_arg *arg; char *p; + enum margserr ac; enum mdoct ntok; + int state; /* arg#; -1: not yet open; -2: closed */ + int la, maxargs, nl; nl = mdoc->flags & MDOC_NEWLINE; @@ -1426,62 +1299,76 @@ in_line_argn(MACRO_PROT_ARGS) mdoc_argv(mdoc, line, tok, &arg, pos, buf); + state = -1; p = NULL; - flushed = j = 0; for (;;) { la = *pos; ac = mdoc_args(mdoc, line, pos, buf, tok, &p); + + if (ac == ARGS_WORD && state == -1 && + ! (mdoc_macros[tok].flags & MDOC_IGNDELIM) && + mdoc_isdelim(p) == DELIM_OPEN) { + dword(mdoc, line, la, p, DELIM_OPEN, 0); + continue; + } + + if (state == -1 && tok != MDOC_In && + tok != MDOC_St && tok != MDOC_Xr) { + mdoc_elem_alloc(mdoc, line, ppos, tok, arg); + state = 0; + } + if (ac == ARGS_PUNCT || ac == ARGS_EOLN) { - if (j < 2 && tok == MDOC_Pf) + if (abs(state) < 2 && tok == MDOC_Pf) mandoc_vmsg(MANDOCERR_PF_SKIP, mdoc->parse, line, ppos, "Pf %s", p == NULL ? "at eol" : p); break; } - if ( ! (mdoc_macros[tok].flags & MDOC_IGNDELIM) && - ac != ARGS_QWORD && j == 0 && - mdoc_isdelim(p) == DELIM_OPEN) { - dword(mdoc, line, la, p, DELIM_OPEN, 0); - continue; - } else if (j == 0) - mdoc_elem_alloc(mdoc, line, ppos, tok, arg); - - if (j == maxargs && ! flushed) { + if (state == maxargs) { rew_elem(mdoc, tok); - flushed = 1; + state = -2; } - ntok = (ac == ARGS_QWORD || (tok == MDOC_Pf && j == 0)) ? + ntok = (ac == ARGS_QWORD || (tok == MDOC_Pf && state == 0)) ? MDOC_MAX : lookup(mdoc, tok, line, la, p); if (ntok != MDOC_MAX) { - if ( ! flushed) + if (state >= 0) { rew_elem(mdoc, tok); - flushed = 1; + state = -2; + } mdoc_macro(mdoc, ntok, line, la, pos, buf); - j++; break; } - if ( ! (mdoc_macros[tok].flags & MDOC_IGNDELIM) && - ac != ARGS_QWORD && ! flushed && - mdoc_isdelim(p) != DELIM_NONE) { + if (ac == ARGS_QWORD || + mdoc_macros[tok].flags & MDOC_IGNDELIM || + mdoc_isdelim(p) == DELIM_NONE) { + if (state == -1) { + mdoc_elem_alloc(mdoc, line, ppos, tok, arg); + state = 1; + } else if (state >= 0) + state++; + } else if (state >= 0) { rew_elem(mdoc, tok); - flushed = 1; + state = -2; } dword(mdoc, line, la, p, DELIM_MAX, MDOC_JOIN & mdoc_macros[tok].flags); - j++; } - if (j == 0) { - mdoc_elem_alloc(mdoc, line, ppos, tok, arg); - if (ac == ARGS_PUNCT && tok == MDOC_Pf) - append_delims(mdoc, line, pos, buf); + if (state == -1) { + mandoc_msg(MANDOCERR_MACRO_EMPTY, mdoc->parse, + line, ppos, mdoc_macronames[tok]); + return; } - if ( ! flushed) + + if (state == 0 && tok == MDOC_Pf) + append_delims(mdoc, line, pos, buf); + if (state >= 0) rew_elem(mdoc, tok); if (nl) append_delims(mdoc, line, pos, buf); @@ -1490,10 +1377,24 @@ in_line_argn(MACRO_PROT_ARGS) static void in_line_eoln(MACRO_PROT_ARGS) { - struct mdoc_arg *arg; + struct mdoc_node *n; + struct mdoc_arg *arg; + + if ((tok == MDOC_Pp || tok == MDOC_Lp) && + ! (mdoc->flags & MDOC_SYNOPSIS)) { + n = mdoc->last; + if (mdoc->next == MDOC_NEXT_SIBLING) + n = n->parent; + if (n->tok == MDOC_Nm) + rew_last(mdoc, mdoc->last->parent); + } - if (tok == MDOC_Pp) - rew_sub(MDOC_BLOCK, mdoc, MDOC_Nm, line, ppos); + if (buf[*pos] == '\0' && + (tok == MDOC_Fd || mdoc_macronames[tok][0] == '%')) { + mandoc_msg(MANDOCERR_MACRO_EMPTY, mdoc->parse, + line, ppos, mdoc_macronames[tok]); + return; + } mdoc_argv(mdoc, line, tok, &arg, pos, buf); mdoc_elem_alloc(mdoc, line, ppos, tok, arg); @@ -1543,13 +1444,20 @@ ctx_synopsis(MACRO_PROT_ARGS) static void phrase_ta(MACRO_PROT_ARGS) { - struct mdoc_node *n; + struct mdoc_node *body, *n; /* Make sure we are in a column list or ignore this macro. */ - n = mdoc->last; - while (n != NULL && n->tok != MDOC_Bl) - n = n->parent; + body = NULL; + for (n = mdoc->last; n != NULL; n = n->parent) { + if (n->flags & MDOC_ENDED) + continue; + if (n->tok == MDOC_It && n->type == MDOC_BODY) + body = n; + if (n->tok == MDOC_Bl) + break; + } + if (n == NULL || n->norm->Bl.type != LIST_column) { mandoc_msg(MANDOCERR_TA_STRAY, mdoc->parse, line, ppos, "Ta"); @@ -1558,7 +1466,7 @@ phrase_ta(MACRO_PROT_ARGS) /* Advance to the next column. */ - rew_sub(MDOC_BODY, mdoc, MDOC_It, line, ppos); + rew_last(mdoc, body); mdoc_body_alloc(mdoc, line, ppos, MDOC_It); parse_rest(mdoc, MDOC_MAX, line, pos, buf); } diff --git a/contrib/mdocml/mdoc_man.c b/contrib/mdocml/mdoc_man.c index 974cfbd46f58..9c086a576c4e 100644 --- a/contrib/mdocml/mdoc_man.c +++ b/contrib/mdocml/mdoc_man.c @@ -1,6 +1,6 @@ -/* $Id: mdoc_man.c,v 1.77 2014/11/30 05:29:00 schwarze Exp $ */ +/* $Id: mdoc_man.c,v 1.88 2015/02/17 20:37:17 schwarze Exp $ */ /* - * Copyright (c) 2011, 2012, 2013, 2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2011-2015 Ingo Schwarze <schwarze@openbsd.org> * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -29,8 +29,7 @@ #include "mdoc.h" #include "main.h" -#define DECL_ARGS const struct mdoc_meta *meta, \ - const struct mdoc_node *n +#define DECL_ARGS const struct mdoc_meta *meta, struct mdoc_node *n struct manact { int (*cond)(DECL_ARGS); /* DON'T run actions */ @@ -116,8 +115,8 @@ static void print_word(const char *); static void print_line(const char *, int); static void print_block(const char *, int); static void print_offs(const char *, int); -static void print_width(const char *, - const struct mdoc_node *, size_t); +static void print_width(const struct mdoc_bl *, + const struct mdoc_node *); static void print_count(int *); static void print_node(DECL_ARGS); @@ -186,8 +185,8 @@ static const struct manact manacts[MDOC_MAX + 1] = { { NULL, pre_bx, NULL, NULL, NULL }, /* Bx */ { NULL, pre_skip, NULL, NULL, NULL }, /* Db */ { NULL, NULL, NULL, NULL, NULL }, /* Dc */ - { cond_body, pre_enc, post_enc, "\\(lq", "\\(rq" }, /* Do */ - { cond_body, pre_enc, post_enc, "\\(lq", "\\(rq" }, /* Dq */ + { cond_body, pre_enc, post_enc, "\\(Lq", "\\(Rq" }, /* Do */ + { cond_body, pre_enc, post_enc, "\\(Lq", "\\(Rq" }, /* Dq */ { NULL, NULL, NULL, NULL, NULL }, /* Ec */ { NULL, NULL, NULL, NULL, NULL }, /* Ef */ { NULL, pre_em, post_font, NULL, NULL }, /* Em */ @@ -265,7 +264,7 @@ static int outflags; #define BL_STACK_MAX 32 -static size_t Bl_stack[BL_STACK_MAX]; /* offsets [chars] */ +static int Bl_stack[BL_STACK_MAX]; /* offsets [chars] */ static int Bl_stack_post[BL_STACK_MAX]; /* add final .RE */ static int Bl_stack_len; /* number of nested Bl blocks */ static int TPremain; /* characters before tag is full */ @@ -423,7 +422,7 @@ print_offs(const char *v, int keywords) { char buf[24]; struct roffsu su; - size_t sz; + int sz; print_line(".RS", MMAN_Bk_susp); @@ -434,7 +433,7 @@ print_offs(const char *v, int keywords) sz = 6; else if (keywords && !strcmp(v, "indent-two")) sz = 12; - else if (a2roffsu(v, &su, SCALE_MAX)) { + else if (a2roffsu(v, &su, SCALE_EN) > 1) { if (SCALE_EN == su.unit) sz = su.scale; else { @@ -459,7 +458,7 @@ print_offs(const char *v, int keywords) if (Bl_stack_len) sz += Bl_stack[Bl_stack_len - 1]; - (void)snprintf(buf, sizeof(buf), "%zun", sz); + (void)snprintf(buf, sizeof(buf), "%dn", sz); print_word(buf); outflags |= MMAN_nl; } @@ -468,20 +467,19 @@ print_offs(const char *v, int keywords) * Set up the indentation for a list item; used from pre_it(). */ static void -print_width(const char *v, const struct mdoc_node *child, size_t defsz) +print_width(const struct mdoc_bl *bl, const struct mdoc_node *child) { char buf[24]; struct roffsu su; - size_t sz, chsz; - int numeric, remain; + int numeric, remain, sz, chsz; numeric = 1; remain = 0; - /* Convert v into a number (of characters). */ - if (NULL == v) - sz = defsz; - else if (a2roffsu(v, &su, SCALE_MAX)) { + /* Convert the width into a number (of characters). */ + if (bl->width == NULL) + sz = (bl->type == LIST_hang) ? 6 : 0; + else if (a2roffsu(bl->width, &su, SCALE_MAX) > 1) { if (SCALE_EN == su.unit) sz = su.scale; else { @@ -489,11 +487,15 @@ print_width(const char *v, const struct mdoc_node *child, size_t defsz) numeric = 0; } } else - sz = strlen(v); + sz = strlen(bl->width); /* XXX Rough estimation, might have multiple parts. */ - chsz = (NULL != child && MDOC_TEXT == child->type) ? - strlen(child->string) : 0; + if (bl->type == LIST_enum) + chsz = (bl->count > 8) + 1; + else if (child != NULL && child->type == MDOC_TEXT) + chsz = strlen(child->string); + else + chsz = 0; /* Maybe we are inside an enclosing list? */ mid_it(); @@ -505,17 +507,17 @@ print_width(const char *v, const struct mdoc_node *child, size_t defsz) Bl_stack[Bl_stack_len++] = sz + 2; /* Set up the current list. */ - if (defsz && chsz > sz) + if (chsz > sz && bl->type != LIST_tag) print_block(".HP", 0); else { print_block(".TP", 0); remain = sz + 2; } if (numeric) { - (void)snprintf(buf, sizeof(buf), "%zun", sz + 2); + (void)snprintf(buf, sizeof(buf), "%dn", sz + 2); print_word(buf); } else - print_word(v); + print_word(bl->width); TPremain = remain; } @@ -524,7 +526,7 @@ print_count(int *count) { char buf[24]; - (void)snprintf(buf, sizeof(buf), "%d.", ++*count); + (void)snprintf(buf, sizeof(buf), "%d.\\&", ++*count); print_word(buf); } @@ -545,10 +547,10 @@ void man_mdoc(void *arg, const struct mdoc *mdoc) { const struct mdoc_meta *meta; - const struct mdoc_node *n; + struct mdoc_node *n; meta = mdoc_meta(mdoc); - n = mdoc_node(mdoc); + n = mdoc_node(mdoc)->child; printf(".TH \"%s\" \"%s\" \"%s\" \"%s\" \"%s\"\n", meta->title, @@ -564,15 +566,18 @@ man_mdoc(void *arg, const struct mdoc *mdoc) fontqueue.head = fontqueue.tail = mandoc_malloc(8); *fontqueue.tail = 'R'; } - print_node(meta, n); + while (n != NULL) { + print_node(meta, n); + n = n->next; + } putchar('\n'); } static void print_node(DECL_ARGS) { - const struct mdoc_node *sub; const struct manact *act; + struct mdoc_node *sub; int cond, do_sub; /* @@ -585,6 +590,7 @@ print_node(DECL_ARGS) act = NULL; cond = 0; do_sub = 1; + n->flags &= ~MDOC_ENDED; if (MDOC_TEXT == n->type) { /* @@ -632,7 +638,7 @@ print_node(DECL_ARGS) (*act->post)(meta, n); if (ENDBODY_NOT != n->end) - n->pending->flags |= MDOC_ENDED; + n->body->flags |= MDOC_ENDED; if (ENDBODY_NOSPACE == n->end) outflags &= ~(MMAN_spc | MMAN_nl); @@ -876,8 +882,8 @@ static int pre_aq(DECL_ARGS) { - print_word(n->parent->prev != NULL && - n->parent->prev->tok == MDOC_An ? "<" : "\\(la"); + print_word(n->nchild == 1 && + n->child->tok == MDOC_Mt ? "<" : "\\(la"); outflags &= ~MMAN_spc; return(1); } @@ -887,8 +893,8 @@ post_aq(DECL_ARGS) { outflags &= ~(MMAN_spc | MMAN_nl); - print_word(n->parent->prev != NULL && - n->parent->prev->tok == MDOC_An ? ">" : "\\(ra"); + print_word(n->nchild == 1 && + n->child->tok == MDOC_Mt ? ">" : "\\(ra"); } static int @@ -1003,10 +1009,12 @@ pre_bl(DECL_ARGS) return(1); } - print_line(".TS", MMAN_nl); - for (icol = 0; icol < n->norm->Bl.ncols; icol++) - print_word("l"); - print_word("."); + if (n->nchild) { + print_line(".TS", MMAN_nl); + for (icol = 0; icol < n->norm->Bl.ncols; icol++) + print_word("l"); + print_word("."); + } outflags |= MMAN_nl; return(1); } @@ -1017,7 +1025,8 @@ post_bl(DECL_ARGS) switch (n->norm->Bl.type) { case LIST_column: - print_line(".TE", 0); + if (n->nchild) + print_line(".TE", 0); break; case LIST_enum: n->norm->Bl.count = 0; @@ -1128,16 +1137,37 @@ static int pre_eo(DECL_ARGS) { - outflags &= ~(MMAN_spc | MMAN_nl); + if (n->end == ENDBODY_NOT && + n->parent->head->child == NULL && + n->child != NULL && + n->child->end != ENDBODY_NOT) + print_word("\\&"); + else if (n->end != ENDBODY_NOT ? n->child != NULL : + n->parent->head->child != NULL && (n->child != NULL || + (n->parent->tail != NULL && n->parent->tail->child != NULL))) + outflags &= ~(MMAN_spc | MMAN_nl); return(1); } static void post_eo(DECL_ARGS) { + int body, tail; - if (n->end != ENDBODY_SPACE) + if (n->end != ENDBODY_NOT) { + outflags |= MMAN_spc; + return; + } + + body = n->child != NULL || n->parent->head->child != NULL; + tail = n->parent->tail != NULL && n->parent->tail->child != NULL; + + if (body && tail) outflags &= ~MMAN_spc; + else if ( ! (body || tail)) + print_word("\\&"); + else if ( ! tail) + outflags |= MMAN_spc; } static int @@ -1256,12 +1286,14 @@ pre_fo(DECL_ARGS) pre_syn(n); break; case MDOC_HEAD: + if (n->child == NULL) + return(0); if (MDOC_SYNPRETTY & n->flags) print_block(".HP 4n", MMAN_nl); font_push('B'); break; case MDOC_BODY: - outflags &= ~MMAN_spc; + outflags &= ~(MMAN_spc | MMAN_nl); print_word("("); outflags &= ~MMAN_spc; break; @@ -1277,7 +1309,8 @@ post_fo(DECL_ARGS) switch (n->type) { case MDOC_HEAD: - font_pop(); + if (n->child != NULL) + font_pop(); break; case MDOC_BODY: post_fn(meta, n); @@ -1362,7 +1395,7 @@ pre_it(DECL_ARGS) case LIST_dash: /* FALLTHROUGH */ case LIST_hyphen: - print_width(bln->norm->Bl.width, NULL, 0); + print_width(&bln->norm->Bl, NULL); TPremain = 0; outflags |= MMAN_nl; font_push('B'); @@ -1374,19 +1407,19 @@ pre_it(DECL_ARGS) outflags |= MMAN_nl; return(0); case LIST_enum: - print_width(bln->norm->Bl.width, NULL, 0); + print_width(&bln->norm->Bl, NULL); TPremain = 0; outflags |= MMAN_nl; print_count(&bln->norm->Bl.count); outflags |= MMAN_nl; return(0); case LIST_hang: - print_width(bln->norm->Bl.width, n->child, 6); + print_width(&bln->norm->Bl, n->child); TPremain = 0; outflags |= MMAN_nl; return(1); case LIST_tag: - print_width(bln->norm->Bl.width, n->child, 0); + print_width(&bln->norm->Bl, n->child); putchar('\n'); outflags &= ~MMAN_spc; return(1); @@ -1418,7 +1451,7 @@ mid_it(void) /* Restore the indentation of the enclosing list. */ print_line(".RS", MMAN_Bk_susp); - (void)snprintf(buf, sizeof(buf), "%zun", + (void)snprintf(buf, sizeof(buf), "%dn", Bl_stack[Bl_stack_len - 1]); print_word(buf); diff --git a/contrib/mdocml/mdoc_term.c b/contrib/mdocml/mdoc_term.c index 7f57aed37649..cc44d761248f 100644 --- a/contrib/mdocml/mdoc_term.c +++ b/contrib/mdocml/mdoc_term.c @@ -1,7 +1,7 @@ -/* $Id: mdoc_term.c,v 1.299 2014/12/02 10:08:06 schwarze Exp $ */ +/* $Id: mdoc_term.c,v 1.311 2015/02/17 20:37:17 schwarze Exp $ */ /* * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2010, 2012, 2013, 2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2010, 2012-2015 Ingo Schwarze <schwarze@openbsd.org> * Copyright (c) 2013 Franco Fichtner <franco@lastsummer.de> * * Permission to use, copy, modify, and distribute this software for any @@ -22,6 +22,7 @@ #include <assert.h> #include <ctype.h> +#include <limits.h> #include <stdint.h> #include <stdio.h> #include <stdlib.h> @@ -49,8 +50,7 @@ struct termact { void (*post)(DECL_ARGS); }; -static size_t a2width(const struct termp *, const char *); -static size_t a2height(const struct termp *, const char *); +static int a2width(const struct termp *, const char *); static void print_bvspace(struct termp *, const struct mdoc_node *, @@ -67,6 +67,7 @@ static void termp__t_post(DECL_ARGS); static void termp_bd_post(DECL_ARGS); static void termp_bk_post(DECL_ARGS); static void termp_bl_post(DECL_ARGS); +static void termp_eo_post(DECL_ARGS); static void termp_fd_post(DECL_ARGS); static void termp_fo_post(DECL_ARGS); static void termp_in_post(DECL_ARGS); @@ -91,6 +92,7 @@ static int termp_bt_pre(DECL_ARGS); static int termp_bx_pre(DECL_ARGS); static int termp_cd_pre(DECL_ARGS); static int termp_d1_pre(DECL_ARGS); +static int termp_eo_pre(DECL_ARGS); static int termp_ex_pre(DECL_ARGS); static int termp_fa_pre(DECL_ARGS); static int termp_fd_pre(DECL_ARGS); @@ -190,7 +192,7 @@ static const struct termact termacts[MDOC_MAX] = { { NULL, NULL }, /* Ec */ /* FIXME: no space */ { NULL, NULL }, /* Ef */ { termp_under_pre, NULL }, /* Em */ - { termp_quote_pre, termp_quote_post }, /* Eo */ + { termp_eo_pre, termp_eo_post }, /* Eo */ { termp_xx_pre, NULL }, /* Fx */ { termp_bold_pre, NULL }, /* Ms */ { termp_li_pre, NULL }, /* No */ @@ -291,9 +293,10 @@ static void print_mdoc_nodelist(DECL_ARGS) { - print_mdoc_node(p, pair, meta, n); - if (n->next) - print_mdoc_nodelist(p, pair, meta, n->next); + while (n != NULL) { + print_mdoc_node(p, pair, meta, n); + n = n->next; + } } static void @@ -306,7 +309,8 @@ print_mdoc_node(DECL_ARGS) chld = 1; offset = p->offset; rmargin = p->rmargin; - n->prev_font = term_fontq(p); + n->flags &= ~MDOC_ENDED; + n->prev_font = p->fonti; memset(&npair, 0, sizeof(struct termpair)); npair.ppair = pair; @@ -316,12 +320,9 @@ print_mdoc_node(DECL_ARGS) * invoked in a prior line, revert it to PREKEEP. */ - if (TERMP_KEEP & p->flags) { - if (n->prev ? (n->prev->lastline != n->line) : - (n->parent && n->parent->line != n->line)) { - p->flags &= ~TERMP_KEEP; - p->flags |= TERMP_PREKEEP; - } + if (p->flags & TERMP_KEEP && n->flags & MDOC_LINE) { + p->flags &= ~TERMP_KEEP; + p->flags |= TERMP_PREKEEP; } /* @@ -361,7 +362,7 @@ print_mdoc_node(DECL_ARGS) print_mdoc_nodelist(p, &npair, meta, n->child); term_fontpopq(p, - (ENDBODY_NOT == n->end ? n : n->pending)->prev_font); + (ENDBODY_NOT == n->end ? n : n->body)->prev_font); switch (n->type) { case MDOC_TEXT: @@ -381,7 +382,7 @@ print_mdoc_node(DECL_ARGS) * that it must not call the post handler again. */ if (ENDBODY_NOT != n->end) - n->pending->flags |= MDOC_ENDED; + n->body->flags |= MDOC_ENDED; /* * End of line terminating an implicit block @@ -526,30 +527,15 @@ print_mdoc_head(struct termp *p, const void *arg) free(volume); } -static size_t -a2height(const struct termp *p, const char *v) -{ - struct roffsu su; - - - assert(v); - if ( ! a2roffsu(v, &su, SCALE_VS)) - SCALE_VS_INIT(&su, atoi(v)); - - return(term_vspan(p, &su)); -} - -static size_t +static int a2width(const struct termp *p, const char *v) { struct roffsu su; - assert(v); - if ( ! a2roffsu(v, &su, SCALE_MAX)) { + if (a2roffsu(v, &su, SCALE_MAX) < 2) { SCALE_HS_INIT(&su, term_strlen(p, v)); su.scale /= term_strlen(p, "0"); } - return(term_hspan(p, &su)); } @@ -620,10 +606,10 @@ termp_ll_pre(DECL_ARGS) static int termp_it_pre(DECL_ARGS) { - const struct mdoc_node *bl, *nn; char buf[24]; - int i; - size_t width, offset, ncols, dcol; + const struct mdoc_node *bl, *nn; + size_t ncols, dcol; + int i, offset, width; enum mdoc_list type; if (MDOC_BLOCK == n->type) { @@ -635,15 +621,46 @@ termp_it_pre(DECL_ARGS) type = bl->norm->Bl.type; /* + * Defaults for specific list types. + */ + + switch (type) { + case LIST_bullet: + /* FALLTHROUGH */ + case LIST_dash: + /* FALLTHROUGH */ + case LIST_hyphen: + /* FALLTHROUGH */ + case LIST_enum: + width = term_len(p, 2); + break; + case LIST_hang: + width = term_len(p, 8); + break; + case LIST_column: + /* FALLTHROUGH */ + case LIST_tag: + width = term_len(p, 10); + break; + default: + width = 0; + break; + } + offset = 0; + + /* * First calculate width and offset. This is pretty easy unless * we're a -column list, in which case all prior columns must * be accounted for. */ - width = offset = 0; - - if (bl->norm->Bl.offs) + if (bl->norm->Bl.offs != NULL) { offset = a2width(p, bl->norm->Bl.offs); + if (offset < 0 && (size_t)(-offset) > p->offset) + offset = -p->offset; + else if (offset > SHRT_MAX) + offset = 0; + } switch (type) { case LIST_column: @@ -698,39 +715,11 @@ termp_it_pre(DECL_ARGS) * number for buffering single arguments. See the above * handling for column for how this changes. */ - assert(bl->norm->Bl.width); width = a2width(p, bl->norm->Bl.width) + term_len(p, 2); - break; - } - - /* - * List-type can override the width in the case of fixed-head - * values (bullet, dash/hyphen, enum). Tags need a non-zero - * offset. - */ - - switch (type) { - case LIST_bullet: - /* FALLTHROUGH */ - case LIST_dash: - /* FALLTHROUGH */ - case LIST_hyphen: - /* FALLTHROUGH */ - case LIST_enum: - if (width < term_len(p, 2)) - width = term_len(p, 2); - break; - case LIST_hang: - if (0 == width) - width = term_len(p, 8); - break; - case LIST_column: - /* FALLTHROUGH */ - case LIST_tag: - if (0 == width) - width = term_len(p, 10); - break; - default: + if (width < 0 && (size_t)(-width) > p->offset) + width = -p->offset; + else if (width > SHRT_MAX) + width = 0; break; } @@ -776,16 +765,16 @@ termp_it_pre(DECL_ARGS) case LIST_enum: /* * Weird special case. - * Very narrow enum lists actually hang. + * Some very narrow lists actually hang. */ - if (width == term_len(p, 2)) - p->flags |= TERMP_HANG; /* FALLTHROUGH */ case LIST_bullet: /* FALLTHROUGH */ case LIST_dash: /* FALLTHROUGH */ case LIST_hyphen: + if (width <= (int)term_len(p, 2)) + p->flags |= TERMP_HANG; if (MDOC_HEAD != n->type) break; p->flags |= TERMP_NOBREAK; @@ -874,7 +863,6 @@ termp_it_pre(DECL_ARGS) case LIST_hyphen: /* FALLTHROUGH */ case LIST_tag: - assert(width); if (MDOC_HEAD == n->type) p->rmargin = p->offset + width; else @@ -1104,9 +1092,6 @@ termp_an_pre(DECL_ARGS) return(0); } - if (n->child == NULL) - return(0); - if (p->flags & TERMP_SPLIT) term_newln(p); @@ -1554,6 +1539,7 @@ termp_bd_pre(DECL_ARGS) { size_t tabwidth, lm, len, rm, rmax; struct mdoc_node *nn; + int offset; if (MDOC_BLOCK == n->type) { print_bvspace(p, n, n); @@ -1570,8 +1556,13 @@ termp_bd_pre(DECL_ARGS) p->offset += term_len(p, p->defindent + 1); else if ( ! strcmp(n->norm->Bd.offs, "indent-two")) p->offset += term_len(p, (p->defindent + 1) * 2); - else - p->offset += a2width(p, n->norm->Bd.offs); + else { + offset = a2width(p, n->norm->Bd.offs); + if (offset < 0 && (size_t)(-offset) > p->offset) + p->offset = 0; + else if (offset < SHRT_MAX) + p->offset += offset; + } /* * If -ragged or -filled are specified, the block does nothing @@ -1816,11 +1807,17 @@ termp_in_post(DECL_ARGS) static int termp_sp_pre(DECL_ARGS) { + struct roffsu su; size_t i, len; switch (n->tok) { case MDOC_sp: - len = n->child ? a2height(p, n->child->string) : 1; + if (n->child) { + if ( ! a2roffsu(n->child->string, &su, SCALE_VS)) + su.scale = 1.0; + len = term_vspan(p, &su); + } else + len = 1; break; case MDOC_br: len = 0; @@ -1856,8 +1853,8 @@ termp_quote_pre(DECL_ARGS) case MDOC_Ao: /* FALLTHROUGH */ case MDOC_Aq: - term_word(p, n->parent->prev != NULL && - n->parent->prev->tok == MDOC_An ? "<" : "\\(la"); + term_word(p, n->nchild == 1 && + n->child->tok == MDOC_Mt ? "<" : "\\(la"); break; case MDOC_Bro: /* FALLTHROUGH */ @@ -1876,7 +1873,7 @@ termp_quote_pre(DECL_ARGS) case MDOC_Do: /* FALLTHROUGH */ case MDOC_Dq: - term_word(p, "\\(lq"); + term_word(p, "\\(Lq"); break; case MDOC_En: if (NULL == n->norm->Es || @@ -1884,8 +1881,6 @@ termp_quote_pre(DECL_ARGS) return(1); term_word(p, n->norm->Es->child->string); break; - case MDOC_Eo: - break; case MDOC_Po: /* FALLTHROUGH */ case MDOC_Pq: @@ -1921,16 +1916,14 @@ termp_quote_post(DECL_ARGS) if (n->type != MDOC_BODY && n->type != MDOC_ELEM) return; - if ( ! (n->tok == MDOC_En || - (n->tok == MDOC_Eo && n->end == ENDBODY_SPACE))) - p->flags |= TERMP_NOSPACE; + p->flags |= TERMP_NOSPACE; switch (n->tok) { case MDOC_Ao: /* FALLTHROUGH */ case MDOC_Aq: - term_word(p, n->parent->prev != NULL && - n->parent->prev->tok == MDOC_An ? ">" : "\\(ra"); + term_word(p, n->nchild == 1 && + n->child->tok == MDOC_Mt ? ">" : "\\(ra"); break; case MDOC_Bro: /* FALLTHROUGH */ @@ -1949,17 +1942,15 @@ termp_quote_post(DECL_ARGS) case MDOC_Do: /* FALLTHROUGH */ case MDOC_Dq: - term_word(p, "\\(rq"); + term_word(p, "\\(Rq"); break; case MDOC_En: - if (NULL != n->norm->Es && - NULL != n->norm->Es->child && - NULL != n->norm->Es->child->next) { - p->flags |= TERMP_NOSPACE; + if (n->norm->Es == NULL || + n->norm->Es->child == NULL || + n->norm->Es->child->next == NULL) + p->flags &= ~TERMP_NOSPACE; + else term_word(p, n->norm->Es->child->next->string); - } - break; - case MDOC_Eo: break; case MDOC_Po: /* FALLTHROUGH */ @@ -1987,6 +1978,50 @@ termp_quote_post(DECL_ARGS) } static int +termp_eo_pre(DECL_ARGS) +{ + + if (n->type != MDOC_BODY) + return(1); + + if (n->end == ENDBODY_NOT && + n->parent->head->child == NULL && + n->child != NULL && + n->child->end != ENDBODY_NOT) + term_word(p, "\\&"); + else if (n->end != ENDBODY_NOT ? n->child != NULL : + n->parent->head->child != NULL && (n->child != NULL || + (n->parent->tail != NULL && n->parent->tail->child != NULL))) + p->flags |= TERMP_NOSPACE; + + return(1); +} + +static void +termp_eo_post(DECL_ARGS) +{ + int body, tail; + + if (n->type != MDOC_BODY) + return; + + if (n->end != ENDBODY_NOT) { + p->flags &= ~TERMP_NOSPACE; + return; + } + + body = n->child != NULL || n->parent->head->child != NULL; + tail = n->parent->tail != NULL && n->parent->tail->child != NULL; + + if (body && tail) + p->flags |= TERMP_NOSPACE; + else if ( ! (body || tail)) + term_word(p, "\\&"); + else if ( ! tail) + p->flags &= ~TERMP_NOSPACE; +} + +static int termp_fo_pre(DECL_ARGS) { size_t rmargin = 0; diff --git a/contrib/mdocml/mdoc_validate.c b/contrib/mdocml/mdoc_validate.c index 7990ffe93853..eb531e828987 100644 --- a/contrib/mdocml/mdoc_validate.c +++ b/contrib/mdocml/mdoc_validate.c @@ -1,7 +1,7 @@ -/* $Id: mdoc_validate.c,v 1.263 2014/11/30 05:29:00 schwarze Exp $ */ +/* $Id: mdoc_validate.c,v 1.283 2015/02/23 13:55:55 schwarze Exp $ */ /* * Copyright (c) 2008-2012 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2010-2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2010-2015 Ingo Schwarze <schwarze@openbsd.org> * Copyright (c) 2010 Joerg Sonnenberger <joerg@netbsd.org> * * Permission to use, copy, modify, and distribute this software for any @@ -48,11 +48,6 @@ enum check_ineq { CHECK_EQ }; -enum check_lvl { - CHECK_WARN, - CHECK_ERROR, -}; - typedef void (*v_pre)(PRE_ARGS); typedef void (*v_post)(POST_ARGS); @@ -61,8 +56,6 @@ struct valids { v_post post; }; -static void check_count(struct mdoc *, enum mdoc_type, - enum check_lvl, enum check_ineq, int); static void check_text(struct mdoc *, int, int, char *); static void check_argv(struct mdoc *, struct mdoc_node *, struct mdoc_argv *); @@ -72,11 +65,6 @@ static enum mdoc_sec a2sec(const char *); static size_t macro2len(enum mdoct); static void rewrite_macro2len(char **); -static void bwarn_ge1(POST_ARGS); -static void ewarn_eq1(POST_ARGS); -static void ewarn_ge1(POST_ARGS); -static void hwarn_eq0(POST_ARGS); - static void post_an(POST_ARGS); static void post_at(POST_ARGS); static void post_bf(POST_ARGS); @@ -99,7 +87,6 @@ static void post_fn(POST_ARGS); static void post_fname(POST_ARGS); static void post_fo(POST_ARGS); static void post_hyph(POST_ARGS); -static void post_hyphtext(POST_ARGS); static void post_ignpar(POST_ARGS); static void post_it(POST_ARGS); static void post_lb(POST_ARGS); @@ -157,12 +144,12 @@ static const struct valids mdoc_valids[MDOC_MAX] = { { NULL, NULL }, /* Ev */ { pre_std, post_ex }, /* Ex */ { NULL, post_fa }, /* Fa */ - { NULL, ewarn_ge1 }, /* Fd */ + { NULL, NULL }, /* Fd */ { NULL, NULL }, /* Fl */ { NULL, post_fn }, /* Fn */ { NULL, NULL }, /* Ft */ { NULL, NULL }, /* Ic */ - { NULL, ewarn_eq1 }, /* In */ + { NULL, NULL }, /* In */ { NULL, post_defaults }, /* Li */ { NULL, post_nd }, /* Nd */ { NULL, post_nm }, /* Nm */ @@ -173,18 +160,18 @@ static const struct valids mdoc_valids[MDOC_MAX] = { { NULL, post_st }, /* St */ { NULL, NULL }, /* Va */ { NULL, post_vt }, /* Vt */ - { NULL, ewarn_ge1 }, /* Xr */ - { NULL, ewarn_ge1 }, /* %A */ - { NULL, post_hyphtext }, /* %B */ /* FIXME: can be used outside Rs/Re. */ - { NULL, ewarn_ge1 }, /* %D */ - { NULL, ewarn_ge1 }, /* %I */ - { NULL, ewarn_ge1 }, /* %J */ - { NULL, post_hyphtext }, /* %N */ - { NULL, post_hyphtext }, /* %O */ - { NULL, ewarn_ge1 }, /* %P */ - { NULL, post_hyphtext }, /* %R */ - { NULL, post_hyphtext }, /* %T */ /* FIXME: can be used outside Rs/Re. */ - { NULL, ewarn_ge1 }, /* %V */ + { NULL, NULL }, /* Xr */ + { NULL, NULL }, /* %A */ + { NULL, post_hyph }, /* %B */ /* FIXME: can be used outside Rs/Re. */ + { NULL, NULL }, /* %D */ + { NULL, NULL }, /* %I */ + { NULL, NULL }, /* %J */ + { NULL, post_hyph }, /* %N */ + { NULL, post_hyph }, /* %O */ + { NULL, NULL }, /* %P */ + { NULL, post_hyph }, /* %R */ + { NULL, post_hyph }, /* %T */ /* FIXME: can be used outside Rs/Re. */ + { NULL, NULL }, /* %V */ { NULL, NULL }, /* Ac */ { NULL, NULL }, /* Ao */ { NULL, NULL }, /* Aq */ @@ -246,14 +233,14 @@ static const struct valids mdoc_valids[MDOC_MAX] = { { NULL, NULL }, /* Brq */ { NULL, NULL }, /* Bro */ { NULL, NULL }, /* Brc */ - { NULL, ewarn_ge1 }, /* %C */ + { NULL, NULL }, /* %C */ { pre_obsolete, post_es }, /* Es */ { pre_obsolete, post_en }, /* En */ { NULL, NULL }, /* Dx */ - { NULL, ewarn_ge1 }, /* %Q */ + { NULL, NULL }, /* %Q */ { NULL, post_par }, /* br */ { NULL, post_par }, /* sp */ - { NULL, ewarn_eq1 }, /* %U */ + { NULL, NULL }, /* %U */ { NULL, NULL }, /* Ta */ { NULL, NULL }, /* ll */ }; @@ -311,7 +298,8 @@ mdoc_valid_pre(struct mdoc *mdoc, struct mdoc_node *n) switch (n->type) { case MDOC_TEXT: - check_text(mdoc, n->line, n->pos, n->string); + if (n->sec != SEC_SYNOPSIS || n->parent->tok != MDOC_Fd) + check_text(mdoc, n->line, n->pos, n->string); /* FALLTHROUGH */ case MDOC_TBL: /* FALLTHROUGH */ @@ -338,7 +326,7 @@ mdoc_valid_post(struct mdoc *mdoc) n = mdoc->last; if (n->flags & MDOC_VALID) return; - n->flags |= MDOC_VALID; + n->flags |= MDOC_VALID | MDOC_ENDED; switch (n->type) { case MDOC_TEXT: @@ -373,67 +361,6 @@ mdoc_valid_post(struct mdoc *mdoc) } static void -check_count(struct mdoc *mdoc, enum mdoc_type type, - enum check_lvl lvl, enum check_ineq ineq, int val) -{ - const char *p; - enum mandocerr t; - - if (mdoc->last->type != type) - return; - - switch (ineq) { - case CHECK_LT: - p = "less than "; - if (mdoc->last->nchild < val) - return; - break; - case CHECK_GT: - p = "more than "; - if (mdoc->last->nchild > val) - return; - break; - case CHECK_EQ: - p = ""; - if (val == mdoc->last->nchild) - return; - break; - default: - abort(); - /* NOTREACHED */ - } - - t = lvl == CHECK_WARN ? MANDOCERR_ARGCWARN : MANDOCERR_ARGCOUNT; - mandoc_vmsg(t, mdoc->parse, mdoc->last->line, - mdoc->last->pos, "want %s%d children (have %d)", - p, val, mdoc->last->nchild); -} - -static void -bwarn_ge1(POST_ARGS) -{ - check_count(mdoc, MDOC_BODY, CHECK_WARN, CHECK_GT, 0); -} - -static void -ewarn_eq1(POST_ARGS) -{ - check_count(mdoc, MDOC_ELEM, CHECK_WARN, CHECK_EQ, 1); -} - -static void -ewarn_ge1(POST_ARGS) -{ - check_count(mdoc, MDOC_ELEM, CHECK_WARN, CHECK_GT, 0); -} - -static void -hwarn_eq0(POST_ARGS) -{ - check_count(mdoc, MDOC_HEAD, CHECK_WARN, CHECK_EQ, 0); -} - -static void check_args(struct mdoc *mdoc, struct mdoc_node *n) { int i; @@ -490,24 +417,13 @@ pre_display(PRE_ARGS) static void pre_bl(PRE_ARGS) { - struct mdoc_node *np; struct mdoc_argv *argv, *wa; int i; enum mdocargt mdoclt; enum mdoc_list lt; - if (MDOC_BLOCK != n->type) { - if (ENDBODY_NOT != n->end) { - assert(n->pending); - np = n->pending->parent; - } else - np = n->parent; - - assert(np); - assert(MDOC_BLOCK == np->type); - assert(MDOC_Bl == np->tok); + if (n->type != MDOC_BLOCK) return; - } /* * First figure out which kind of list to use: bind ourselves to @@ -683,25 +599,14 @@ pre_bl(PRE_ARGS) static void pre_bd(PRE_ARGS) { - struct mdoc_node *np; struct mdoc_argv *argv; int i; enum mdoc_disp dt; pre_literal(mdoc, n); - if (MDOC_BLOCK != n->type) { - if (ENDBODY_NOT != n->end) { - assert(n->pending); - np = n->pending->parent; - } else - np = n->parent; - - assert(np); - assert(MDOC_BLOCK == np->type); - assert(MDOC_Bd == np->tok); + if (n->type != MDOC_BLOCK) return; - } for (i = 0; n->args && i < (int)n->args->argc; i++) { argv = n->args->argv + i; @@ -871,22 +776,10 @@ post_bf(POST_ARGS) * element, which contains the goods. */ - if (MDOC_HEAD != mdoc->last->type) { - if (ENDBODY_NOT != mdoc->last->end) { - assert(mdoc->last->pending); - np = mdoc->last->pending->parent->head; - } else if (MDOC_BLOCK != mdoc->last->type) { - np = mdoc->last->parent->head; - } else - np = mdoc->last->head; - - assert(np); - assert(MDOC_HEAD == np->type); - assert(MDOC_Bf == np->tok); + np = mdoc->last; + if (MDOC_HEAD != np->type) return; - } - np = mdoc->last; assert(MDOC_BLOCK == np->parent->type); assert(MDOC_Bf == np->parent->tok); @@ -941,13 +834,12 @@ post_lb(POST_ARGS) const char *stdlibname; char *libname; - check_count(mdoc, MDOC_ELEM, CHECK_WARN, CHECK_EQ, 1); n = mdoc->last->child; assert(MDOC_TEXT == n->type); if (NULL == (stdlibname = mdoc_a2lib(n->string))) mandoc_asprintf(&libname, - "library \\(lq%s\\(rq", n->string); + "library \\(Lq%s\\(Rq", n->string); else libname = mandoc_strdup(stdlibname); @@ -994,11 +886,27 @@ post_fn(POST_ARGS) static void post_fo(POST_ARGS) { + const struct mdoc_node *n; - check_count(mdoc, MDOC_HEAD, CHECK_WARN, CHECK_EQ, 1); - bwarn_ge1(mdoc); - if (mdoc->last->type == MDOC_HEAD && mdoc->last->nchild) - post_fname(mdoc); + n = mdoc->last; + + if (n->type != MDOC_HEAD) + return; + + if (n->child == NULL) { + mandoc_msg(MANDOCERR_FO_NOHEAD, mdoc->parse, + n->line, n->pos, "Fo"); + return; + } + if (n->child != n->last) { + mandoc_vmsg(MANDOCERR_ARG_EXCESS, mdoc->parse, + n->child->next->line, n->child->next->pos, + "Fo ... %s", n->child->next->string); + while (n->child != n->last) + mdoc_node_delete(mdoc, n->last); + } + + post_fname(mdoc); } static void @@ -1047,50 +955,79 @@ post_vt(POST_ARGS) static void post_nm(POST_ARGS) { + struct mdoc_node *n; + + n = mdoc->last; + + if (n->last != NULL && + (n->last->tok == MDOC_Pp || + n->last->tok == MDOC_Lp)) + mdoc_node_relink(mdoc, n->last); if (NULL != mdoc->meta.name) return; - mdoc_deroff(&mdoc->meta.name, mdoc->last); + mdoc_deroff(&mdoc->meta.name, n); if (NULL == mdoc->meta.name) mandoc_msg(MANDOCERR_NM_NONAME, mdoc->parse, - mdoc->last->line, mdoc->last->pos, "Nm"); + n->line, n->pos, "Nm"); } static void post_nd(POST_ARGS) { + struct mdoc_node *n; + + n = mdoc->last; + + if (n->type != MDOC_BODY) + return; + + if (n->child == NULL) + mandoc_msg(MANDOCERR_ND_EMPTY, mdoc->parse, + n->line, n->pos, "Nd"); - check_count(mdoc, MDOC_BODY, CHECK_ERROR, CHECK_GT, 0); post_hyph(mdoc); } static void post_d1(POST_ARGS) { + struct mdoc_node *n; + + n = mdoc->last; + + if (n->type != MDOC_BODY) + return; + + if (n->child == NULL) + mandoc_msg(MANDOCERR_BLK_EMPTY, mdoc->parse, + n->line, n->pos, "D1"); - bwarn_ge1(mdoc); post_hyph(mdoc); } static void post_literal(POST_ARGS) { + struct mdoc_node *n; - if (mdoc->last->tok == MDOC_Bd) - hwarn_eq0(mdoc); - bwarn_ge1(mdoc); + n = mdoc->last; - /* - * The `Dl' (note "el" not "one") and `Bd' macros unset the - * MDOC_LITERAL flag as they leave. Note that `Bd' only sets - * this in literal mode, but it doesn't hurt to just switch it - * off in general since displays can't be nested. - */ + if (n->type != MDOC_BODY) + return; + + if (n->child == NULL) + mandoc_msg(MANDOCERR_BLK_EMPTY, mdoc->parse, + n->line, n->pos, mdoc_macronames[n->tok]); - if (MDOC_BODY == mdoc->last->type) - mdoc->flags &= ~MDOC_LITERAL; + if (n->tok == MDOC_Bd && + n->norm->Bd.type != DISP_literal && + n->norm->Bd.type != DISP_unfilled) + return; + + mdoc->flags &= ~MDOC_LITERAL; } static void @@ -1164,14 +1101,17 @@ post_at(POST_ARGS) static void post_an(POST_ARGS) { - struct mdoc_node *np; + struct mdoc_node *np, *nch; np = mdoc->last; - if (AUTH__NONE == np->norm->An.auth) { - if (0 == np->child) - check_count(mdoc, MDOC_ELEM, CHECK_WARN, CHECK_GT, 0); - } else if (np->child) - check_count(mdoc, MDOC_ELEM, CHECK_WARN, CHECK_EQ, 0); + nch = np->child; + if (np->norm->An.auth == AUTH__NONE) { + if (nch == NULL) + mandoc_msg(MANDOCERR_MACRO_EMPTY, mdoc->parse, + np->line, np->pos, "An"); + } else if (nch != NULL) + mandoc_vmsg(MANDOCERR_ARG_EXCESS, mdoc->parse, + nch->line, nch->pos, "An ... %s", nch->string); } static void @@ -1197,7 +1137,7 @@ post_it(POST_ARGS) struct mdoc_node *nbl, *nit, *nch; nit = mdoc->last; - if (MDOC_BLOCK != nit->type) + if (nit->type != MDOC_BLOCK) return; nbl = nit->parent->parent; @@ -1213,7 +1153,7 @@ post_it(POST_ARGS) case LIST_inset: /* FALLTHROUGH */ case LIST_diag: - if (NULL == nit->head->child) + if (nit->head->child == NULL) mandoc_vmsg(MANDOCERR_IT_NOHEAD, mdoc->parse, nit->line, nit->pos, "Bl -%s It", @@ -1226,14 +1166,14 @@ post_it(POST_ARGS) case LIST_enum: /* FALLTHROUGH */ case LIST_hyphen: - if (NULL == nit->body->child) + if (nit->body == NULL || nit->body->child == NULL) mandoc_vmsg(MANDOCERR_IT_NOBODY, mdoc->parse, nit->line, nit->pos, "Bl -%s It", mdoc_argnames[nbl->args->argv[0].arg]); /* FALLTHROUGH */ case LIST_item: - if (NULL != nit->head->child) + if (nit->head->child != NULL) mandoc_vmsg(MANDOCERR_ARG_SKIP, mdoc->parse, nit->line, nit->pos, "It %s", nit->head->child->string); @@ -1241,16 +1181,16 @@ post_it(POST_ARGS) case LIST_column: cols = (int)nbl->norm->Bl.ncols; - assert(NULL == nit->head->child); + assert(nit->head->child == NULL); for (i = 0, nch = nit->child; nch; nch = nch->next) - if (MDOC_BODY == nch->type) + if (nch->type == MDOC_BODY) i++; if (i < cols || i > cols + 1) - mandoc_vmsg(MANDOCERR_ARGCOUNT, + mandoc_vmsg(MANDOCERR_BL_COL, mdoc->parse, nit->line, nit->pos, - "columns == %d (have %d)", cols, i); + "%d columns, %d cells", cols, i); break; default: abort(); @@ -1404,13 +1344,21 @@ post_bl_block_tag(POST_ARGS) static void post_bl_head(POST_ARGS) { - struct mdoc_node *np, *nn, *nnp; + struct mdoc_node *nbl, *nh, *nch, *nnext; struct mdoc_argv *argv; int i, j; - if (LIST_column != mdoc->last->norm->Bl.type) { - /* FIXME: this should be ERROR class... */ - hwarn_eq0(mdoc); + nh = mdoc->last; + + if (nh->norm->Bl.type != LIST_column) { + if ((nch = nh->child) == NULL) + return; + mandoc_vmsg(MANDOCERR_ARG_EXCESS, mdoc->parse, + nch->line, nch->pos, "Bl ... %s", nch->string); + while (nch != NULL) { + mdoc_node_delete(mdoc, nch); + nch = nh->child; + } return; } @@ -1420,17 +1368,15 @@ post_bl_head(POST_ARGS) * lists where they're argument values following -column. */ - if (mdoc->last->child == NULL) + if (nh->child == NULL) return; - np = mdoc->last->parent; - assert(np->args); - - for (j = 0; j < (int)np->args->argc; j++) - if (MDOC_Column == np->args->argv[j].arg) + nbl = nh->parent; + for (j = 0; j < (int)nbl->args->argc; j++) + if (nbl->args->argv[j].arg == MDOC_Column) break; - assert(j < (int)np->args->argc); + assert(j < (int)nbl->args->argc); /* * Accommodate for new-style groff column syntax. Shuffle the @@ -1438,25 +1384,23 @@ post_bl_head(POST_ARGS) * column field. Then, delete the head children. */ - argv = np->args->argv + j; + argv = nbl->args->argv + j; i = argv->sz; - argv->sz += mdoc->last->nchild; + argv->sz += nh->nchild; argv->value = mandoc_reallocarray(argv->value, argv->sz, sizeof(char *)); - mdoc->last->norm->Bl.ncols = argv->sz; - mdoc->last->norm->Bl.cols = (void *)argv->value; + nh->norm->Bl.ncols = argv->sz; + nh->norm->Bl.cols = (void *)argv->value; - for (nn = mdoc->last->child; nn; i++) { - argv->value[i] = nn->string; - nn->string = NULL; - nnp = nn; - nn = nn->next; - mdoc_node_delete(NULL, nnp); + for (nch = nh->child; nch != NULL; nch = nnext) { + argv->value[i++] = nch->string; + nch->string = NULL; + nnext = nch->next; + mdoc_node_delete(NULL, nch); } - - mdoc->last->nchild = 0; - mdoc->last->child = NULL; + nh->nchild = 0; + nh->child = NULL; } static void @@ -1480,11 +1424,17 @@ post_bl(POST_ARGS) return; } - bwarn_ge1(mdoc); - nchild = nbody->child; - while (NULL != nchild) { - if (MDOC_It == nchild->tok || MDOC_Sm == nchild->tok) { + if (nchild == NULL) { + mandoc_msg(MANDOCERR_BLK_EMPTY, mdoc->parse, + nbody->line, nbody->pos, "Bl"); + return; + } + while (nchild != NULL) { + if (nchild->tok == MDOC_It || + (nchild->tok == MDOC_Sm && + nchild->next != NULL && + nchild->next->tok == MDOC_It)) { nchild = nchild->next; continue; } @@ -1539,9 +1489,15 @@ post_bl(POST_ARGS) static void post_bk(POST_ARGS) { + struct mdoc_node *n; - hwarn_eq0(mdoc); - bwarn_ge1(mdoc); + n = mdoc->last; + + if (n->type == MDOC_BLOCK && n->body->child == NULL) { + mandoc_msg(MANDOCERR_BLK_EMPTY, + mdoc->parse, n->line, n->pos, "Bk"); + mdoc_node_delete(mdoc, n); + } } static void @@ -1623,13 +1579,6 @@ post_st(POST_ARGS) n = mdoc->last; nch = n->child; - if (NULL == nch) { - mandoc_msg(MANDOCERR_MACRO_EMPTY, mdoc->parse, - n->line, n->pos, mdoc_macronames[n->tok]); - mdoc_node_delete(mdoc, n); - return; - } - assert(MDOC_TEXT == nch->type); if (NULL == (p = mdoc_a2st(nch->string))) { @@ -1645,19 +1594,17 @@ post_st(POST_ARGS) static void post_rs(POST_ARGS) { - struct mdoc_node *nn, *next, *prev; + struct mdoc_node *np, *nch, *next, *prev; int i, j; - switch (mdoc->last->type) { - case MDOC_HEAD: - check_count(mdoc, MDOC_HEAD, CHECK_WARN, CHECK_EQ, 0); - return; - case MDOC_BODY: - if (mdoc->last->child) - break; - check_count(mdoc, MDOC_BODY, CHECK_WARN, CHECK_GT, 0); + np = mdoc->last; + + if (np->type != MDOC_BODY) return; - default: + + if (np->child == NULL) { + mandoc_msg(MANDOCERR_RS_EMPTY, mdoc->parse, + np->line, np->pos, "Rs"); return; } @@ -1668,38 +1615,38 @@ post_rs(POST_ARGS) */ next = NULL; - for (nn = mdoc->last->child->next; nn; nn = next) { - /* Determine order of `nn'. */ + for (nch = np->child->next; nch != NULL; nch = next) { + /* Determine order number of this child. */ for (i = 0; i < RSORD_MAX; i++) - if (rsord[i] == nn->tok) + if (rsord[i] == nch->tok) break; if (i == RSORD_MAX) { mandoc_msg(MANDOCERR_RS_BAD, - mdoc->parse, nn->line, nn->pos, - mdoc_macronames[nn->tok]); + mdoc->parse, nch->line, nch->pos, + mdoc_macronames[nch->tok]); i = -1; - } else if (MDOC__J == nn->tok || MDOC__B == nn->tok) - mdoc->last->norm->Rs.quote_T++; + } else if (nch->tok == MDOC__J || nch->tok == MDOC__B) + np->norm->Rs.quote_T++; /* - * Remove `nn' from the chain. This somewhat + * Remove this child from the chain. This somewhat * repeats mdoc_node_unlink(), but since we're * just re-ordering, there's no need for the * full unlink process. */ - if (NULL != (next = nn->next)) - next->prev = nn->prev; + if ((next = nch->next) != NULL) + next->prev = nch->prev; - if (NULL != (prev = nn->prev)) - prev->next = nn->next; + if ((prev = nch->prev) != NULL) + prev->next = nch->next; - nn->prev = nn->next = NULL; + nch->prev = nch->next = NULL; /* * Scan back until we reach a node that's - * ordered before `nn'. + * to be ordered before this child. */ for ( ; prev ; prev = prev->prev) { @@ -1715,21 +1662,21 @@ post_rs(POST_ARGS) } /* - * Set `nn' back into its correct place in front - * of the `prev' node. + * Set this child back into its correct place + * in front of the `prev' node. */ - nn->prev = prev; + nch->prev = prev; - if (prev) { - if (prev->next) - prev->next->prev = nn; - nn->next = prev->next; - prev->next = nn; + if (prev == NULL) { + np->child->prev = nch; + nch->next = np->child; + np->child = nch; } else { - mdoc->last->child->prev = nn; - nn->next = mdoc->last->child; - mdoc->last->child = nn; + if (prev->next) + prev->next->prev = nch; + nch->next = prev->next; + prev->next = nch; } } } @@ -1741,33 +1688,17 @@ post_rs(POST_ARGS) static void post_hyph(POST_ARGS) { - struct mdoc_node *n, *nch; + struct mdoc_node *nch; char *cp; - n = mdoc->last; - switch (n->type) { - case MDOC_HEAD: - if (MDOC_Sh == n->tok || MDOC_Ss == n->tok) - break; - return; - case MDOC_BODY: - if (MDOC_D1 == n->tok || MDOC_Nd == n->tok) - break; - return; - case MDOC_ELEM: - break; - default: - return; - } - - for (nch = n->child; nch; nch = nch->next) { - if (MDOC_TEXT != nch->type) + for (nch = mdoc->last->child; nch != NULL; nch = nch->next) { + if (nch->type != MDOC_TEXT) continue; cp = nch->string; - if ('\0' == *cp) + if (*cp == '\0') continue; - while ('\0' != *(++cp)) - if ('-' == *cp && + while (*(++cp) != '\0') + if (*cp == '-' && isalpha((unsigned char)cp[-1]) && isalpha((unsigned char)cp[1])) *cp = ASCII_HYPH; @@ -1775,14 +1706,6 @@ post_hyph(POST_ARGS) } static void -post_hyphtext(POST_ARGS) -{ - - ewarn_ge1(mdoc); - post_hyph(mdoc); -} - -static void post_ns(POST_ARGS) { @@ -1825,41 +1748,45 @@ static void post_sh_name(POST_ARGS) { struct mdoc_node *n; + int hasnm, hasnd; - /* - * Warn if the NAME section doesn't contain the `Nm' and `Nd' - * macros (can have multiple `Nm' and one `Nd'). Note that the - * children of the BODY declaration can also be "text". - */ - - if (NULL == (n = mdoc->last->child)) { - mandoc_msg(MANDOCERR_NAMESEC_BAD, mdoc->parse, - mdoc->last->line, mdoc->last->pos, "empty"); - return; - } + hasnm = hasnd = 0; - for ( ; n && n->next; n = n->next) { - if (MDOC_ELEM == n->type && MDOC_Nm == n->tok) - continue; - if (MDOC_TEXT == n->type) - continue; - mandoc_msg(MANDOCERR_NAMESEC_BAD, mdoc->parse, - n->line, n->pos, mdoc_macronames[n->tok]); + for (n = mdoc->last->child; n != NULL; n = n->next) { + switch (n->tok) { + case MDOC_Nm: + hasnm = 1; + break; + case MDOC_Nd: + hasnd = 1; + if (n->next != NULL) + mandoc_msg(MANDOCERR_NAMESEC_ND, + mdoc->parse, n->line, n->pos, NULL); + break; + case MDOC_MAX: + if (hasnm) + break; + /* FALLTHROUGH */ + default: + mandoc_msg(MANDOCERR_NAMESEC_BAD, mdoc->parse, + n->line, n->pos, mdoc_macronames[n->tok]); + break; + } } - assert(n); - if (MDOC_BLOCK == n->type && MDOC_Nd == n->tok) - return; - - mandoc_msg(MANDOCERR_NAMESEC_BAD, mdoc->parse, - n->line, n->pos, mdoc_macronames[n->tok]); + if ( ! hasnm) + mandoc_msg(MANDOCERR_NAMESEC_NONM, mdoc->parse, + mdoc->last->line, mdoc->last->pos, NULL); + if ( ! hasnd) + mandoc_msg(MANDOCERR_NAMESEC_NOND, mdoc->parse, + mdoc->last->line, mdoc->last->pos, NULL); } static void post_sh_see_also(POST_ARGS) { const struct mdoc_node *n; - const char *name, *sec; + const char *name, *sec; const char *lastname, *lastsec, *lastpunct; int cmp; @@ -2061,11 +1988,15 @@ post_ignpar(POST_ARGS) { struct mdoc_node *np; - check_count(mdoc, MDOC_HEAD, CHECK_WARN, CHECK_GT, 0); - post_hyph(mdoc); - - if (MDOC_BODY != mdoc->last->type) + switch (mdoc->last->type) { + case MDOC_HEAD: + post_hyph(mdoc); return; + case MDOC_BODY: + break; + default: + return; + } if (NULL != (np = mdoc->last->child)) if (MDOC_Pp == np->tok || MDOC_Lp == np->tok) { @@ -2123,14 +2054,17 @@ post_par(POST_ARGS) { struct mdoc_node *np; - if (mdoc->last->tok == MDOC_sp) - check_count(mdoc, MDOC_ELEM, CHECK_WARN, CHECK_LT, 2); - else - check_count(mdoc, MDOC_ELEM, CHECK_WARN, CHECK_EQ, 0); + np = mdoc->last; - if (MDOC_ELEM != mdoc->last->type && - MDOC_BLOCK != mdoc->last->type) - return; + if (np->tok == MDOC_sp) { + if (np->nchild > 1) + mandoc_vmsg(MANDOCERR_ARG_EXCESS, mdoc->parse, + np->child->next->line, np->child->next->pos, + "sp ... %s", np->child->next->string); + } else if (np->child != NULL) + mandoc_vmsg(MANDOCERR_ARG_SKIP, + mdoc->parse, np->line, np->pos, "%s %s", + mdoc_macronames[np->tok], np->child->string); if (NULL == (np = mdoc->last->prev)) { np = mdoc->last->parent; @@ -2226,70 +2160,68 @@ post_dt(POST_ARGS) mdoc->meta.vol = NULL; mdoc->meta.arch = NULL; - /* First check that all characters are uppercase. */ + /* Mandatory first argument: title. */ - if (NULL != (nn = n->child)) - for (p = nn->string; *p; p++) { - if (toupper((unsigned char)*p) == *p) - continue; - mandoc_vmsg(MANDOCERR_TITLE_CASE, - mdoc->parse, nn->line, - nn->pos + (p - nn->string), - "Dt %s", nn->string); - break; - } - - /* No argument: msec and arch remain NULL. */ - - if (NULL == (nn = n->child)) { + nn = n->child; + if (nn == NULL || *nn->string == '\0') { mandoc_msg(MANDOCERR_DT_NOTITLE, mdoc->parse, n->line, n->pos, "Dt"); mdoc->meta.title = mandoc_strdup("UNTITLED"); - mdoc->meta.vol = mandoc_strdup("LOCAL"); - goto out; + } else { + mdoc->meta.title = mandoc_strdup(nn->string); + + /* Check that all characters are uppercase. */ + + for (p = nn->string; *p != '\0'; p++) + if (islower((unsigned char)*p)) { + mandoc_vmsg(MANDOCERR_TITLE_CASE, + mdoc->parse, nn->line, + nn->pos + (p - nn->string), + "Dt %s", nn->string); + break; + } } - /* One argument: msec and arch remain NULL. */ + /* Mandatory second argument: section. */ - mdoc->meta.title = mandoc_strdup( - '\0' == nn->string[0] ? "UNTITLED" : nn->string); + if (nn != NULL) + nn = nn->next; - if (NULL == (nn = nn->next)) { + if (nn == NULL) { mandoc_vmsg(MANDOCERR_MSEC_MISSING, mdoc->parse, n->line, n->pos, "Dt %s", mdoc->meta.title); mdoc->meta.vol = mandoc_strdup("LOCAL"); - goto out; + goto out; /* msec and arch remain NULL. */ } - /* Handles: `.Dt TITLE SEC' - * title = TITLE, - * volume = SEC is msec ? format(msec) : SEC, - * msec = SEC is msec ? atoi(msec) : 0, - * arch = NULL - */ + mdoc->meta.msec = mandoc_strdup(nn->string); + + /* Infer volume title from section number. */ cp = mandoc_a2msec(nn->string); - if (cp) { - mdoc->meta.vol = mandoc_strdup(cp); - mdoc->meta.msec = mandoc_strdup(nn->string); - } else { + if (cp == NULL) { mandoc_vmsg(MANDOCERR_MSEC_BAD, mdoc->parse, nn->line, nn->pos, "Dt ... %s", nn->string); mdoc->meta.vol = mandoc_strdup(nn->string); - mdoc->meta.msec = mandoc_strdup(nn->string); - } + } else + mdoc->meta.vol = mandoc_strdup(cp); - /* Handle an optional architecture */ + /* Optional third argument: architecture. */ - if ((nn = nn->next) != NULL) { - for (p = nn->string; *p; p++) - *p = tolower((unsigned char)*p); - mdoc->meta.arch = mandoc_strdup(nn->string); - } + if ((nn = nn->next) == NULL) + goto out; + + for (p = nn->string; *p != '\0'; p++) + *p = tolower((unsigned char)*p); + mdoc->meta.arch = mandoc_strdup(nn->string); + + /* Ignore fourth and later arguments. */ + + if ((nn = nn->next) != NULL) + mandoc_vmsg(MANDOCERR_ARG_EXCESS, mdoc->parse, + nn->line, nn->pos, "Dt ... %s", nn->string); - /* Ignore any subsequent parameters... */ - /* FIXME: warn about subsequent parameters. */ out: mdoc_node_delete(mdoc, n); } diff --git a/contrib/mdocml/msec.c b/contrib/mdocml/msec.c index ffe5024ff1e3..d49d2975b6b1 100644 --- a/contrib/mdocml/msec.c +++ b/contrib/mdocml/msec.c @@ -1,4 +1,4 @@ -/* $Id: msec.c,v 1.13 2014/12/01 08:05:52 schwarze Exp $ */ +/* $Id: msec.c,v 1.14 2014/12/21 14:14:35 schwarze Exp $ */ /* * Copyright (c) 2009 Kristaps Dzonsons <kristaps@bsd.lv> * @@ -20,6 +20,7 @@ #include <string.h> +#include "mandoc.h" #include "libmandoc.h" #define LINE(x, y) \ diff --git a/contrib/mdocml/out.c b/contrib/mdocml/out.c index 7a61b39969c3..53b93fbe00cc 100644 --- a/contrib/mdocml/out.c +++ b/contrib/mdocml/out.c @@ -1,7 +1,7 @@ -/* $Id: out.c,v 1.54 2014/12/04 02:05:42 schwarze Exp $ */ +/* $Id: out.c,v 1.59 2015/01/30 04:11:50 schwarze Exp $ */ /* * Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2011, 2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2011, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -20,8 +20,6 @@ #include <sys/types.h> #include <assert.h> -#include <ctype.h> -#include <stdio.h> #include <stdlib.h> #include <string.h> #include <time.h> @@ -39,97 +37,64 @@ static void tblcalc_number(struct rofftbl *, struct roffcol *, /* - * Convert a `scaling unit' to a consistent form, or fail. Scaling - * units are documented in groff.7, mdoc.7, man.7. + * Parse the *src string and store a scaling unit into *dst. + * If the string doesn't specify the unit, use the default. + * If no default is specified, fail. + * Return 2 on complete success, 1 when a conversion was done, + * but there was trailing garbage, and 0 on total failure. */ int a2roffsu(const char *src, struct roffsu *dst, enum roffscale def) { - char buf[BUFSIZ], hasd; - int i; - enum roffscale unit; + char *endptr; - if ('\0' == *src) + dst->unit = def == SCALE_MAX ? SCALE_BU : def; + dst->scale = strtod(src, &endptr); + if (endptr == src) return(0); - i = hasd = 0; - - switch (*src) { - case '+': - src++; + switch (*endptr++) { + case 'c': + dst->unit = SCALE_CM; break; - case '-': - buf[i++] = *src++; + case 'i': + dst->unit = SCALE_IN; break; - default: + case 'f': + dst->unit = SCALE_FS; break; - } - - if ('\0' == *src) - return(0); - - while (i < BUFSIZ) { - if ( ! isdigit((unsigned char)*src)) { - if ('.' != *src) - break; - else if (hasd) - break; - else - hasd = 1; - } - buf[i++] = *src++; - } - - if (BUFSIZ == i || (*src && *(src + 1))) - return(0); - - buf[i] = '\0'; - - switch (*src) { - case 'c': - unit = SCALE_CM; + case 'M': + dst->unit = SCALE_MM; break; - case 'i': - unit = SCALE_IN; + case 'm': + dst->unit = SCALE_EM; + break; + case 'n': + dst->unit = SCALE_EN; break; case 'P': - unit = SCALE_PC; + dst->unit = SCALE_PC; break; case 'p': - unit = SCALE_PT; + dst->unit = SCALE_PT; break; - case 'f': - unit = SCALE_FS; + case 'u': + dst->unit = SCALE_BU; break; case 'v': - unit = SCALE_VS; - break; - case 'm': - unit = SCALE_EM; + dst->unit = SCALE_VS; break; case '\0': + endptr--; + /* FALLTHROUGH */ + default: if (SCALE_MAX == def) return(0); - unit = def; - break; - case 'u': - unit = SCALE_BU; - break; - case 'M': - unit = SCALE_MM; - break; - case 'n': - unit = SCALE_EN; + dst->unit = def; break; - default: - return(0); } - /* FIXME: do this in the caller. */ - if ((dst->scale = atof(buf)) < 0.0) - dst->scale = 0.0; - dst->unit = unit; - return(1); + return(*endptr == '\0' ? 2 : 1); } /* @@ -142,11 +107,12 @@ void tblcalc(struct rofftbl *tbl, const struct tbl_span *sp, size_t totalwidth) { + const struct tbl_opts *opts; const struct tbl_dat *dp; struct roffcol *col; size_t ewidth, xwidth; int spans; - int icol, maxcol, necol, nxcol; + int icol, maxcol, necol, nxcol, quirkcol; /* * Allocate the master column specifiers. These will hold the @@ -157,6 +123,7 @@ tblcalc(struct rofftbl *tbl, const struct tbl_span *sp, assert(NULL == tbl->cols); tbl->cols = mandoc_calloc((size_t)sp->opts->cols, sizeof(struct roffcol)); + opts = sp->opts; for (maxcol = -1; sp; sp = sp->next) { if (TBL_SPAN_DATA != sp->pos) @@ -173,14 +140,14 @@ tblcalc(struct rofftbl *tbl, const struct tbl_span *sp, spans = dp->spans; if (1 < spans) continue; - icol = dp->layout->head->ident; + icol = dp->layout->col; if (maxcol < icol) maxcol = icol; col = tbl->cols + icol; col->flags |= dp->layout->flags; if (dp->layout->flags & TBL_CELL_WIGN) continue; - tblcalc_data(tbl, col, sp->opts, dp); + tblcalc_data(tbl, col, opts, dp); } } @@ -230,13 +197,35 @@ tblcalc(struct rofftbl *tbl, const struct tbl_span *sp, */ if (nxcol && totalwidth) { - xwidth = totalwidth - 3*maxcol - xwidth; + xwidth = totalwidth - xwidth - 3*maxcol - + (opts->opts & (TBL_OPT_BOX | TBL_OPT_DBOX) ? + 2 : !!opts->lvert + !!opts->rvert); + + /* + * Emulate a bug in GNU tbl width calculation that + * manifests itself for large numbers of x-columns. + * Emulating it for 5 x-columns gives identical + * behaviour for up to 6 x-columns. + */ + + if (nxcol == 5) { + quirkcol = xwidth % nxcol + 2; + if (quirkcol != 3 && quirkcol != 4) + quirkcol = -1; + } else + quirkcol = -1; + + necol = 0; + ewidth = 0; for (icol = 0; icol <= maxcol; icol++) { col = tbl->cols + icol; if ( ! (col->flags & TBL_CELL_WMAX)) continue; - col->width = xwidth / nxcol--; - xwidth -= col->width; + col->width = (double)xwidth * ++necol / nxcol + - ewidth + 0.4995; + if (necol == quirkcol) + col->width--; + ewidth += col->width; } } } diff --git a/contrib/mdocml/preconv.c b/contrib/mdocml/preconv.c index 0c6076ecb425..a2bbe9ca6065 100644 --- a/contrib/mdocml/preconv.c +++ b/contrib/mdocml/preconv.c @@ -1,4 +1,4 @@ -/* $Id: preconv.c,v 1.12 2014/11/14 04:24:04 schwarze Exp $ */ +/* $Id: preconv.c,v 1.13 2014/12/19 04:58:35 schwarze Exp $ */ /* * Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv> * Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org> @@ -19,6 +19,7 @@ #include <sys/types.h> +#include <assert.h> #include <stdio.h> #include <string.h> #include "mandoc.h" @@ -28,88 +29,70 @@ int preconv_encode(struct buf *ib, size_t *ii, struct buf *ob, size_t *oi, int *filenc) { - size_t i; - int state; + unsigned char *cu; + int nby; unsigned int accum; - unsigned char cu; + + cu = ib->buf + *ii; + assert(*cu & 0x80); if ( ! (*filenc & MPARSE_UTF8)) goto latin; - state = 0; - accum = 0U; - - for (i = *ii; i < ib->sz; i++) { - cu = ib->buf[i]; - if (state) { - if ( ! (cu & 128) || (cu & 64)) { - /* Bad sequence header. */ - break; - } - - /* Accept only legitimate bit patterns. */ - - if (cu > 191 || cu < 128) { - /* Bad in-sequence bits. */ - break; - } - - accum |= (cu & 63) << --state * 6; - - if (state) - continue; - - if (accum < 0x80) - ob->buf[(*oi)++] = accum; - else - *oi += snprintf(ob->buf + *oi, - 11, "\\[u%.4X]", accum); - *ii = i + 1; - *filenc &= ~MPARSE_LATIN1; - return(1); - } else { - /* - * Entering a UTF-8 state: if we encounter a - * UTF-8 bitmask, calculate the expected UTF-8 - * state from it. - */ - for (state = 0; state < 7; state++) - if ( ! (cu & (1 << (7 - state)))) - break; - - /* Accept only legitimate bit patterns. */ - - switch (state--) { - case (4): - if (cu <= 244 && cu >= 240) { - accum = (cu & 7) << 18; - continue; - } - /* Bad 4-sequence start bits. */ - break; - case (3): - if (cu <= 239 && cu >= 224) { - accum = (cu & 15) << 12; - continue; - } - /* Bad 3-sequence start bits. */ - break; - case (2): - if (cu <= 223 && cu >= 194) { - accum = (cu & 31) << 6; - continue; - } - /* Bad 2-sequence start bits. */ - break; - default: - /* Bad sequence bit mask. */ - break; - } - break; - } + nby = 1; + while (nby < 5 && *cu & (1 << (7 - nby))) + nby++; + + switch (nby) { + case 2: + accum = *cu & 0x1f; + if (accum < 0x02) /* Obfuscated ASCII. */ + goto latin; + break; + case 3: + accum = *cu & 0x0f; + break; + case 4: + accum = *cu & 0x07; + if (accum > 0x04) /* Beyond Unicode. */ + goto latin; + break; + default: /* Bad sequence header. */ + goto latin; + } + + cu++; + switch (nby) { + case 3: + if ((accum == 0x00 && ! (*cu & 0x20)) || /* Use 2-byte. */ + (accum == 0x0d && *cu & 0x20)) /* Surrogates. */ + goto latin; + break; + case 4: + if ((accum == 0x00 && ! (*cu & 0x30)) || /* Use 3-byte. */ + (accum == 0x04 && *cu & 0x30)) /* Beyond Unicode. */ + goto latin; + break; + default: + break; + } + + while (--nby) { + if ((*cu & 0xc0) != 0x80) /* Invalid continuation. */ + goto latin; + accum <<= 6; + accum += *cu & 0x3f; + cu++; } - /* FALLTHROUGH: Invalid or incomplete UTF-8 sequence. */ + assert(accum > 0x7f); + assert(accum < 0x110000); + assert(accum < 0xd800 || accum > 0xdfff); + + *oi += snprintf(ob->buf + *oi, 11, "\\[u%.4X]", accum); + *ii = (char *)cu - ib->buf; + *filenc &= ~MPARSE_LATIN1; + return(1); latin: if ( ! (*filenc & MPARSE_LATIN1)) diff --git a/contrib/mdocml/read.c b/contrib/mdocml/read.c index 8d6cb1038bec..0b4caa05a9c0 100644 --- a/contrib/mdocml/read.c +++ b/contrib/mdocml/read.c @@ -1,7 +1,7 @@ -/* $Id: read.c,v 1.104 2014/12/01 04:14:14 schwarze Exp $ */ +/* $Id: read.c,v 1.129 2015/03/02 14:50:17 schwarze Exp $ */ /* * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2010-2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2010-2015 Ingo Schwarze <schwarze@openbsd.org> * Copyright (c) 2010, 2012 Joerg Sonnenberger <joerg@netbsd.org> * * Permission to use, copy, modify, and distribute this software for any @@ -80,7 +80,7 @@ static const enum mandocerr mandoclimits[MANDOCLEVEL_MAX] = { MANDOCERR_WARNING, MANDOCERR_WARNING, MANDOCERR_ERROR, - MANDOCERR_FATAL, + MANDOCERR_UNSUPP, MANDOCERR_MAX, MANDOCERR_MAX }; @@ -109,7 +109,11 @@ static const char * const mandocerrs[MANDOCERR_MAX] = { "no document body", "content before first section header", "first section is not \"NAME\"", - "bad NAME section contents", + "NAME section without name", + "NAME section without description", + "description not at the end of NAME", + "bad NAME section content", + "missing description line, using \"\"", "sections out of conventional order", "duplicate section title", "unexpected section", @@ -135,18 +139,22 @@ static const char * const mandocerrs[MANDOCERR_MAX] = { "skipping empty request", "conditional request controls empty scope", "skipping empty macro", + "empty block", "empty argument, using 0n", - "argument count wrong", "missing display type, using -ragged", "list type is not the first argument", "missing -width in -tag list, using 8n", "missing utility name, using \"\"", + "missing function name, using \"\"", "empty head in list item", "empty list item", "missing font type, using \\fR", "unknown font type, using \\fR", "nothing follows prefix", + "empty reference block", "missing -std argument, adding it", + "missing option string, using \"\"", + "missing resource identifier, using \"\"", "missing eqn box, using \"\"", /* related to bad macro arguments */ @@ -156,12 +164,14 @@ static const char * const mandocerrs[MANDOCERR_MAX] = { "skipping duplicate display type", "skipping duplicate list type", "skipping -width argument", + "wrong number of cells", "unknown AT&T UNIX version", "comma in function argument", "parenthesis in function name", "invalid content in Rs block", "invalid Boolean argument", "unknown font, skipping request", + "odd number of characters in request", /* related to plain text */ "blank line in fill mode, using .sp", @@ -171,64 +181,60 @@ static const char * const mandocerrs[MANDOCERR_MAX] = { "invalid escape sequence", "undefined string, using \"\"", - "generic error", + /* related to tables */ + "tbl line starts with span", + "tbl column starts with span", + "skipping vertical bar in tbl layout", - /* related to equations */ - "unexpected equation scope closure", - "equation scope open on exit", - "overlapping equation scopes", - "unexpected end of equation", + "generic error", /* related to tables */ - "bad table syntax", - "bad table option", - "bad table layout", - "no table layout cells specified", - "no table data cells specified", - "ignore data in cell", - "data block still open", - "ignoring extra data cells", + "non-alphabetic character in tbl options", + "skipping unknown tbl option", + "missing tbl option argument", + "wrong tbl option argument size", + "empty tbl layout", + "invalid character in tbl layout", + "unmatched parenthesis in tbl layout", + "tbl without any data cells", + "ignoring data in spanned tbl cell", + "ignoring extra tbl data cells", + "data block open at end of tbl", /* related to document structure and macros */ + NULL, "input stack limit exceeded, infinite loop?", "skipping bad character", "skipping unknown macro", + "skipping insecure request", "skipping item outside list", "skipping column outside column list", "skipping end of block that is not open", + "fewer RS blocks open, skipping", "inserting missing end of block", "appending missing end of block", /* related to request and macro arguments */ "escaped character not allowed in a name", - "argument count wrong", "NOT IMPLEMENTED: Bd -file", "missing list type, using -item", "missing manual name, using \"\"", "uname(3) system call failed, using UNKNOWN", "unknown standard specifier", "skipping request without numeric argument", + "NOT IMPLEMENTED: .so with absolute path or \"..\"", + ".so request failed", "skipping all arguments", "skipping excess arguments", "divide by zero", - "generic fatal error", - + "unsupported feature", "input too large", - "NOT IMPLEMENTED: .so with absolute path or \"..\"", - ".so request failed", - - /* system errors */ - "cannot dup file descriptor", - "cannot exec", - "gunzip failed with code", - "cannot fork", - NULL, - "cannot open pipe", - "cannot read file", - "gunzip died from signal", - "cannot stat file", - "wait failed", + "unsupported control character", + "unsupported roff request", + "eqn delim option in tbl", + "unsupported tbl layout modifier", + "ignoring macro in table", }; static const char * const mandoclevels[MANDOCLEVEL_MAX] = { @@ -236,7 +242,7 @@ static const char * const mandoclevels[MANDOCLEVEL_MAX] = { "RESERVED", "WARNING", "ERROR", - "FATAL", + "UNSUPP", "BADARG", "SYSERR" }; @@ -297,7 +303,8 @@ choose_parser(struct mparse *curp) /* Fall back to man(7) as a last resort. */ if (NULL == curp->pman) - curp->pman = man_alloc(curp->roff, curp, + curp->pman = man_alloc( + curp->roff, curp, curp->defos, MPARSE_QUICK & curp->options ? 1 : 0); assert(curp->pman); curp->man = curp->pman; @@ -315,10 +322,14 @@ mparse_buf_r(struct mparse *curp, struct buf blk, size_t i, int start) { const struct tbl_span *span; struct buf ln; + const char *save_file; + char *cp; size_t pos; /* byte number in the ln buffer */ enum rofferr rr; int of; int lnn; /* line number in the real file */ + int fd; + pid_t save_child; unsigned char c; memset(&ln, 0, sizeof(ln)); @@ -373,9 +384,8 @@ mparse_buf_r(struct mparse *curp, struct buf blk, size_t i, int start) if (c & 0x80) { if ( ! (curp->filenc && preconv_encode( &blk, &i, &ln, &pos, &curp->filenc))) { - mandoc_vmsg(MANDOCERR_BADCHAR, - curp, curp->line, pos, - "0x%x", c); + mandoc_vmsg(MANDOCERR_CHAR_BAD, curp, + curp->line, pos, "0x%x", c); ln.buf[pos++] = '?'; i++; } @@ -387,10 +397,13 @@ mparse_buf_r(struct mparse *curp, struct buf blk, size_t i, int start) */ if (c == 0x7f || (c < 0x20 && c != 0x09)) { - mandoc_vmsg(MANDOCERR_BADCHAR, curp, - curp->line, pos, "0x%x", c); + mandoc_vmsg(c == 0x00 || c == 0x04 || + c > 0x0a ? MANDOCERR_CHAR_BAD : + MANDOCERR_CHAR_UNSUPP, + curp, curp->line, pos, "0x%x", c); i++; - ln.buf[pos++] = '?'; + if (c != '\r') + ln.buf[pos++] = '?'; continue; } @@ -444,7 +457,7 @@ mparse_buf_r(struct mparse *curp, struct buf blk, size_t i, int start) if ( ! (isascii(c) && (isgraph(c) || isblank(c)))) { - mandoc_vmsg(MANDOCERR_BADCHAR, curp, + mandoc_vmsg(MANDOCERR_CHAR_BAD, curp, curp->line, pos, "0x%x", c); i += 2; ln.buf[pos++] = '?'; @@ -513,9 +526,6 @@ rerun: case ROFF_IGN: pos = 0; continue; - case ROFF_ERR: - assert(MANDOCLEVEL_FATAL <= curp->file_status); - break; case ROFF_SO: if ( ! (curp->options & MPARSE_SO) && (i >= blk.sz || blk.buf[i] == '\0')) { @@ -530,13 +540,26 @@ rerun: */ if (curp->secondary) curp->secondary->sz -= pos + 1; - mparse_readfd(curp, -1, ln.buf + of); - if (MANDOCLEVEL_FATAL <= curp->file_status) { + save_file = curp->file; + save_child = curp->child; + if (mparse_open(curp, &fd, ln.buf + of) == + MANDOCLEVEL_OK) { + mparse_readfd(curp, fd, ln.buf + of); + curp->file = save_file; + } else { + curp->file = save_file; mandoc_vmsg(MANDOCERR_SO_FAIL, curp, curp->line, pos, ".so %s", ln.buf + of); - break; + ln.sz = mandoc_asprintf(&cp, + ".sp\nSee the file %s.\n.sp", + ln.buf + of); + free(ln.buf); + ln.buf = cp; + of = 0; + mparse_buf_r(curp, ln, of, 0); } + curp->child = save_child; pos = 0; continue; default: @@ -544,14 +567,6 @@ rerun: } /* - * If we encounter errors in the recursive parse, make - * sure we don't continue parsing. - */ - - if (MANDOCLEVEL_FATAL <= curp->file_status) - break; - - /* * If input parsers have not been allocated, do so now. * We keep these instanced between parsers, but set them * locally per parse routine since we can use different @@ -609,11 +624,8 @@ read_whole_file(struct mparse *curp, const char *file, int fd, #if HAVE_MMAP struct stat st; if (-1 == fstat(fd, &st)) { - curp->file_status = MANDOCLEVEL_SYSERR; - if (curp->mmsg) - (*curp->mmsg)(MANDOCERR_SYSSTAT, curp->file_status, - file, 0, 0, strerror(errno)); - return(0); + perror(file); + exit((int)MANDOCLEVEL_SYSERR); } /* @@ -625,10 +637,7 @@ read_whole_file(struct mparse *curp, const char *file, int fd, if (S_ISREG(st.st_mode)) { if (st.st_size >= (1U << 31)) { - curp->file_status = MANDOCLEVEL_FATAL; - if (curp->mmsg) - (*curp->mmsg)(MANDOCERR_TOOLARGE, - curp->file_status, file, 0, 0, NULL); + mandoc_msg(MANDOCERR_TOOLARGE, curp, 0, 0, NULL); return(0); } *with_mmap = 1; @@ -651,11 +660,8 @@ read_whole_file(struct mparse *curp, const char *file, int fd, for (;;) { if (off == fb->sz) { if (fb->sz == (1U << 31)) { - curp->file_status = MANDOCLEVEL_FATAL; - if (curp->mmsg) - (*curp->mmsg)(MANDOCERR_TOOLARGE, - curp->file_status, - file, 0, 0, NULL); + mandoc_msg(MANDOCERR_TOOLARGE, curp, + 0, 0, NULL); break; } resize_buf(fb, 65536); @@ -666,12 +672,8 @@ read_whole_file(struct mparse *curp, const char *file, int fd, return(1); } if (ssz == -1) { - curp->file_status = MANDOCLEVEL_SYSERR; - if (curp->mmsg) - (*curp->mmsg)(MANDOCERR_SYSREAD, - curp->file_status, file, 0, 0, - strerror(errno)); - break; + perror(file); + exit((int)MANDOCLEVEL_SYSERR); } off += (size_t)ssz; } @@ -685,9 +687,6 @@ static void mparse_end(struct mparse *curp) { - if (MANDOCLEVEL_FATAL <= curp->file_status) - return; - if (curp->mdoc == NULL && curp->man == NULL && curp->sodest == NULL) { @@ -695,22 +694,16 @@ mparse_end(struct mparse *curp) curp->mdoc = curp->pmdoc; else { if (curp->pman == NULL) - curp->pman = man_alloc(curp->roff, curp, + curp->pman = man_alloc( + curp->roff, curp, curp->defos, curp->options & MPARSE_QUICK ? 1 : 0); curp->man = curp->pman; } } - - if (curp->mdoc && ! mdoc_endparse(curp->mdoc)) { - assert(MANDOCLEVEL_FATAL <= curp->file_status); - return; - } - - if (curp->man && ! man_endparse(curp->man)) { - assert(MANDOCLEVEL_FATAL <= curp->file_status); - return; - } - + if (curp->mdoc) + mdoc_endparse(curp->mdoc); + if (curp->man) + man_endparse(curp->man); roff_endparse(curp->roff); } @@ -747,7 +740,7 @@ mparse_parse_buffer(struct mparse *curp, struct buf blk, const char *file) mparse_buf_r(curp, blk, offset, 1); - if (0 == --recursion_depth && MANDOCLEVEL_FATAL > curp->file_status) + if (--recursion_depth == 0) mparse_end(curp); curp->primary = svprimary; @@ -768,8 +761,6 @@ mparse_readmem(struct mparse *curp, void *buf, size_t len, } /* - * If a file descriptor is given, use it and assume it points - * to the named file. Otherwise, open the named file. * Read the whole file into memory and call the parsers. * Called recursively when an .so request is encountered. */ @@ -779,13 +770,6 @@ mparse_readfd(struct mparse *curp, int fd, const char *file) struct buf blk; int with_mmap; int save_filenc; - pid_t save_child; - - save_child = curp->child; - if (fd != -1) - curp->child = 0; - else if (mparse_open(curp, &fd, file) >= MANDOCLEVEL_SYSERR) - goto out; if (read_whole_file(curp, file, fd, &blk, &with_mmap)) { save_filenc = curp->filenc; @@ -805,8 +789,6 @@ mparse_readfd(struct mparse *curp, int fd, const char *file) perror(file); mparse_wait(curp); -out: - curp->child = save_child; return(curp->file_status); } @@ -816,9 +798,7 @@ mparse_open(struct mparse *curp, int *fd, const char *file) int pfd[2]; int save_errno; char *cp; - enum mandocerr err; - pfd[1] = -1; curp->file = file; /* Unless zipped, try to just open the file. */ @@ -842,50 +822,38 @@ mparse_open(struct mparse *curp, int *fd, const char *file) if (access(file, R_OK) == -1) { if (cp != NULL) errno = save_errno; - err = MANDOCERR_SYSOPEN; - goto out; + free(cp); + *fd = -1; + curp->child = 0; + mandoc_msg(MANDOCERR_FILE, curp, 0, 0, strerror(errno)); + return(MANDOCLEVEL_ERROR); } /* Run gunzip(1). */ if (pipe(pfd) == -1) { - err = MANDOCERR_SYSPIPE; - goto out; + perror("pipe"); + exit((int)MANDOCLEVEL_SYSERR); } switch (curp->child = fork()) { case -1: - err = MANDOCERR_SYSFORK; - close(pfd[0]); - close(pfd[1]); - pfd[1] = -1; - break; + perror("fork"); + exit((int)MANDOCLEVEL_SYSERR); case 0: close(pfd[0]); if (dup2(pfd[1], STDOUT_FILENO) == -1) { - err = MANDOCERR_SYSDUP; - break; + perror("dup"); + exit((int)MANDOCLEVEL_SYSERR); } execlp("gunzip", "gunzip", "-c", file, NULL); - err = MANDOCERR_SYSEXEC; - break; + perror("exec"); + exit((int)MANDOCLEVEL_SYSERR); default: close(pfd[1]); *fd = pfd[0]; return(MANDOCLEVEL_OK); } - -out: - free(cp); - *fd = -1; - curp->child = 0; - curp->file_status = MANDOCLEVEL_SYSERR; - if (curp->mmsg) - (*curp->mmsg)(err, curp->file_status, curp->file, - 0, 0, strerror(errno)); - if (pfd[1] != -1) - exit(1); - return(curp->file_status); } enum mandoclevel @@ -897,22 +865,19 @@ mparse_wait(struct mparse *curp) return(MANDOCLEVEL_OK); if (waitpid(curp->child, &status, 0) == -1) { - mandoc_msg(MANDOCERR_SYSWAIT, curp, 0, 0, - strerror(errno)); - curp->file_status = MANDOCLEVEL_SYSERR; - return(curp->file_status); + perror("wait"); + exit((int)MANDOCLEVEL_SYSERR); } + curp->child = 0; if (WIFSIGNALED(status)) { - mandoc_vmsg(MANDOCERR_SYSSIG, curp, 0, 0, - "%d", WTERMSIG(status)); - curp->file_status = MANDOCLEVEL_SYSERR; - return(curp->file_status); + mandoc_vmsg(MANDOCERR_FILE, curp, 0, 0, + "gunzip died from signal %d", WTERMSIG(status)); + return(MANDOCLEVEL_ERROR); } if (WEXITSTATUS(status)) { - mandoc_vmsg(MANDOCERR_SYSEXIT, curp, 0, 0, - "%d", WEXITSTATUS(status)); - curp->file_status = MANDOCLEVEL_SYSERR; - return(curp->file_status); + mandoc_vmsg(MANDOCERR_FILE, curp, 0, 0, + "gunzip failed with code %d", WEXITSTATUS(status)); + return(MANDOCLEVEL_ERROR); } return(MANDOCLEVEL_OK); } @@ -923,8 +888,6 @@ mparse_alloc(int options, enum mandoclevel wlevel, mandocmsg mmsg, { struct mparse *curp; - assert(wlevel <= MANDOCLEVEL_FATAL); - curp = mandoc_calloc(1, sizeof(struct mparse)); curp->options = options; @@ -939,7 +902,8 @@ mparse_alloc(int options, enum mandoclevel wlevel, mandocmsg mmsg, curp->roff, curp, curp->defos, curp->options & MPARSE_QUICK ? 1 : 0); if (curp->options & MPARSE_MAN) - curp->pman = man_alloc(curp->roff, curp, + curp->pman = man_alloc( + curp->roff, curp, curp->defos, curp->options & MPARSE_QUICK ? 1 : 0); return(curp); @@ -1020,11 +984,11 @@ mandoc_msg(enum mandocerr er, struct mparse *m, { enum mandoclevel level; - level = MANDOCLEVEL_FATAL; + level = MANDOCLEVEL_UNSUPP; while (er < mandoclimits[level]) level--; - if (level < m->wlevel) + if (level < m->wlevel && er != MANDOCERR_FILE) return; if (m->mmsg) diff --git a/contrib/mdocml/roff.7 b/contrib/mdocml/roff.7 index 6ee29321884d..dc39b69bb56b 100644 --- a/contrib/mdocml/roff.7 +++ b/contrib/mdocml/roff.7 @@ -1,4 +1,4 @@ -.\" $Id: roff.7,v 1.60 2014/12/02 10:08:06 schwarze Exp $ +.\" $Id: roff.7,v 1.70 2015/02/17 17:16:52 schwarze Exp $ .\" .\" Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> .\" Copyright (c) 2010, 2011, 2013, 2014 Ingo Schwarze <schwarze@openbsd.org> @@ -15,7 +15,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: December 2 2014 $ +.Dd $Mdocdate: February 17 2015 $ .Dt ROFF 7 .Os .Sh NAME @@ -395,27 +395,32 @@ The .Xr mandoc 1 .Nm parser recognises the following requests. -Note that the -.Nm -language defines many more requests not implemented in -.Xr mandoc 1 . +For requests marked as "ignored" or "unsupported", any arguments are +ignored, and the number of arguments is not checked. +.Ss \&ab +Abort processing. +Currently unsupported. .Ss \&ad Set line adjustment mode. -This line-scoped request is intended to have one argument to select -normal, left, right, or centre adjustment for subsequent text. -Currently, it is ignored including its arguments, -and the number of arguments is not checked. +It takes one argument to select normal, left, right, +or center adjustment for subsequent text. +Currently ignored. +.Ss \&af +Assign an output format to a number register. +Currently ignored. +.Ss \&aln +Create an alias for a number register. +Currently unsupported. +.Ss \&als +Create an alias for a request, string, macro, or diversion. +Currently unsupported. .Ss \&am Append to a macro definition. The syntax of this request is the same as that of .Sx \&de . -.Ss \&ami -Append to a macro definition, specifying the macro name indirectly. -The syntax of this request is the same as that of -.Sx \&dei . .Ss \&am1 Append to a macro definition, switching roff compatibility mode off -during macro execution. +during macro execution (groff extension). The syntax of this request is the same as that of .Sx \&de1 . Since @@ -424,14 +429,96 @@ does not implement .Nm compatibility mode at all, it handles this request as an alias for .Sx \&am . +.Ss \&ami +Append to a macro definition, specifying the macro name indirectly +(groff extension). +The syntax of this request is the same as that of +.Sx \&dei . +.Ss \&ami1 +Append to a macro definition, specifying the macro name indirectly +and switching roff compatibility mode off during macro execution +(groff extension). +The syntax of this request is the same as that of +.Sx \&dei1 . +Since +.Xr mandoc 1 +does not implement +.Nm +compatibility mode at all, it handles this request as an alias for +.Sx \&ami . .Ss \&as Append to a user-defined string. The syntax of this request is the same as that of .Sx \&ds . If a user-defined string with the specified name does not yet exist, it is set to the empty string before appending. +.Ss \&as1 +Append to a user-defined string, switching roff compatibility mode off +during macro execution (groff extension). +The syntax of this request is the same as that of +.Sx \&ds1 . +Since +.Xr mandoc 1 +does not implement +.Nm +compatibility mode at all, it handles this request as an alias for +.Sx \&as . +.Ss \&asciify +Fully unformat a diversion. +Currently unsupported. +.Ss \&backtrace +Print a backtrace of the input stack. +This is a groff extension and currently ignored. +.Ss \&bd +Artificially embolden by repeated printing with small shifts. +Currently ignored. +.Ss \&bleedat +Set the BleedBox page parameter for PDF generation. +This is a Heirloom extension and currently ignored. +.Ss \&blm +Set a blank line trap. +Currently unsupported. +.Ss \&box +Begin a diversion without including a partially filled line. +Currently unsupported. +.Ss \&boxa +Add to a diversion without including a partially filled line. +Currently unsupported. +.Ss \&bp +Begin new page. +Currently ignored. +.Ss \&BP +Define a frame and place a picture in it. +This is a Heirloom extension and currently unsupported. +.Ss \&br +Break the output line. +See +.Xr man 7 +and +.Xr mdoc 7 . +.Ss \&break +Break out of a +.Sx \&while +loop. +Currently unsupported. +.Ss \&breakchar +Optional line break characters. +This is a Heirloom extension and currently ignored. +.Ss \&brnl +Break output line after next N input lines. +This is a Heirloom extension and currently ignored. +.Ss \&brp +Break and spread output line. +Currently, this is implemented as an alias for +.Sx \&br . +.Ss \&brpnl +Break and spread output line after next N input lines. +This is a Heirloom extension and currently ignored. +.Ss \&c2 +Change the no-break control character. +Currently unsupported. .Ss \&cc -Changes the control character. +Change the control character. Its syntax is as follows: .Bd -literal -offset indent .Pf . Cm \&cc Op Ar c @@ -444,10 +531,63 @@ is not specified, the control character is reset to Trailing characters are ignored. .Ss \&ce Center some lines. -This line-scoped request is intended to take one integer argument, -specifying how many lines to center. -Currently, it is ignored including its arguments, and the number -of arguments is not checked. +It takes one integer argument, specifying how many lines to center. +Currently ignored. +.Ss \&cf +Output the contents of a file. +Ignored because insecure. +.Ss \&cflags +Set character flags. +This is a groff extension and currently ignored. +.Ss \&ch +Change a trap location. +Currently ignored. +.Ss \&char +Define a new glyph. +Currently unsupported. +.Ss \&chop +Remove the last character from a macro, string, or diversion. +Currently unsupported. +.Ss \&class +Define a character class. +This is a groff extension and currently ignored. +.Ss \&close +Close an open file. +Ignored because insecure. +.Ss \&CL +Print text in color. +This is a Heirloom extension and currently unsupported. +.Ss \&color +Activate or deactivate colors. +This is a groff extension and currently ignored. +.Ss \&composite +Define a name component for composite glyph names. +This is a groff extension and currently unsupported. +.Ss \&continue +Immediately start the next iteration of a +.Sx \&while +loop. +Currently unsupported. +.Ss \&cp +Switch +.Nm +compatibility mode on or off. +Currently ignored. +.Ss \&cropat +Set the CropBox page parameter for PDF generation. +This is a Heirloom extension and currently ignored. +.Ss \&cs +Constant character spacing mode. +Currently ignored. +.Ss \&cu +Underline including whitespace. +Currently ignored. +.Ss \&da +Append to a diversion. +Currently unsupported. +.Ss \&dch +Change a trap location in the current diversion. +This is a Heirloom extension and currently unsupported. .Ss \&de Define a .Nm @@ -543,12 +683,30 @@ one explicit newline character. In order to prevent endless recursion, both groff and .Xr mandoc 1 limit the stack depth for expanding macros and strings -to a large, but finite number. -Do not rely on the exact value of this limit. +to a large, but finite number, and +.Xr mandoc 1 +also limits the length of the expanded input line. +Do not rely on the exact values of these limits. +.Ss \&de1 +Define a +.Nm +macro that will be executed with +.Nm +compatibility mode switched off during macro execution. +This is a groff extension. +Since +.Xr mandoc 1 +does not implement +.Nm +compatibility mode at all, it handles this request as an alias for +.Sx \&de . +.Ss \&defcolor +Define a color name. +This is a groff extension and currently ignored. .Ss \&dei Define a .Nm -macro, specifying the macro name indirectly. +macro, specifying the macro name indirectly (groff extension). The syntax of this request is the same as that of .Sx \&de . The request @@ -558,21 +716,33 @@ The request has the same effect as: .Pp .D1 Pf . Cm \&de No \e* Ns Bo Ar name Bc Op \e* Ns Bq Ar end -.Ss \&de1 +.Ss \&dei1 Define a .Nm macro that will be executed with .Nm -compatibility mode switched off during macro execution. -This is a GNU extension not available in traditional -.Nm -implementations and not even in older versions of groff. +compatibility mode switched off during macro execution, +specifying the macro name indirectly (groff extension). Since .Xr mandoc 1 does not implement .Nm compatibility mode at all, it handles this request as an alias for -.Sx \&de . +.Sx \&dei . +.Ss \&device +This request only makes sense with the groff-specific intermediate +output format and is unsupported. +.Ss \&devicem +This request only makes sense with the groff-specific intermediate +output format and is unsupported. +.Ss \&di +Begin a diversion. +Currently unsupported. +.Ss \&do +Execute +.Nm +request or macro line with compatibility mode disabled. +Currently unsupported. .Ss \&ds Define a user-defined string. Its syntax is as follows: @@ -631,6 +801,32 @@ macro when used in a .Xr man 7 document. Such abuse is of course strongly discouraged. +.Ss \&ds1 +Define a user-defined string that will be expanded with +.Nm +compatibility mode switched off during string expansion. +This is a groff extension. +Since +.Xr mandoc 1 +does not implement +.Nm +compatibility mode at all, it handles this request as an alias for +.Sx \&ds . +.Ss \&dwh +Set a location trap in the current diversion. +This is a Heirloom extension and currently unsupported. +.Ss \&dt +Set a trap within a diversion. +Currently unsupported. +.Ss \&ec +Change the escape character. +Currently unsupported. +.Ss \&ecs +Restore the escape character. +Currently unsupported. +.Ss \&ecr +Save the escape character. +Currently unsupported. .Ss \&el The .Qq else @@ -645,21 +841,89 @@ then false is assumed. The syntax of this request is similar to .Sx \&if except that the conditional is missing. +.Ss \&em +Set a trap at the end of input. +Currently unsupported. .Ss \&EN End an equation block. See .Sx \&EQ . +.Ss \&eo +Disable the escape mechanism completely. +Currently unsupported. +.Ss \&EP +End a picture started by +.Sx \&BP . +This is a Heirloom extension and currently unsupported. .Ss \&EQ Begin an equation block. See .Xr eqn 7 for a description of the equation language. +.Ss \&errprint +Print a string like an error message. +This is a Heirloom extension and currently ignored. +.Ss \&ev +Switch to another environment. +Currently unsupported. +.Ss \&evc +Copy an environment into the current environment. +Currently unsupported. +.Ss \&ex +Abort processing and exit. +Currently unsupported. +.Ss \&fallback +Select the fallback sequence for a font. +This is a Heirloom extension and currently ignored. .Ss \&fam Change the font family. -This line-scoped request is intended to have one argument specifying -the font family to be selected. -It is a groff extension, and currently, it is ignored including its -arguments, and the number of arguments is not checked. +Takes one argument specifying the font family to be selected. +It is a groff extension and currently ignored. +.Ss \&fc +Define a delimiting and a padding character for fields. +Currently unsupported. +.Ss \&fchar +Define a fallback glyph. +Currently unsupported. +.Ss \&fcolor +Set the fill color for \eD objects. +This is a groff extension and currently ignored. +.Ss \&fdeferlig +Defer ligature building. +This is a Heirloom extension and currently ignored. +.Ss \&feature +Enable or disable an OpenType feature. +This is a Heirloom extension and currently ignored. +.Ss \&fi +Switch to fill mode. +See +.Xr man 7 . +Ignored in +.Xr mdoc 7 . +.Ss \&fkern +Control the use of kerning tables for a font. +This is a Heirloom extension and currently ignored. +.Ss \&fl +Flush output. +Currently ignored. +.Ss \&flig +Define ligatures. +This is a Heirloom extension and currently ignored. +.Ss \&fp +Assign font position. +Currently ignored. +.Ss \&fps +Mount a font with a special character map. +This is a Heirloom extension and currently ignored. +.Ss \&fschar +Define a font-specific fallback glyph. +This is a groff extension and currently unsupported. +.Ss \&fspacewidth +Set a font-specific width for the space character. +This is a Heirloom extension and currently ignored. +.Ss \&fspecial +Conditionally define a special font. +This is a groff extension and currently ignored. .Ss \&ft Change the font. Its syntax is as follows: @@ -688,12 +952,60 @@ This request takes effect only locally, may be overridden by macros and escape sequences, and is only supported in .Xr man 7 for now. +.Ss \&ftr +Translate font name. +This is a groff extension and currently ignored. +.Ss \&fzoom +Zoom font size. +Currently ignored. +.Ss \&gcolor +Set glyph color. +This is a groff extension and currently ignored. +.Ss \&hc +Set the hyphenation character. +Currently ignored. +.Ss \&hcode +Set hyphenation codes of characters. +Currently ignored. +.Ss \&hidechar +Hide characters in a font. +This is a Heirloom extension and currently ignored. +.Ss \&hla +Set hyphenation language. +This is a groff extension and currently ignored. +.Ss \&hlm +Set maximum number of consecutive hyphenated lines. +Currently ignored. +.Ss \&hpf +Load hyphenation pattern file. +This is a groff extension and currently ignored. +.Ss \&hpfa +Load hyphenation pattern file, appending to the current patterns. +This is a groff extension and currently ignored. +.Ss \&hpfcode +Define mapping values for character codes in hyphenation patterns. +This is a groff extension and currently ignored. .Ss \&hw Specify hyphenation points in words. -This line-scoped request is currently ignored. +Currently ignored. .Ss \&hy Set automatic hyphenation mode. -This line-scoped request is currently ignored. +Currently ignored. +.Ss \&hylang +Set hyphenation language. +This is a Heirloom extension and currently ignored. +.Ss \&hylen +Minimum word length for hyphenation. +This is a Heirloom extension and currently ignored. +.Ss \&hym +Set hyphenation margin. +This is a groff extension and currently ignored. +.Ss \&hypp +Define hyphenation penalties. +This is a Heirloom extension and currently ignored. +.Ss \&hys +Set hyphenation space. +This is a groff extension and currently ignored. .Ss \&ie The .Qq if @@ -871,6 +1183,82 @@ Otherwise, it only terminates the and arguments following it or the .Sq \&.. request are discarded. +.Ss \&in +Change indentation. +See +.Xr man 7 . +Ignored in +.Xr mdoc 7 . +.Ss \&index +Find a substring in a string. +This is a Heirloom extension and currently unsupported. +.Ss \&it +Set an input line trap. +Its syntax is as follows: +.Pp +.D1 Pf . Cm it Ar expression macro +.Pp +The named +.Ar macro +will be invoked after processing the number of input text lines +specified by the numerical +.Ar expression . +While evaluating the +.Ar expression , +the unit suffixes described below +.Sx Scaling Widths +are ignored. +.Ss \&itc +Set an input line trap, not counting lines ending with \ec. +Currently unsupported. +.Ss \&IX +To support the generation of a table of contents, +.Xr pod2man 1 +emits this user-defined macro, usually without defining it. +To avoid reporting large numbers of spurious errors, +.Xr mandoc 1 +ignores it. +.Ss \&kern +Switch kerning on or off. +Currently ignored. +.Ss \&kernafter +Increase kerning after some characters. +This is a Heirloom extension and currently ignored. +.Ss \&kernbefore +Increase kerning before some characters. +This is a Heirloom extension and currently ignored. +.Ss \&kernpair +Add a kerning pair to the kerning table. +This is a Heirloom extension and currently ignored. +.Ss \&lc +Define a leader repetition character. +Currently unsupported. +.Ss \&lc_ctype +Set the +.Dv LC_CTYPE +locale. +This is a Heirloom extension and currently unsupported. +.Ss \&lds +Define a local string. +This is a Heirloom extension and currently unsupported. +.Ss \&length +Count the number of input characters in a user-defined string. +Currently unsupported. +.Ss \&letadj +Dynamic letter spacing and reshaping. +This is a Heirloom extension and currently ignored. +.Ss \&lf +Change the line number for error messages. +Ignored because insecure. +.Ss \&lg +Switch the ligature mechanism on or off. +Currently ignored. +.Ss \&lhang +Hang characters at left margin. +This is a Heirloom extension and currently ignored. +.Ss \&linetabs +Enable or disable line-tabs mode. +This is a groff extension and currently unsupported. .Ss \&ll Change the output line length. Its syntax is as follows: @@ -888,13 +1276,69 @@ among others because it overrides the .Xr mandoc 1 .Fl O Cm width command line option. +.Ss \&lnr +Set local number register. +This is a Heirloom extension and currently unsupported. +.Ss \&lnrf +Set local floating-point register. +This is a Heirloom extension and currently unsupported. +.Ss \&lpfx +Set a line prefix. +This is a Heirloom extension and currently unsupported. +.Ss \&ls +Set line spacing. +It takes one integer argument specifying the vertical distance of +subsequent output text lines measured in v units. +Currently ignored. +.Ss \&lsm +Set a leading spaces trap. +This is a groff extension and currently unsupported. +.Ss \< +Set title line length. +Currently ignored. +.Ss \&mc +Print margin character in the right margin. +Currently ignored. +.Ss \&mediasize +Set the device media size. +This is a Heirloom extension and currently ignored. +.Ss \&minss +Set minimum word space. +This is a Heirloom extension and currently ignored. +.Ss \&mk +Mark vertical position. +Currently ignored. +.Ss \&mso +Load a macro file. +Ignored because insecure. +.Ss \&na +Disable adjusting without changing the adjustment mode. +Currently ignored. .Ss \&ne Declare the need for the specified minimum vertical space before the next trap or the bottom of the page. -This line-scoped request is currently ignored. +Currently ignored. +.Ss \&nf +Switch to no-fill mode. +See +.Xr man 7 . +Ignored by +.Xr mdoc 7 . .Ss \&nh Turn off automatic hyphenation mode. -This line-scoped request is currently ignored. +Currently ignored. +.Ss \&nhychar +Define hyphenation-inhibiting characters. +This is a Heirloom extension and currently ignored. +.Ss \&nm +Print line numbers. +Currently unsupported. +.Ss \&nn +Temporarily turn off line numbering. +Currently unsupported. +.Ss \&nop +Exexute the rest of the input line as a request or macro line. +Currently unsupported. .Ss \&nr Define or change a register. A register is an arbitrary string value that defines some sort of state, @@ -932,31 +1376,142 @@ section with the .Cm \&Sh macro will reset this register. .El +.Ss \&nrf +Define or change a floating-point register. +This is a Heirloom extension and currently unsupported. +.Ss \&nroff +Force nroff mode. +This is a groff extension and currently ignored. .Ss \&ns Turn on no-space mode. -This line-scoped request is intended to take no arguments. -Currently, it is ignored including its arguments, -and the number of arguments is not checked. +Currently ignored. +.Ss \&nx +Abort processing of the current input file and process another one. +Ignored because insecure. +.Ss \&open +Open a file for writing. +Ignored because insecure. +.Ss \&opena +Open a file for appending. +Ignored because insecure. +.Ss \&os +Output saved vertical space. +Currently ignored. +.Ss \&output +Output directly to intermediate output. +Not supported. +.Ss \&padj +Globally control paragraph-at-once adjustment. +This is a Heirloom extension and currently ignored. +.Ss \&papersize +Set the paper size. +This is a Heirloom extension and currently ignored. +.Ss \&pc +Change the page number character. +Currently ignored. +.Ss \&pev +Print environments. +This is a groff extension and currently ignored. +.Ss \&pi +Pipe output to a shell command. +Ignored because insecure. +.Ss \&PI +Low-level request used by +.Sx \&BP . +This is a Heirloom extension and currently unsupported. .Ss \&pl Change page length. -This line-scoped request is intended to take one height argument. -Currently, it is ignored including its arguments, -and the number of arguments is not checked. +Takes one height argument. +Currently ignored. +.Ss \&pm +Print names and sizes of macros, strings, and diversions. +Currently ignored. +.Ss \&pn +Change page number of the next page. +Currently ignored. +.Ss \&pnr +Print all number registers. +Currently ignored. +.Ss \&po +Set horizontal page offset. +Currently ignored. .Ss \&ps Change point size. -This line-scoped request is intended to take one numerical argument. -Currently, it is ignored including its arguments, -and the number of arguments is not checked. +Takes one numerical argument. +Currently ignored. +.Ss \&psbb +Retrieve the bounding box of a PostScript file. +Currently unsupported. +.Ss \&pshape +Set a special shape for the current paragraph. +This is a Heirloom extension and currently unsupported. +.Ss \&pso +Include output of a shell command. +Ignored because insecure. +.Ss \&ptr +Print the names and positions of all traps. +This is a groff extension and currently ignored. +.Ss \&pvs +Change post-vertical spacing. +This is a groff extension and currently ignored. +.Ss \&rchar +Remove glyph definitions. +Currently unsupported. +.Ss \&rd +Read from standard input. +Currently ignored. +.Ss \&recursionlimit +Set the maximum stack depth for recursive macros. +This is a Heirloom extension and currently ignored. +.Ss \&return +Exit a macro and return to the caller. +Currently unsupported. +.Ss \&rfschar +Remove font-specific fallback glyph definitions. +Currently unsupported. +.Ss \&rhang +Hang characters at right margin. +This is a Heirloom extension and currently ignored. +.Ss \&rj +Justify unfilled text to the right margin. +Currently ignored. .Ss \&rm Remove a request, macro or string. Its syntax is as follows: .Pp .D1 Pf \. Cm \&rm Ar name +.Ss \&rn +Rename a request, macro, diversion, or string. +Currently unsupported. +.Ss \&rnn +Rename a number register. +Currently unsupported. .Ss \&rr Remove a register. Its syntax is as follows: .Pp .D1 Pf \. Cm \&rr Ar name +.Ss \&rs +End no-space mode. +Currently ignored. +.Ss \&rt +Return to marked vertical position. +Currently ignored. +.Ss \&schar +Define global fallback glyph. +This is a groff extension and currently unsupported. +.Ss \&sentchar +Define sentence-ending characters. +This is a Heirloom extension and currently ignored. +.Ss \&shc +Change the soft hyphen character. +Currently ignored. +.Ss \&shift +Shift macro arguments. +Currently unsupported. +.Ss \&sizes +Define permissible point sizes. +This is a groff extension and currently ignored. .Ss \&so Include a source file. Its syntax is as follows: @@ -990,10 +1545,64 @@ is discouraged. Use .Xr ln 1 instead. +.Ss \&spacewidth +Set the space width from the font metrics file. +This is a Heirloom extension and currently ignored. +.Ss \&special +Define a special font. +This is a groff extension and currently ignored. +.Ss \&spreadwarn +Warn about wide spacing between words. +Currently ignored. +.Ss \&ss +Set space character size. +Currently ignored. +.Ss \&sty +Associate style with a font position. +This is a groff extension and currently ignored. +.Ss \&substring +Replace a user-defined string with a substring. +Currently unsupported. +.Ss \&sv +Save vertical space. +Currently ignored. +.Ss \&sy +Execute shell command. +Ignored because insecure. +.Ss \&T& +Re-start a table layout, retaining the options of the prior table +invocation. +See +.Sx \&TS . .Ss \&ta Set tab stops. -This line-scoped request can take an arbitrary number of arguments. -Currently, it is ignored including its arguments. +Takes an arbitrary number of arguments. +Currently unsupported. +.Ss \&tc +Change tab repetion character. +Currently unsupported. +.Ss \&TE +End a table context. +See +.Sx \&TS . +.Ss \&ti +Temporary indent. +Currently unsupported. +.Ss \&tkf +Enable track kerning for a font. +Currently ignored. +.Ss \&tl +Print a title line. +Currently unsupported. +.Ss \&tm +Print to standard error output. +Currently ignored. +.Ss \&tm1 +Print to standard error output, allowing leading blanks. +This is a groff extension and currently ignored. +.Ss \&tmc +Print to standard error output without a trailing newline. +This is a groff extension and currently ignored. .Ss \&tr Output character translation. Its syntax is as follows: @@ -1011,20 +1620,88 @@ Replacement (or origin) characters may also be character escapes; thus, .Dl tr \e(xx\e(yy .Pp replaces all invocations of \e(xx with \e(yy. -.Ss \&T& -Re-start a table layout, retaining the options of the prior table -invocation. -See -.Sx \&TS . -.Ss \&TE -End a table context. -See -.Sx \&TS . +.Ss \&track +Static letter space tracking. +This is a Heirloom extension and currently ignored. +.Ss \&transchar +Define transparent characters for sentence-ending. +This is a Heirloom extension and currently ignored. +.Ss \&trf +Output the contents of a file, disallowing invalid characters. +This is a groff extension and ignored because insecure. +.Ss \&trimat +Set the TrimBox page parameter for PDF generation. +This is a Heirloom extension and currently ignored. +.Ss \&trin +Output character translation, ignored by +.Cm \&asciify . +Currently unsupported. +.Ss \&trnt +Output character translation, ignored by \e!. +Currently unsupported. +.Ss \&troff +Force troff mode. +This is a groff extension and currently ignored. .Ss \&TS Begin a table, which formats input in aligned rows and columns. See .Xr tbl 7 for a description of the tbl language. +.Ss \&uf +Globally set the underline font. +Currently ignored. +.Ss \&ul +Underline. +Currently ignored. +.Ss \&unformat +Unformat spaces and tabs in a diversion. +Currently unsupported. +.Ss \&unwatch +Disable notification for string or macro. +This is a Heirloom extension and currently ignored. +.Ss \&unwatchn +Disable notification for register. +This is a Heirloom extension and currently ignored. +.Ss \&vpt +Enable or disable vertical position traps. +This is a groff extension and currently ignored. +.Ss \&vs +Change vertical spacing. +Currently ignored. +.Ss \&warn +Set warning level. +Currently ignored. +.Ss \&warnscale +Set the scaling indicator used in warnings. +This is a groff extension and currently ignored. +.Ss \&watch +Notify on change of string or macro. +This is a Heirloom extension and currently ignored. +.Ss \&watchlength +On change, report the contents of macros and strings +up to the sepcified length. +This is a Heirloom extension and currently ignored. +.Ss \&watchn +Notify on change of register. +This is a Heirloom extension and currently ignored. +.Ss \&wh +Set a page location trap. +Currently unsupported. +.Ss \&while +Repeated execution while a condition is true. +Currently unsupported. +.Ss \&write +Write to an open file. +Ignored because insecure. +.Ss \&writec +Write to an open file without appending a newline. +Ignored because insecure. +.Ss \&writem +Write macro or string to an open file. +Ignored because insecure. +.Ss \&xflag +Set the extension level. +This is a Heirloom extension and currently ignored. .Ss Numerical expressions The .Sx \&nr , @@ -1043,6 +1720,14 @@ prefixed by an optional sign .Sq + or .Sq - . +Each number may be followed by one optional scaling unit described below +.Sx Scaling Widths . +The following equations hold: +.Bd -literal -offset indent +1i = 6v = 6P = 10m = 10n = 72p = 1000M = 240u = 240 +254c = 100i = 24000u = 24000 +1f = 65536u = 65536 +.Ed .Pp The following binary operators are implemented. Unless otherwise stated, they behave as in the C language: @@ -1276,10 +1961,11 @@ For short names, there are variants and .No \en( Ns Ar cc . .Ss \eo\(aq Ns Ar string Ns \(aq -Overstrike -.Ar string ; -ignored by -.Xr mandoc 1 . +Overstrike, writing all the characters contained in the +.Ar string +to the same output position. +In terminal and HTML output modes, +only the last one of the characters is visible. .Ss \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns \(aq Set number register; ignored by .Xr mandoc 1 . @@ -1347,50 +2033,66 @@ approximated in .Xr mandoc 1 by simply skipping the next character. .Sh COMPATIBILITY -This section documents compatibility between mandoc and other +The +.Xr mandoc 1 +implementation of the .Nm -implementations, at this time limited to GNU troff -.Pq Qq groff . -The term -.Qq historic groff -refers to groff version 1.15. +language is intentionally incomplete. +Unimplemented features include: .Pp .Bl -dash -compact .It +For security reasons, +.Xr mandoc 1 +never reads or writes external files except via +.Sx \&so +requests with safe relative paths. +.It +There is no automatic hyphenation, no adjustment to the right margin, +and no centering; the output is always set flush-left. +.It +Support for setting tabulator positions +and tabulator and leader characters is missing, +and support for manually changing indentation is limited. +.It The .Sq u scaling unit is the default terminal unit. -In traditional troff systems, this unit would change depending on the +In traditional troff systems, this unit changes depending on the output media. .It -In mandoc, the -.Sx \&EQ , -.Sx \&TE , -.Sx \&TS , -and -.Sx \&T& , -macros are considered regular macros. -In all other -.Nm -implementations, these are special macros that must be specified without -spacing between the control character (which must be a period) and the -macro name. +Width measurements are implemented in a crude way +and often yield wrong results. +Explicit movement requests and escapes are ignored. .It -The -.Cm nS -register is only compatible with OpenBSD's groff-1.15. +There is no concept of output pages, no support for floats, +graphics drawing, and picture inclusion; +terminal output is always continuous. .It -Historic groff did not accept white-space before a custom -.Ar end -macro for the -.Sx \&ig -request. +Requests regarding color, font families, and glyph manipulation +are ignored. +Font support is very limited. +Kerning is not implemented, and no ligatures are produced. .It The -.Sx \&if -and family would print funny white-spaces with historic groff when -using the next-line syntax. +.Qq \(aq +macro control character does not suppress output line breaks. +.It +Diversions are not implemented, +and support for traps is very incomplete. +.It +While recursion is supported, +.Sx \&while +loops are not. .El +.Pp +The special semantics of the +.Cm nS +number register is an idiosyncracy of +.Ox +manuals and not supported by other +.Xr mdoc 7 +implementations. .Sh SEE ALSO .Xr mandoc 1 , .Xr eqn 7 , diff --git a/contrib/mdocml/roff.c b/contrib/mdocml/roff.c index f44f01f1b033..3c920137ea70 100644 --- a/contrib/mdocml/roff.c +++ b/contrib/mdocml/roff.c @@ -1,7 +1,7 @@ -/* $Id: roff.c,v 1.239 2014/11/19 01:20:25 schwarze Exp $ */ +/* $Id: roff.c,v 1.263 2015/02/21 14:46:58 schwarze Exp $ */ /* - * Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2010-2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2010, 2011, 2012, 2014 Kristaps Dzonsons <kristaps@bsd.lv> + * Copyright (c) 2010-2015 Ingo Schwarze <schwarze@openbsd.org> * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -21,6 +21,7 @@ #include <assert.h> #include <ctype.h> +#include <limits.h> #include <stdio.h> #include <stdlib.h> #include <string.h> @@ -37,43 +38,247 @@ #define EXPAND_LIMIT 1000 enum rofft { + ROFF_ab, ROFF_ad, + ROFF_af, + ROFF_aln, + ROFF_als, ROFF_am, - ROFF_ami, ROFF_am1, + ROFF_ami, + ROFF_ami1, ROFF_as, + ROFF_as1, + ROFF_asciify, + ROFF_backtrace, + ROFF_bd, + ROFF_bleedat, + ROFF_blm, + ROFF_box, + ROFF_boxa, + ROFF_bp, + ROFF_BP, + /* MAN_br, MDOC_br */ + ROFF_break, + ROFF_breakchar, + ROFF_brnl, + ROFF_brp, + ROFF_brpnl, + ROFF_c2, ROFF_cc, ROFF_ce, + ROFF_cf, + ROFF_cflags, + ROFF_ch, + ROFF_char, + ROFF_chop, + ROFF_class, + ROFF_close, + ROFF_CL, + ROFF_color, + ROFF_composite, + ROFF_continue, + ROFF_cp, + ROFF_cropat, + ROFF_cs, + ROFF_cu, + ROFF_da, + ROFF_dch, + ROFF_Dd, ROFF_de, - ROFF_dei, ROFF_de1, + ROFF_defcolor, + ROFF_dei, + ROFF_dei1, + ROFF_device, + ROFF_devicem, + ROFF_di, + ROFF_do, ROFF_ds, + ROFF_ds1, + ROFF_dwh, + ROFF_dt, + ROFF_ec, + ROFF_ecr, + ROFF_ecs, ROFF_el, + ROFF_em, + ROFF_EN, + ROFF_eo, + ROFF_EP, + ROFF_EQ, + ROFF_errprint, + ROFF_ev, + ROFF_evc, + ROFF_ex, + ROFF_fallback, ROFF_fam, + ROFF_fc, + ROFF_fchar, + ROFF_fcolor, + ROFF_fdeferlig, + ROFF_feature, + /* MAN_fi; ignored in mdoc(7) */ + ROFF_fkern, + ROFF_fl, + ROFF_flig, + ROFF_fp, + ROFF_fps, + ROFF_fschar, + ROFF_fspacewidth, + ROFF_fspecial, + /* MAN_ft; ignored in mdoc(7) */ + ROFF_ftr, + ROFF_fzoom, + ROFF_gcolor, + ROFF_hc, + ROFF_hcode, + ROFF_hidechar, + ROFF_hla, + ROFF_hlm, + ROFF_hpf, + ROFF_hpfa, + ROFF_hpfcode, ROFF_hw, ROFF_hy, + ROFF_hylang, + ROFF_hylen, + ROFF_hym, + ROFF_hypp, + ROFF_hys, ROFF_ie, ROFF_if, ROFF_ig, + /* MAN_in; ignored in mdoc(7) */ + ROFF_index, ROFF_it, + ROFF_itc, + ROFF_IX, + ROFF_kern, + ROFF_kernafter, + ROFF_kernbefore, + ROFF_kernpair, + ROFF_lc, + ROFF_lc_ctype, + ROFF_lds, + ROFF_length, + ROFF_letadj, + ROFF_lf, + ROFF_lg, + ROFF_lhang, + ROFF_linetabs, + /* MAN_ll, MDOC_ll */ + ROFF_lnr, + ROFF_lnrf, + ROFF_lpfx, + ROFF_ls, + ROFF_lsm, + ROFF_lt, + ROFF_mc, + ROFF_mediasize, + ROFF_minss, + ROFF_mk, + ROFF_mso, + ROFF_na, ROFF_ne, + /* MAN_nf; ignored in mdoc(7) */ ROFF_nh, + ROFF_nhychar, + ROFF_nm, + ROFF_nn, + ROFF_nop, ROFF_nr, + ROFF_nrf, + ROFF_nroff, ROFF_ns, + ROFF_nx, + ROFF_open, + ROFF_opena, + ROFF_os, + ROFF_output, + ROFF_padj, + ROFF_papersize, + ROFF_pc, + ROFF_pev, + ROFF_pi, + ROFF_PI, ROFF_pl, + ROFF_pm, + ROFF_pn, + ROFF_pnr, + ROFF_po, ROFF_ps, + ROFF_psbb, + ROFF_pshape, + ROFF_pso, + ROFF_ptr, + ROFF_pvs, + ROFF_rchar, + ROFF_rd, + ROFF_recursionlimit, + ROFF_return, + ROFF_rfschar, + ROFF_rhang, + ROFF_rj, ROFF_rm, + ROFF_rn, + ROFF_rnn, ROFF_rr, + ROFF_rs, + ROFF_rt, + ROFF_schar, + ROFF_sentchar, + ROFF_shc, + ROFF_shift, + ROFF_sizes, ROFF_so, + /* MAN_sp, MDOC_sp */ + ROFF_spacewidth, + ROFF_special, + ROFF_spreadwarn, + ROFF_ss, + ROFF_sty, + ROFF_substring, + ROFF_sv, + ROFF_sy, + ROFF_T_, ROFF_ta, - ROFF_tr, - ROFF_Dd, + ROFF_tc, + ROFF_TE, ROFF_TH, + ROFF_ti, + ROFF_tkf, + ROFF_tl, + ROFF_tm, + ROFF_tm1, + ROFF_tmc, + ROFF_tr, + ROFF_track, + ROFF_transchar, + ROFF_trf, + ROFF_trimat, + ROFF_trin, + ROFF_trnt, + ROFF_troff, ROFF_TS, - ROFF_TE, - ROFF_T_, - ROFF_EQ, - ROFF_EN, + ROFF_uf, + ROFF_ul, + ROFF_unformat, + ROFF_unwatch, + ROFF_unwatchn, + ROFF_vpt, + ROFF_vs, + ROFF_warn, + ROFF_warnscale, + ROFF_watch, + ROFF_watchlength, + ROFF_watchn, + ROFF_wh, + ROFF_while, + ROFF_write, + ROFF_writec, + ROFF_writem, + ROFF_xflag, ROFF_cblock, ROFF_USERDEF, ROFF_MAX @@ -177,6 +382,7 @@ static void roffnode_push(struct roff *, enum rofft, static enum rofferr roff_block(ROFF_ARGS); static enum rofferr roff_block_text(ROFF_ARGS); static enum rofferr roff_block_sub(ROFF_ARGS); +static enum rofferr roff_brp(ROFF_ARGS); static enum rofferr roff_cblock(ROFF_ARGS); static enum rofferr roff_cc(ROFF_ARGS); static void roff_ccond(struct roff *, int, int); @@ -190,19 +396,20 @@ static int roff_evalcond(struct roff *r, int, static int roff_evalnum(struct roff *, int, const char *, int *, int *, int); static int roff_evalpar(struct roff *, int, - const char *, int *, int *); + const char *, int *, int *, int); static int roff_evalstrcond(const char *, int *); static void roff_free1(struct roff *); static void roff_freereg(struct roffreg *); static void roff_freestr(struct roffkv *); static size_t roff_getname(struct roff *, char **, int, int); -static int roff_getnum(const char *, int *, int *); +static int roff_getnum(const char *, int *, int *, int); static int roff_getop(const char *, int *, char *); static int roff_getregn(const struct roff *, const char *, size_t); static int roff_getregro(const char *name); static const char *roff_getstrn(const struct roff *, const char *, size_t); +static enum rofferr roff_insec(ROFF_ARGS); static enum rofferr roff_it(ROFF_ARGS); static enum rofferr roff_line_ignore(ROFF_ARGS); static enum rofferr roff_nr(ROFF_ARGS); @@ -225,6 +432,7 @@ static enum rofferr roff_TS(ROFF_ARGS); static enum rofferr roff_EQ(ROFF_ARGS); static enum rofferr roff_EN(ROFF_ARGS); static enum rofferr roff_T_(ROFF_ARGS); +static enum rofferr roff_unsupp(ROFF_ARGS); static enum rofferr roff_userdef(ROFF_ARGS); /* See roffhash_find() */ @@ -233,46 +441,246 @@ static enum rofferr roff_userdef(ROFF_ARGS); #define ASCII_LO 33 #define HASHWIDTH (ASCII_HI - ASCII_LO + 1) +#define ROFFNUM_SCALE (1 << 0) /* Honour scaling in roff_getnum(). */ +#define ROFFNUM_WHITE (1 << 1) /* Skip whitespace in roff_evalnum(). */ + static struct roffmac *hash[HASHWIDTH]; static struct roffmac roffs[ROFF_MAX] = { + { "ab", roff_unsupp, NULL, NULL, 0, NULL }, { "ad", roff_line_ignore, NULL, NULL, 0, NULL }, + { "af", roff_line_ignore, NULL, NULL, 0, NULL }, + { "aln", roff_unsupp, NULL, NULL, 0, NULL }, + { "als", roff_unsupp, NULL, NULL, 0, NULL }, { "am", roff_block, roff_block_text, roff_block_sub, 0, NULL }, - { "ami", roff_block, roff_block_text, roff_block_sub, 0, NULL }, { "am1", roff_block, roff_block_text, roff_block_sub, 0, NULL }, + { "ami", roff_block, roff_block_text, roff_block_sub, 0, NULL }, + { "ami1", roff_block, roff_block_text, roff_block_sub, 0, NULL }, { "as", roff_ds, NULL, NULL, 0, NULL }, + { "as1", roff_ds, NULL, NULL, 0, NULL }, + { "asciify", roff_unsupp, NULL, NULL, 0, NULL }, + { "backtrace", roff_line_ignore, NULL, NULL, 0, NULL }, + { "bd", roff_line_ignore, NULL, NULL, 0, NULL }, + { "bleedat", roff_line_ignore, NULL, NULL, 0, NULL }, + { "blm", roff_unsupp, NULL, NULL, 0, NULL }, + { "box", roff_unsupp, NULL, NULL, 0, NULL }, + { "boxa", roff_unsupp, NULL, NULL, 0, NULL }, + { "bp", roff_line_ignore, NULL, NULL, 0, NULL }, + { "BP", roff_unsupp, NULL, NULL, 0, NULL }, + { "break", roff_unsupp, NULL, NULL, 0, NULL }, + { "breakchar", roff_line_ignore, NULL, NULL, 0, NULL }, + { "brnl", roff_line_ignore, NULL, NULL, 0, NULL }, + { "brp", roff_brp, NULL, NULL, 0, NULL }, + { "brpnl", roff_line_ignore, NULL, NULL, 0, NULL }, + { "c2", roff_unsupp, NULL, NULL, 0, NULL }, { "cc", roff_cc, NULL, NULL, 0, NULL }, { "ce", roff_line_ignore, NULL, NULL, 0, NULL }, + { "cf", roff_insec, NULL, NULL, 0, NULL }, + { "cflags", roff_line_ignore, NULL, NULL, 0, NULL }, + { "ch", roff_line_ignore, NULL, NULL, 0, NULL }, + { "char", roff_unsupp, NULL, NULL, 0, NULL }, + { "chop", roff_unsupp, NULL, NULL, 0, NULL }, + { "class", roff_line_ignore, NULL, NULL, 0, NULL }, + { "close", roff_insec, NULL, NULL, 0, NULL }, + { "CL", roff_unsupp, NULL, NULL, 0, NULL }, + { "color", roff_line_ignore, NULL, NULL, 0, NULL }, + { "composite", roff_unsupp, NULL, NULL, 0, NULL }, + { "continue", roff_unsupp, NULL, NULL, 0, NULL }, + { "cp", roff_line_ignore, NULL, NULL, 0, NULL }, + { "cropat", roff_line_ignore, NULL, NULL, 0, NULL }, + { "cs", roff_line_ignore, NULL, NULL, 0, NULL }, + { "cu", roff_line_ignore, NULL, NULL, 0, NULL }, + { "da", roff_unsupp, NULL, NULL, 0, NULL }, + { "dch", roff_unsupp, NULL, NULL, 0, NULL }, + { "Dd", roff_Dd, NULL, NULL, 0, NULL }, { "de", roff_block, roff_block_text, roff_block_sub, 0, NULL }, - { "dei", roff_block, roff_block_text, roff_block_sub, 0, NULL }, { "de1", roff_block, roff_block_text, roff_block_sub, 0, NULL }, + { "defcolor", roff_line_ignore, NULL, NULL, 0, NULL }, + { "dei", roff_block, roff_block_text, roff_block_sub, 0, NULL }, + { "dei1", roff_block, roff_block_text, roff_block_sub, 0, NULL }, + { "device", roff_unsupp, NULL, NULL, 0, NULL }, + { "devicem", roff_unsupp, NULL, NULL, 0, NULL }, + { "di", roff_unsupp, NULL, NULL, 0, NULL }, + { "do", roff_unsupp, NULL, NULL, 0, NULL }, { "ds", roff_ds, NULL, NULL, 0, NULL }, + { "ds1", roff_ds, NULL, NULL, 0, NULL }, + { "dwh", roff_unsupp, NULL, NULL, 0, NULL }, + { "dt", roff_unsupp, NULL, NULL, 0, NULL }, + { "ec", roff_unsupp, NULL, NULL, 0, NULL }, + { "ecr", roff_unsupp, NULL, NULL, 0, NULL }, + { "ecs", roff_unsupp, NULL, NULL, 0, NULL }, { "el", roff_cond, roff_cond_text, roff_cond_sub, ROFFMAC_STRUCT, NULL }, + { "em", roff_unsupp, NULL, NULL, 0, NULL }, + { "EN", roff_EN, NULL, NULL, 0, NULL }, + { "eo", roff_unsupp, NULL, NULL, 0, NULL }, + { "EP", roff_unsupp, NULL, NULL, 0, NULL }, + { "EQ", roff_EQ, NULL, NULL, 0, NULL }, + { "errprint", roff_line_ignore, NULL, NULL, 0, NULL }, + { "ev", roff_unsupp, NULL, NULL, 0, NULL }, + { "evc", roff_unsupp, NULL, NULL, 0, NULL }, + { "ex", roff_unsupp, NULL, NULL, 0, NULL }, + { "fallback", roff_line_ignore, NULL, NULL, 0, NULL }, { "fam", roff_line_ignore, NULL, NULL, 0, NULL }, + { "fc", roff_unsupp, NULL, NULL, 0, NULL }, + { "fchar", roff_unsupp, NULL, NULL, 0, NULL }, + { "fcolor", roff_line_ignore, NULL, NULL, 0, NULL }, + { "fdeferlig", roff_line_ignore, NULL, NULL, 0, NULL }, + { "feature", roff_line_ignore, NULL, NULL, 0, NULL }, + { "fkern", roff_line_ignore, NULL, NULL, 0, NULL }, + { "fl", roff_line_ignore, NULL, NULL, 0, NULL }, + { "flig", roff_line_ignore, NULL, NULL, 0, NULL }, + { "fp", roff_line_ignore, NULL, NULL, 0, NULL }, + { "fps", roff_line_ignore, NULL, NULL, 0, NULL }, + { "fschar", roff_unsupp, NULL, NULL, 0, NULL }, + { "fspacewidth", roff_line_ignore, NULL, NULL, 0, NULL }, + { "fspecial", roff_line_ignore, NULL, NULL, 0, NULL }, + { "ftr", roff_line_ignore, NULL, NULL, 0, NULL }, + { "fzoom", roff_line_ignore, NULL, NULL, 0, NULL }, + { "gcolor", roff_line_ignore, NULL, NULL, 0, NULL }, + { "hc", roff_line_ignore, NULL, NULL, 0, NULL }, + { "hcode", roff_line_ignore, NULL, NULL, 0, NULL }, + { "hidechar", roff_line_ignore, NULL, NULL, 0, NULL }, + { "hla", roff_line_ignore, NULL, NULL, 0, NULL }, + { "hlm", roff_line_ignore, NULL, NULL, 0, NULL }, + { "hpf", roff_line_ignore, NULL, NULL, 0, NULL }, + { "hpfa", roff_line_ignore, NULL, NULL, 0, NULL }, + { "hpfcode", roff_line_ignore, NULL, NULL, 0, NULL }, { "hw", roff_line_ignore, NULL, NULL, 0, NULL }, { "hy", roff_line_ignore, NULL, NULL, 0, NULL }, + { "hylang", roff_line_ignore, NULL, NULL, 0, NULL }, + { "hylen", roff_line_ignore, NULL, NULL, 0, NULL }, + { "hym", roff_line_ignore, NULL, NULL, 0, NULL }, + { "hypp", roff_line_ignore, NULL, NULL, 0, NULL }, + { "hys", roff_line_ignore, NULL, NULL, 0, NULL }, { "ie", roff_cond, roff_cond_text, roff_cond_sub, ROFFMAC_STRUCT, NULL }, { "if", roff_cond, roff_cond_text, roff_cond_sub, ROFFMAC_STRUCT, NULL }, { "ig", roff_block, roff_block_text, roff_block_sub, 0, NULL }, + { "index", roff_unsupp, NULL, NULL, 0, NULL }, { "it", roff_it, NULL, NULL, 0, NULL }, + { "itc", roff_unsupp, NULL, NULL, 0, NULL }, + { "IX", roff_line_ignore, NULL, NULL, 0, NULL }, + { "kern", roff_line_ignore, NULL, NULL, 0, NULL }, + { "kernafter", roff_line_ignore, NULL, NULL, 0, NULL }, + { "kernbefore", roff_line_ignore, NULL, NULL, 0, NULL }, + { "kernpair", roff_line_ignore, NULL, NULL, 0, NULL }, + { "lc", roff_unsupp, NULL, NULL, 0, NULL }, + { "lc_ctype", roff_unsupp, NULL, NULL, 0, NULL }, + { "lds", roff_unsupp, NULL, NULL, 0, NULL }, + { "length", roff_unsupp, NULL, NULL, 0, NULL }, + { "letadj", roff_line_ignore, NULL, NULL, 0, NULL }, + { "lf", roff_insec, NULL, NULL, 0, NULL }, + { "lg", roff_line_ignore, NULL, NULL, 0, NULL }, + { "lhang", roff_line_ignore, NULL, NULL, 0, NULL }, + { "linetabs", roff_unsupp, NULL, NULL, 0, NULL }, + { "lnr", roff_unsupp, NULL, NULL, 0, NULL }, + { "lnrf", roff_unsupp, NULL, NULL, 0, NULL }, + { "lpfx", roff_unsupp, NULL, NULL, 0, NULL }, + { "ls", roff_line_ignore, NULL, NULL, 0, NULL }, + { "lsm", roff_unsupp, NULL, NULL, 0, NULL }, + { "lt", roff_line_ignore, NULL, NULL, 0, NULL }, + { "mc", roff_line_ignore, NULL, NULL, 0, NULL }, + { "mediasize", roff_line_ignore, NULL, NULL, 0, NULL }, + { "minss", roff_line_ignore, NULL, NULL, 0, NULL }, + { "mk", roff_line_ignore, NULL, NULL, 0, NULL }, + { "mso", roff_insec, NULL, NULL, 0, NULL }, + { "na", roff_line_ignore, NULL, NULL, 0, NULL }, { "ne", roff_line_ignore, NULL, NULL, 0, NULL }, { "nh", roff_line_ignore, NULL, NULL, 0, NULL }, + { "nhychar", roff_line_ignore, NULL, NULL, 0, NULL }, + { "nm", roff_unsupp, NULL, NULL, 0, NULL }, + { "nn", roff_unsupp, NULL, NULL, 0, NULL }, + { "nop", roff_unsupp, NULL, NULL, 0, NULL }, { "nr", roff_nr, NULL, NULL, 0, NULL }, + { "nrf", roff_unsupp, NULL, NULL, 0, NULL }, + { "nroff", roff_line_ignore, NULL, NULL, 0, NULL }, { "ns", roff_line_ignore, NULL, NULL, 0, NULL }, + { "nx", roff_insec, NULL, NULL, 0, NULL }, + { "open", roff_insec, NULL, NULL, 0, NULL }, + { "opena", roff_insec, NULL, NULL, 0, NULL }, + { "os", roff_line_ignore, NULL, NULL, 0, NULL }, + { "output", roff_unsupp, NULL, NULL, 0, NULL }, + { "padj", roff_line_ignore, NULL, NULL, 0, NULL }, + { "papersize", roff_line_ignore, NULL, NULL, 0, NULL }, + { "pc", roff_line_ignore, NULL, NULL, 0, NULL }, + { "pev", roff_line_ignore, NULL, NULL, 0, NULL }, + { "pi", roff_insec, NULL, NULL, 0, NULL }, + { "PI", roff_unsupp, NULL, NULL, 0, NULL }, { "pl", roff_line_ignore, NULL, NULL, 0, NULL }, + { "pm", roff_line_ignore, NULL, NULL, 0, NULL }, + { "pn", roff_line_ignore, NULL, NULL, 0, NULL }, + { "pnr", roff_line_ignore, NULL, NULL, 0, NULL }, + { "po", roff_line_ignore, NULL, NULL, 0, NULL }, { "ps", roff_line_ignore, NULL, NULL, 0, NULL }, + { "psbb", roff_unsupp, NULL, NULL, 0, NULL }, + { "pshape", roff_unsupp, NULL, NULL, 0, NULL }, + { "pso", roff_insec, NULL, NULL, 0, NULL }, + { "ptr", roff_line_ignore, NULL, NULL, 0, NULL }, + { "pvs", roff_line_ignore, NULL, NULL, 0, NULL }, + { "rchar", roff_unsupp, NULL, NULL, 0, NULL }, + { "rd", roff_line_ignore, NULL, NULL, 0, NULL }, + { "recursionlimit", roff_line_ignore, NULL, NULL, 0, NULL }, + { "return", roff_unsupp, NULL, NULL, 0, NULL }, + { "rfschar", roff_unsupp, NULL, NULL, 0, NULL }, + { "rhang", roff_line_ignore, NULL, NULL, 0, NULL }, + { "rj", roff_line_ignore, NULL, NULL, 0, NULL }, { "rm", roff_rm, NULL, NULL, 0, NULL }, + { "rn", roff_unsupp, NULL, NULL, 0, NULL }, + { "rnn", roff_unsupp, NULL, NULL, 0, NULL }, { "rr", roff_rr, NULL, NULL, 0, NULL }, + { "rs", roff_line_ignore, NULL, NULL, 0, NULL }, + { "rt", roff_line_ignore, NULL, NULL, 0, NULL }, + { "schar", roff_unsupp, NULL, NULL, 0, NULL }, + { "sentchar", roff_line_ignore, NULL, NULL, 0, NULL }, + { "shc", roff_line_ignore, NULL, NULL, 0, NULL }, + { "shift", roff_unsupp, NULL, NULL, 0, NULL }, + { "sizes", roff_line_ignore, NULL, NULL, 0, NULL }, { "so", roff_so, NULL, NULL, 0, NULL }, - { "ta", roff_line_ignore, NULL, NULL, 0, NULL }, - { "tr", roff_tr, NULL, NULL, 0, NULL }, - { "Dd", roff_Dd, NULL, NULL, 0, NULL }, + { "spacewidth", roff_line_ignore, NULL, NULL, 0, NULL }, + { "special", roff_line_ignore, NULL, NULL, 0, NULL }, + { "spreadwarn", roff_line_ignore, NULL, NULL, 0, NULL }, + { "ss", roff_line_ignore, NULL, NULL, 0, NULL }, + { "sty", roff_line_ignore, NULL, NULL, 0, NULL }, + { "substring", roff_unsupp, NULL, NULL, 0, NULL }, + { "sv", roff_line_ignore, NULL, NULL, 0, NULL }, + { "sy", roff_insec, NULL, NULL, 0, NULL }, + { "T&", roff_T_, NULL, NULL, 0, NULL }, + { "ta", roff_unsupp, NULL, NULL, 0, NULL }, + { "tc", roff_unsupp, NULL, NULL, 0, NULL }, + { "TE", roff_TE, NULL, NULL, 0, NULL }, { "TH", roff_TH, NULL, NULL, 0, NULL }, + { "ti", roff_unsupp, NULL, NULL, 0, NULL }, + { "tkf", roff_line_ignore, NULL, NULL, 0, NULL }, + { "tl", roff_unsupp, NULL, NULL, 0, NULL }, + { "tm", roff_line_ignore, NULL, NULL, 0, NULL }, + { "tm1", roff_line_ignore, NULL, NULL, 0, NULL }, + { "tmc", roff_line_ignore, NULL, NULL, 0, NULL }, + { "tr", roff_tr, NULL, NULL, 0, NULL }, + { "track", roff_line_ignore, NULL, NULL, 0, NULL }, + { "transchar", roff_line_ignore, NULL, NULL, 0, NULL }, + { "trf", roff_insec, NULL, NULL, 0, NULL }, + { "trimat", roff_line_ignore, NULL, NULL, 0, NULL }, + { "trin", roff_unsupp, NULL, NULL, 0, NULL }, + { "trnt", roff_unsupp, NULL, NULL, 0, NULL }, + { "troff", roff_line_ignore, NULL, NULL, 0, NULL }, { "TS", roff_TS, NULL, NULL, 0, NULL }, - { "TE", roff_TE, NULL, NULL, 0, NULL }, - { "T&", roff_T_, NULL, NULL, 0, NULL }, - { "EQ", roff_EQ, NULL, NULL, 0, NULL }, - { "EN", roff_EN, NULL, NULL, 0, NULL }, + { "uf", roff_line_ignore, NULL, NULL, 0, NULL }, + { "ul", roff_line_ignore, NULL, NULL, 0, NULL }, + { "unformat", roff_unsupp, NULL, NULL, 0, NULL }, + { "unwatch", roff_line_ignore, NULL, NULL, 0, NULL }, + { "unwatchn", roff_line_ignore, NULL, NULL, 0, NULL }, + { "vpt", roff_line_ignore, NULL, NULL, 0, NULL }, + { "vs", roff_line_ignore, NULL, NULL, 0, NULL }, + { "warn", roff_line_ignore, NULL, NULL, 0, NULL }, + { "warnscale", roff_line_ignore, NULL, NULL, 0, NULL }, + { "watch", roff_line_ignore, NULL, NULL, 0, NULL }, + { "watchlength", roff_line_ignore, NULL, NULL, 0, NULL }, + { "watchn", roff_line_ignore, NULL, NULL, 0, NULL }, + { "wh", roff_unsupp, NULL, NULL, 0, NULL }, + { "while", roff_unsupp, NULL, NULL, 0, NULL }, + { "write", roff_insec, NULL, NULL, 0, NULL }, + { "writec", roff_insec, NULL, NULL, 0, NULL }, + { "writem", roff_insec, NULL, NULL, 0, NULL }, + { "xflag", roff_line_ignore, NULL, NULL, 0, NULL }, { ".", roff_cblock, NULL, NULL, 0, NULL }, { NULL, roff_userdef, NULL, NULL, 0, NULL }, }; @@ -600,8 +1008,9 @@ roff_res(struct roff *r, struct buf *buf, int ln, int pos) /* Advance to the end of the name. */ + naml = 0; arg_complete = 1; - for (naml = 0; maxl == 0 || naml < maxl; naml++, cp++) { + while (maxl == 0 || naml < maxl) { if (*cp == '\0') { mandoc_msg(MANDOCERR_ESC_BAD, r->parse, ln, (int)(stesc - buf->buf), stesc); @@ -612,6 +1021,23 @@ roff_res(struct roff *r, struct buf *buf, int ln, int pos) cp++; break; } + if (*cp++ != '\\' || stesc[1] != 'w') { + naml++; + continue; + } + switch (mandoc_escape(&cp, NULL, NULL)) { + case ESCAPE_SPECIAL: + /* FALLTHROUGH */ + case ESCAPE_UNICODE: + /* FALLTHROUGH */ + case ESCAPE_NUMBERED: + /* FALLTHROUGH */ + case ESCAPE_OVERSTRIKE: + naml++; + break; + default: + break; + } } /* @@ -627,7 +1053,8 @@ roff_res(struct roff *r, struct buf *buf, int ln, int pos) case 'B': npos = 0; ubuf[0] = arg_complete && - roff_evalnum(r, ln, stnam, &npos, NULL, 0) && + roff_evalnum(r, ln, stnam, &npos, + NULL, ROFFNUM_SCALE) && stnam + npos + 1 == cp ? '1' : '0'; ubuf[1] = '\0'; break; @@ -650,6 +1077,10 @@ roff_res(struct roff *r, struct buf *buf, int ln, int pos) r->parse, ln, (int)(stesc - buf->buf), "%.*s", (int)naml, stnam); res = ""; + } else if (buf->sz + strlen(res) > SHRT_MAX) { + mandoc_msg(MANDOCERR_ROFFLOOP, r->parse, + ln, (int)(stesc - buf->buf), NULL); + return(ROFF_IGN); } /* Replace the escape sequence by the string. */ @@ -730,6 +1161,7 @@ roff_parseln(struct roff *r, int ln, struct buf *buf, int *offs) enum rofft t; enum rofferr e; int pos; /* parse point */ + int spos; /* saved parse point for messages */ int ppos; /* original offset in buf->buf */ int ctl; /* macro line (boolean) */ @@ -757,13 +1189,13 @@ roff_parseln(struct roff *r, int ln, struct buf *buf, int *offs) /* * First, if a scope is open and we're not a macro, pass the - * text through the macro's filter. If a scope isn't open and - * we're not a macro, just let it through. - * Finally, if there's an equation scope open, divert it into it - * no matter our state. + * text through the macro's filter. + * Equations process all content themselves. + * Tables process almost all content themselves, but we want + * to warn about macros before passing it there. */ - if (r->last && ! ctl) { + if (r->last != NULL && ! ctl) { t = r->last->tok; assert(roffs[t].text); e = (*roffs[t].text)(r, t, buf, ln, pos, pos, offs); @@ -771,13 +1203,12 @@ roff_parseln(struct roff *r, int ln, struct buf *buf, int *offs) if (e != ROFF_CONT) return(e); } - if (r->eqn) + if (r->eqn != NULL) return(eqn_read(&r->eqn, ln, buf->buf, ppos, offs)); - if ( ! ctl) { - if (r->tbl) - return(tbl_read(r->tbl, ln, buf->buf, pos)); + if (r->tbl != NULL && ( ! ctl || buf->buf[pos] == '\0')) + return(tbl_read(r->tbl, ln, buf->buf, ppos)); + if ( ! ctl) return(roff_parsetext(buf, pos, offs)); - } /* Skip empty request lines. */ @@ -800,15 +1231,35 @@ roff_parseln(struct roff *r, int ln, struct buf *buf, int *offs) return((*roffs[t].sub)(r, t, buf, ln, ppos, pos, offs)); } + /* No scope is open. This is a new request or macro. */ + + spos = pos; + t = roff_parse(r, buf->buf, &pos, ln, ppos); + + /* Tables ignore most macros. */ + + if (r->tbl != NULL && (t == ROFF_MAX || t == ROFF_TS)) { + mandoc_msg(MANDOCERR_TBLMACRO, r->parse, + ln, pos, buf->buf + spos); + if (t == ROFF_TS) + return(ROFF_IGN); + while (buf->buf[pos] != '\0' && buf->buf[pos] != ' ') + pos++; + while (buf->buf[pos] != '\0' && buf->buf[pos] == ' ') + pos++; + return(tbl_read(r->tbl, ln, buf->buf, pos)); + } + /* - * Lastly, as we've no scope open, try to look up and execute - * the new macro. If no macro is found, simply return and let - * the compilers handle it. + * This is neither a roff request nor a user-defined macro. + * Let the standard macro set parsers handle it. */ - if ((t = roff_parse(r, buf->buf, &pos, ln, ppos)) == ROFF_MAX) + if (t == ROFF_MAX) return(ROFF_CONT); + /* Execute a roff request or a user defined macro. */ + assert(roffs[t].proc); return((*roffs[t].proc)(r, t, buf, ln, ppos, pos, offs)); } @@ -964,8 +1415,12 @@ roff_block(ROFF_ARGS) if (tok == ROFF_de1) tok = ROFF_de; + else if (tok == ROFF_dei1) + tok = ROFF_dei; else if (tok == ROFF_am1) tok = ROFF_am; + else if (tok == ROFF_ami1) + tok = ROFF_ami; /* Parse the macro name argument. */ @@ -1143,7 +1598,8 @@ roff_cond_sub(ROFF_ARGS) *ep = '&'; roff_ccond(r, ln, ep - buf->buf - 1); } - ++ep; + if (*ep != '\0') + ++ep; } return(rr ? ROFF_CONT : ROFF_IGN); } @@ -1163,7 +1619,8 @@ roff_cond_text(ROFF_ARGS) *ep = '&'; roff_ccond(r, ln, ep - buf->buf - 1); } - ++ep; + if (*ep != '\0') + ++ep; } return(rr ? ROFF_CONT : ROFF_IGN); } @@ -1175,18 +1632,22 @@ roff_cond_text(ROFF_ARGS) * Ignore overflows, treat them just like the C language. */ static int -roff_getnum(const char *v, int *pos, int *res) +roff_getnum(const char *v, int *pos, int *res, int flags) { - int myres, n, p; + int myres, scaled, n, p; if (NULL == res) res = &myres; p = *pos; n = v[p] == '-'; - if (n) + if (n || v[p] == '+') p++; + if (flags & ROFFNUM_WHITE) + while (isspace((unsigned char)v[p])) + p++; + for (*res = 0; isdigit((unsigned char)v[p]); p++) *res = 10 * *res + v[p] - '0'; if (p == *pos + n) @@ -1195,8 +1656,47 @@ roff_getnum(const char *v, int *pos, int *res) if (n) *res = -*res; - *pos = p; - return 1; + /* Each number may be followed by one optional scaling unit. */ + + switch (v[p]) { + case 'f': + scaled = *res * 65536; + break; + case 'i': + scaled = *res * 240; + break; + case 'c': + scaled = *res * 240 / 2.54; + break; + case 'v': + /* FALLTROUGH */ + case 'P': + scaled = *res * 40; + break; + case 'm': + /* FALLTROUGH */ + case 'n': + scaled = *res * 24; + break; + case 'p': + scaled = *res * 10 / 3; + break; + case 'u': + scaled = *res; + break; + case 'M': + scaled = *res * 6 / 25; + break; + default: + scaled = *res; + p--; + break; + } + if (flags & ROFFNUM_SCALE) + *res = scaled; + + *pos = p + 1; + return(1); } /* @@ -1236,7 +1736,7 @@ roff_evalstrcond(const char *v, int *pos) out: if (NULL == s3) s3 = strchr(s2, '\0'); - else + else if (*s3 != '\0') s3++; *pos = s3 - v; return(match); @@ -1249,7 +1749,7 @@ out: static int roff_evalcond(struct roff *r, int ln, const char *v, int *pos) { - int wanttrue, number; + int number, savepos, wanttrue; if ('!' == v[*pos]) { wanttrue = 0; @@ -1258,6 +1758,8 @@ roff_evalcond(struct roff *r, int ln, const char *v, int *pos) wanttrue = 1; switch (v[*pos]) { + case '\0': + return(0); case 'n': /* FALLTHROUGH */ case 'o': @@ -1280,10 +1782,13 @@ roff_evalcond(struct roff *r, int ln, const char *v, int *pos) break; } - if (roff_evalnum(r, ln, v, pos, &number, 0)) + savepos = *pos; + if (roff_evalnum(r, ln, v, pos, &number, ROFFNUM_SCALE)) return((number > 0) == wanttrue); - else + else if (*pos == savepos) return(roff_evalstrcond(v, pos) == wanttrue); + else + return (0); } static enum rofferr @@ -1294,6 +1799,24 @@ roff_line_ignore(ROFF_ARGS) } static enum rofferr +roff_insec(ROFF_ARGS) +{ + + mandoc_msg(MANDOCERR_REQ_INSEC, r->parse, + ln, ppos, roffs[tok].name); + return(ROFF_IGN); +} + +static enum rofferr +roff_unsupp(ROFF_ARGS) +{ + + mandoc_msg(MANDOCERR_REQ_UNSUPP, r->parse, + ln, ppos, roffs[tok].name); + return(ROFF_IGN); +} + +static enum rofferr roff_cond(ROFF_ARGS) { @@ -1376,6 +1899,13 @@ roff_ds(ROFF_ARGS) const char *name; size_t namesz; + /* Ignore groff compatibility mode for now. */ + + if (tok == ROFF_ds1) + tok = ROFF_ds; + else if (tok == ROFF_as1) + tok = ROFF_as; + /* * The first word is the name of the string. * If it is empty or terminated by an escape sequence, @@ -1476,14 +2006,14 @@ roff_getop(const char *v, int *pos, char *res) */ static int roff_evalpar(struct roff *r, int ln, - const char *v, int *pos, int *res) + const char *v, int *pos, int *res, int flags) { if ('(' != v[*pos]) - return(roff_getnum(v, pos, res)); + return(roff_getnum(v, pos, res, flags)); (*pos)++; - if ( ! roff_evalnum(r, ln, v, pos, res, 1)) + if ( ! roff_evalnum(r, ln, v, pos, res, flags | ROFFNUM_WHITE)) return(0); /* @@ -1506,7 +2036,7 @@ roff_evalpar(struct roff *r, int ln, */ static int roff_evalnum(struct roff *r, int ln, const char *v, - int *pos, int *res, int skipwhite) + int *pos, int *res, int flags) { int mypos, operand2; char operator; @@ -1516,29 +2046,29 @@ roff_evalnum(struct roff *r, int ln, const char *v, pos = &mypos; } - if (skipwhite) + if (flags & ROFFNUM_WHITE) while (isspace((unsigned char)v[*pos])) (*pos)++; - if ( ! roff_evalpar(r, ln, v, pos, res)) + if ( ! roff_evalpar(r, ln, v, pos, res, flags)) return(0); while (1) { - if (skipwhite) + if (flags & ROFFNUM_WHITE) while (isspace((unsigned char)v[*pos])) (*pos)++; if ( ! roff_getop(v, pos, &operator)) break; - if (skipwhite) + if (flags & ROFFNUM_WHITE) while (isspace((unsigned char)v[*pos])) (*pos)++; - if ( ! roff_evalpar(r, ln, v, pos, &operand2)) + if ( ! roff_evalpar(r, ln, v, pos, &operand2, flags)) return(0); - if (skipwhite) + if (flags & ROFFNUM_WHITE) while (isspace((unsigned char)v[*pos])) (*pos)++; @@ -1556,7 +2086,7 @@ roff_evalnum(struct roff *r, int ln, const char *v, *res *= operand2; break; case '/': - if (0 == operand2) { + if (operand2 == 0) { mandoc_msg(MANDOCERR_DIVZERO, r->parse, ln, *pos, v); *res = 0; @@ -1565,6 +2095,12 @@ roff_evalnum(struct roff *r, int ln, const char *v, *res /= operand2; break; case '%': + if (operand2 == 0) { + mandoc_msg(MANDOCERR_DIVZERO, + r->parse, ln, *pos, v); + *res = 0; + break; + } *res %= operand2; break; case '<': @@ -1736,7 +2272,7 @@ roff_nr(ROFF_ARGS) if (sign == '+' || sign == '-') val++; - if (roff_evalnum(r, ln, val, NULL, &iv, 0)) + if (roff_evalnum(r, ln, val, NULL, &iv, ROFFNUM_SCALE)) roff_setreg(r, key, iv, sign); return(ROFF_IGN); @@ -1791,24 +2327,29 @@ roff_rm(ROFF_ARGS) static enum rofferr roff_it(ROFF_ARGS) { - char *cp; - size_t len; int iv; /* Parse the number of lines. */ - cp = buf->buf + pos; - len = strcspn(cp, " \t"); - cp[len] = '\0'; - if ((iv = mandoc_strntoi(cp, len, 10)) <= 0) { + + if ( ! roff_evalnum(r, ln, buf->buf, &pos, &iv, 0)) { mandoc_msg(MANDOCERR_IT_NONUM, r->parse, ln, ppos, buf->buf + 1); return(ROFF_IGN); } - cp += len + 1; - /* Arm the input line trap. */ + while (isspace((unsigned char)buf->buf[pos])) + pos++; + + /* + * Arm the input line trap. + * Special-casing "an-trap" is an ugly workaround to cope + * with DocBook stupidly fiddling with man(7) internals. + */ + roffit_lines = iv; - roffit_macro = mandoc_strdup(cp); + roffit_macro = mandoc_strdup(iv != 1 || + strcmp(buf->buf + pos, "an-trap") ? + buf->buf + pos : "br"); return(ROFF_IGN); } @@ -1849,9 +2390,12 @@ roff_TE(ROFF_ARGS) if (NULL == r->tbl) mandoc_msg(MANDOCERR_BLK_NOTOPEN, r->parse, ln, ppos, "TE"); - else - tbl_end(&r->tbl); - + else if ( ! tbl_end(&r->tbl)) { + free(buf->buf); + buf->buf = mandoc_strdup(".sp"); + buf->sz = 4; + return(ROFF_REPARSE); + } return(ROFF_IGN); } @@ -1990,6 +2534,14 @@ roff_TS(ROFF_ARGS) } static enum rofferr +roff_brp(ROFF_ARGS) +{ + + buf->buf[pos - 1] = '\0'; + return(ROFF_CONT); +} + +static enum rofferr roff_cc(ROFF_ARGS) { const char *p; @@ -2000,7 +2552,8 @@ roff_cc(ROFF_ARGS) r->control = 0; if (*p != '\0') - mandoc_msg(MANDOCERR_ARGCOUNT, r->parse, ln, ppos, NULL); + mandoc_vmsg(MANDOCERR_ARG_EXCESS, r->parse, + ln, p - buf->buf, "cc ... %s", p); return(ROFF_IGN); } @@ -2015,7 +2568,7 @@ roff_tr(ROFF_ARGS) p = buf->buf + pos; if (*p == '\0') { - mandoc_msg(MANDOCERR_ARGCOUNT, r->parse, ln, ppos, NULL); + mandoc_msg(MANDOCERR_REQ_EMPTY, r->parse, ln, ppos, "tr"); return(ROFF_IGN); } @@ -2043,8 +2596,8 @@ roff_tr(ROFF_ARGS) } ssz = (size_t)(p - second); } else if (*second == '\0') { - mandoc_msg(MANDOCERR_ARGCOUNT, r->parse, - ln, (int)(p - buf->buf), NULL); + mandoc_vmsg(MANDOCERR_TR_ODD, r->parse, + ln, first - buf->buf, "tr %s", first); second = " "; p--; } @@ -2070,7 +2623,7 @@ roff_tr(ROFF_ARGS) static enum rofferr roff_so(ROFF_ARGS) { - char *name; + char *name, *cp; name = buf->buf + pos; mandoc_vmsg(MANDOCERR_SO, r->parse, ln, ppos, "so %s", name); @@ -2085,7 +2638,12 @@ roff_so(ROFF_ARGS) if (*name == '/' || strstr(name, "../") || strstr(name, "/..")) { mandoc_vmsg(MANDOCERR_SO_PATH, r->parse, ln, ppos, ".so %s", name); - return(ROFF_ERR); + buf->sz = mandoc_asprintf(&cp, + ".sp\nSee the file %s.\n.sp", name) + 1; + free(buf->buf); + buf->buf = cp; + *offs = 0; + return(ROFF_REPARSE); } *offs = pos; @@ -2095,14 +2653,16 @@ roff_so(ROFF_ARGS) static enum rofferr roff_userdef(ROFF_ARGS) { - const char *arg[9]; + const char *arg[9], *ap; char *cp, *n1, *n2; int i; + size_t asz, rsz; /* * Collect pointers to macro argument strings * and NUL-terminate them. */ + cp = buf->buf + pos; for (i = 0; i < 9; i++) arg[i] = *cp == '\0' ? "" : @@ -2111,31 +2671,90 @@ roff_userdef(ROFF_ARGS) /* * Expand macro arguments. */ - buf->sz = 0; - n1 = cp = mandoc_strdup(r->current_string); - while ((cp = strstr(cp, "\\$")) != NULL) { - i = cp[2] - '1'; - if (0 > i || 8 < i) { - /* Not an argument invocation. */ - cp += 2; + + buf->sz = strlen(r->current_string) + 1; + n1 = cp = mandoc_malloc(buf->sz); + memcpy(n1, r->current_string, buf->sz); + while (*cp != '\0') { + + /* Scan ahead for the next argument invocation. */ + + if (*cp++ != '\\') + continue; + if (*cp++ != '$') + continue; + i = *cp - '1'; + if (0 > i || 8 < i) continue; + cp -= 2; + + /* + * Determine the size of the expanded argument, + * taking escaping of quotes into account. + */ + + asz = 0; + for (ap = arg[i]; *ap != '\0'; ap++) { + asz++; + if (*ap == '"') + asz += 3; + } + if (asz != 3) { + + /* + * Determine the size of the rest of the + * unexpanded macro, including the NUL. + */ + + rsz = buf->sz - (cp - n1) - 3; + + /* + * When shrinking, move before + * releasing the storage. + */ + + if (asz < 3) + memmove(cp + asz, cp + 3, rsz); + + /* + * Resize the storage for the macro + * and readjust the parse pointer. + */ + + buf->sz += asz - 3; + n2 = mandoc_realloc(n1, buf->sz); + cp = n2 + (cp - n1); + n1 = n2; + + /* + * When growing, make room + * for the expanded argument. + */ + + if (asz > 3) + memmove(cp + asz, cp + 3, rsz); + } + + /* Copy the expanded argument, escaping quotes. */ + + n2 = cp; + for (ap = arg[i]; *ap != '\0'; ap++) { + if (*ap == '"') { + memcpy(n2, "\\(dq", 4); + n2 += 4; + } else + *n2++ = *ap; } - *cp = '\0'; - buf->sz = mandoc_asprintf(&n2, "%s%s%s", - n1, arg[i], cp + 3) + 1; - cp = n2 + (cp - n1); - free(n1); - n1 = n2; } /* * Replace the macro invocation * by the expanded macro. */ + free(buf->buf); buf->buf = n1; - if (buf->sz == 0) - buf->sz = strlen(buf->buf) + 1; + *offs = 0; return(buf->sz > 1 && buf->buf[buf->sz - 2] == '\n' ? ROFF_REPARSE : ROFF_APPEND); diff --git a/contrib/mdocml/st.in b/contrib/mdocml/st.in index 5d2f129e3f42..e70680f3ab27 100644 --- a/contrib/mdocml/st.in +++ b/contrib/mdocml/st.in @@ -1,4 +1,4 @@ -/* $Id: st.in,v 1.27 2014/11/30 21:56:18 schwarze Exp $ */ +/* $Id: st.in,v 1.28 2015/02/17 20:37:17 schwarze Exp $ */ /* * Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv> * @@ -28,50 +28,50 @@ * REMEMBER TO ADD NEW STANDARDS TO MDOC.7! */ -LINE("-p1003.1-88", "IEEE Std 1003.1-1988 (\\(lqPOSIX.1\\(rq)") -LINE("-p1003.1-90", "IEEE Std 1003.1-1990 (\\(lqPOSIX.1\\(rq)") -LINE("-p1003.1-96", "ISO/IEC 9945-1:1996 (\\(lqPOSIX.1\\(rq)") -LINE("-p1003.1-2001", "IEEE Std 1003.1-2001 (\\(lqPOSIX.1\\(rq)") -LINE("-p1003.1-2004", "IEEE Std 1003.1-2004 (\\(lqPOSIX.1\\(rq)") -LINE("-p1003.1-2008", "IEEE Std 1003.1-2008 (\\(lqPOSIX.1\\(rq)") -LINE("-p1003.1-2013", "IEEE Std 1003.1-2008/Cor 1-2013 (\\(lqPOSIX.1\\(rq)") -LINE("-p1003.1", "IEEE Std 1003.1 (\\(lqPOSIX.1\\(rq)") -LINE("-p1003.1b", "IEEE Std 1003.1b (\\(lqPOSIX.1b\\(rq)") -LINE("-p1003.1b-93", "IEEE Std 1003.1b-1993 (\\(lqPOSIX.1b\\(rq)") -LINE("-p1003.1c-95", "IEEE Std 1003.1c-1995 (\\(lqPOSIX.1c\\(rq)") -LINE("-p1003.1g-2000", "IEEE Std 1003.1g-2000 (\\(lqPOSIX.1g\\(rq)") -LINE("-p1003.1i-95", "IEEE Std 1003.1i-1995 (\\(lqPOSIX.1i\\(rq)") -LINE("-p1003.2", "IEEE Std 1003.2 (\\(lqPOSIX.2\\(rq)") -LINE("-p1003.2-92", "IEEE Std 1003.2-1992 (\\(lqPOSIX.2\\(rq)") -LINE("-p1003.2a-92", "IEEE Std 1003.2a-1992 (\\(lqPOSIX.2\\(rq)") -LINE("-isoC", "ISO/IEC 9899:1990 (\\(lqISO\\~C90\\(rq)") -LINE("-isoC-90", "ISO/IEC 9899:1990 (\\(lqISO\\~C90\\(rq)") -LINE("-isoC-amd1", "ISO/IEC 9899/AMD1:1995 (\\(lqISO\\~C90, Amendment 1\\(rq)") -LINE("-isoC-tcor1", "ISO/IEC 9899/TCOR1:1994 (\\(lqISO\\~C90, Technical Corrigendum 1\\(rq)") -LINE("-isoC-tcor2", "ISO/IEC 9899/TCOR2:1995 (\\(lqISO\\~C90, Technical Corrigendum 2\\(rq)") -LINE("-isoC-99", "ISO/IEC 9899:1999 (\\(lqISO\\~C99\\(rq)") -LINE("-isoC-2011", "ISO/IEC 9899:2011 (\\(lqISO\\~C11\\(rq)") -LINE("-iso9945-1-90", "ISO/IEC 9945-1:1990 (\\(lqPOSIX.1\\(rq)") -LINE("-iso9945-1-96", "ISO/IEC 9945-1:1996 (\\(lqPOSIX.1\\(rq)") -LINE("-iso9945-2-93", "ISO/IEC 9945-2:1993 (\\(lqPOSIX.2\\(rq)") -LINE("-ansiC", "ANSI X3.159-1989 (\\(lqANSI\\~C89\\(rq)") -LINE("-ansiC-89", "ANSI X3.159-1989 (\\(lqANSI\\~C89\\(rq)") +LINE("-p1003.1-88", "IEEE Std 1003.1-1988 (\\(LqPOSIX.1\\(Rq)") +LINE("-p1003.1-90", "IEEE Std 1003.1-1990 (\\(LqPOSIX.1\\(Rq)") +LINE("-p1003.1-96", "ISO/IEC 9945-1:1996 (\\(LqPOSIX.1\\(Rq)") +LINE("-p1003.1-2001", "IEEE Std 1003.1-2001 (\\(LqPOSIX.1\\(Rq)") +LINE("-p1003.1-2004", "IEEE Std 1003.1-2004 (\\(LqPOSIX.1\\(Rq)") +LINE("-p1003.1-2008", "IEEE Std 1003.1-2008 (\\(LqPOSIX.1\\(Rq)") +LINE("-p1003.1-2013", "IEEE Std 1003.1-2008/Cor 1-2013 (\\(LqPOSIX.1\\(Rq)") +LINE("-p1003.1", "IEEE Std 1003.1 (\\(LqPOSIX.1\\(Rq)") +LINE("-p1003.1b", "IEEE Std 1003.1b (\\(LqPOSIX.1b\\(Rq)") +LINE("-p1003.1b-93", "IEEE Std 1003.1b-1993 (\\(LqPOSIX.1b\\(Rq)") +LINE("-p1003.1c-95", "IEEE Std 1003.1c-1995 (\\(LqPOSIX.1c\\(Rq)") +LINE("-p1003.1g-2000", "IEEE Std 1003.1g-2000 (\\(LqPOSIX.1g\\(Rq)") +LINE("-p1003.1i-95", "IEEE Std 1003.1i-1995 (\\(LqPOSIX.1i\\(Rq)") +LINE("-p1003.2", "IEEE Std 1003.2 (\\(LqPOSIX.2\\(Rq)") +LINE("-p1003.2-92", "IEEE Std 1003.2-1992 (\\(LqPOSIX.2\\(Rq)") +LINE("-p1003.2a-92", "IEEE Std 1003.2a-1992 (\\(LqPOSIX.2\\(Rq)") +LINE("-isoC", "ISO/IEC 9899:1990 (\\(LqISO\\~C90\\(Rq)") +LINE("-isoC-90", "ISO/IEC 9899:1990 (\\(LqISO\\~C90\\(Rq)") +LINE("-isoC-amd1", "ISO/IEC 9899/AMD1:1995 (\\(LqISO\\~C90, Amendment 1\\(Rq)") +LINE("-isoC-tcor1", "ISO/IEC 9899/TCOR1:1994 (\\(LqISO\\~C90, Technical Corrigendum 1\\(Rq)") +LINE("-isoC-tcor2", "ISO/IEC 9899/TCOR2:1995 (\\(LqISO\\~C90, Technical Corrigendum 2\\(Rq)") +LINE("-isoC-99", "ISO/IEC 9899:1999 (\\(LqISO\\~C99\\(Rq)") +LINE("-isoC-2011", "ISO/IEC 9899:2011 (\\(LqISO\\~C11\\(Rq)") +LINE("-iso9945-1-90", "ISO/IEC 9945-1:1990 (\\(LqPOSIX.1\\(Rq)") +LINE("-iso9945-1-96", "ISO/IEC 9945-1:1996 (\\(LqPOSIX.1\\(Rq)") +LINE("-iso9945-2-93", "ISO/IEC 9945-2:1993 (\\(LqPOSIX.2\\(Rq)") +LINE("-ansiC", "ANSI X3.159-1989 (\\(LqANSI\\~C89\\(Rq)") +LINE("-ansiC-89", "ANSI X3.159-1989 (\\(LqANSI\\~C89\\(Rq)") LINE("-ieee754", "IEEE Std 754-1985") LINE("-iso8802-3", "ISO 8802-3: 1989") LINE("-iso8601", "ISO 8601") -LINE("-ieee1275-94", "IEEE Std 1275-1994 (\\(lqOpen Firmware\\(rq)") -LINE("-xpg3", "X/Open Portability Guide Issue\\~3 (\\(lqXPG3\\(rq)") -LINE("-xpg4", "X/Open Portability Guide Issue\\~4 (\\(lqXPG4\\(rq)") -LINE("-xpg4.2", "X/Open Portability Guide Issue\\~4, Version\\~2 (\\(lqXPG4.2\\(rq)") -LINE("-xbd5", "X/Open Base Definitions Issue\\~5 (\\(lqXBD5\\(rq)") -LINE("-xcu5", "X/Open Commands and Utilities Issue\\~5 (\\(lqXCU5\\(rq)") -LINE("-xsh4.2", "X/Open System Interfaces and Headers Issue\\~4, Version\\~2 (\\(lqXSH4.2\\(rq)") -LINE("-xsh5", "X/Open System Interfaces and Headers Issue\\~5 (\\(lqXSH5\\(rq)") -LINE("-xns5", "X/Open Networking Services Issue\\~5 (\\(lqXNS5\\(rq)") -LINE("-xns5.2", "X/Open Networking Services Issue\\~5.2 (\\(lqXNS5.2\\(rq)") -LINE("-xcurses4.2", "X/Open Curses Issue\\~4, Version\\~2 (\\(lqXCURSES4.2\\(rq)") -LINE("-susv1", "Version\\~1 of the Single UNIX Specification (\\(lqSUSv1\\(rq)") -LINE("-susv2", "Version\\~2 of the Single UNIX Specification (\\(lqSUSv2\\(rq)") -LINE("-susv3", "Version\\~3 of the Single UNIX Specification (\\(lqSUSv3\\(rq)") -LINE("-susv4", "Version\\~4 of the Single UNIX Specification (\\(lqSUSv4\\(rq)") -LINE("-svid4", "System\\~V Interface Definition, Fourth Edition (\\(lqSVID4\\(rq)") +LINE("-ieee1275-94", "IEEE Std 1275-1994 (\\(LqOpen Firmware\\(Rq)") +LINE("-xpg3", "X/Open Portability Guide Issue\\~3 (\\(LqXPG3\\(Rq)") +LINE("-xpg4", "X/Open Portability Guide Issue\\~4 (\\(LqXPG4\\(Rq)") +LINE("-xpg4.2", "X/Open Portability Guide Issue\\~4, Version\\~2 (\\(LqXPG4.2\\(Rq)") +LINE("-xbd5", "X/Open Base Definitions Issue\\~5 (\\(LqXBD5\\(Rq)") +LINE("-xcu5", "X/Open Commands and Utilities Issue\\~5 (\\(LqXCU5\\(Rq)") +LINE("-xsh4.2", "X/Open System Interfaces and Headers Issue\\~4, Version\\~2 (\\(LqXSH4.2\\(Rq)") +LINE("-xsh5", "X/Open System Interfaces and Headers Issue\\~5 (\\(LqXSH5\\(Rq)") +LINE("-xns5", "X/Open Networking Services Issue\\~5 (\\(LqXNS5\\(Rq)") +LINE("-xns5.2", "X/Open Networking Services Issue\\~5.2 (\\(LqXNS5.2\\(Rq)") +LINE("-xcurses4.2", "X/Open Curses Issue\\~4, Version\\~2 (\\(LqXCURSES4.2\\(Rq)") +LINE("-susv1", "Version\\~1 of the Single UNIX Specification (\\(LqSUSv1\\(Rq)") +LINE("-susv2", "Version\\~2 of the Single UNIX Specification (\\(LqSUSv2\\(Rq)") +LINE("-susv3", "Version\\~3 of the Single UNIX Specification (\\(LqSUSv3\\(Rq)") +LINE("-susv4", "Version\\~4 of the Single UNIX Specification (\\(LqSUSv4\\(Rq)") +LINE("-svid4", "System\\~V Interface Definition, Fourth Edition (\\(LqSVID4\\(Rq)") diff --git a/contrib/mdocml/style.css b/contrib/mdocml/style.css index 83c5acc820da..1328f4d30b45 100644 --- a/contrib/mdocml/style.css +++ b/contrib/mdocml/style.css @@ -1,4 +1,4 @@ -/* $Id: style.css,v 1.30 2014/09/27 11:16:24 kristaps Exp $ */ +/* $Id: style.css,v 1.31 2015/02/10 08:05:30 schwarze Exp $ */ /* * This is an example style-sheet provided for mandoc(1) and the -Thtml @@ -51,7 +51,7 @@ small { } /* Small: SB, SM. */ i.addr { font-weight: normal; } /* Address (Ad). */ i.arg { font-weight: normal; } /* Command argument (Ar). */ span.author { } /* Author name (An). */ -b.cmd { font-style: normal; } /* Command (Cm). */ +b.cmd { font-style: normal; } /* Command (Cm). */ b.config { font-style: normal; } /* Config statement (Cd). */ span.define { } /* Defines (Dv). */ span.desc { } /* Nd. After em-dash. */ diff --git a/contrib/mdocml/tbl.3 b/contrib/mdocml/tbl.3 index 05e423fe548e..f3db622e33cb 100644 --- a/contrib/mdocml/tbl.3 +++ b/contrib/mdocml/tbl.3 @@ -1,4 +1,4 @@ -.\" $Id: tbl.3,v 1.1 2013/06/01 05:44:39 schwarze Exp $ +.\" $Id: tbl.3,v 1.2 2015/01/30 04:11:50 schwarze Exp $ .\" .\" Copyright (c) 2013 Ingo Schwarze <schwarze@openbsd.org> .\" @@ -14,7 +14,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: June 1 2013 $ +.Dd $Mdocdate: January 30 2015 $ .Dt TBL 3 .Os .Sh NAME @@ -79,12 +79,37 @@ It is defined in created in .Fn tbl_alloc , and stored in the members -.Va first_tbl , -.Va last_tbl , +.Fa first_tbl , +.Fa last_tbl , and -.Va tbl +.Fa tbl of .Vt struct roff Bq Pa roff.c . +.Pp +The +.Fa first_span , +.Fa current_span , +.Fa last_span , +and +.Fa next +members may be +.Dv NULL . +The +.Fa first_row +and +.Fa last_row +members may be +.Dv NULL , +but if there is a span, the function +.Fn tbl_layout +guarantees that these pointers are not +.Dv NULL . +The function +.Fn tbl_alloc +guarantees that the +.Fa parse +member is not +.Dv NULL . .It Vt struct tbl_opts This structure describes the options of one table. It is used as a substructure of @@ -92,26 +117,27 @@ It is used as a substructure of and thus created and deleted together with it. It is filled in .Fn tbl_options . -.It Vt struct tbl_head -This structure describes one layout column in a table, -in particular the vertical line to its left. -It is allocated and filled in -.Fn cell_alloc Bq Pa tbl_layout.c -and referenced from the -.Va first_head -and -.Va last_head -members of -.Vt struct tbl_node . .It Vt struct tbl_row This structure describes one layout line in a table by maintaining a list of all the cells in that line. It is allocated and filled in .Fn row Bq Pa tbl_layout.c and referenced from the -.Va layout +.Fa layout member of .Vt struct tbl_node . +.Pp +The +.Fa next +member may be +.Dv NULL . +The function +.Fn tbl_layout +guarantees that the +.Fa first +and +.Fa last +members are not NULL. .It Vt struct tbl_cell This structure describes one layout cell in a table, in particular its alignment, membership in spans, and @@ -119,11 +145,16 @@ usage for lines. It is allocated and filled in .Fn cell_alloc Bq Pa tbl_layout.c and referenced from the -.Va first +.Fa first and -.Va last +.Fa last members of .Vt struct tbl_row . +.Pp +The +.Fa next +member may be +.Dv NULL . .It Vt struct tbl_span This structure describes one data line in a table by maintaining a list of all data cells in that line @@ -133,14 +164,14 @@ It is allocated and filled in which is called from .Fn tbl_data and referenced from the -.Va first_span , -.Va current_span , +.Fa first_span , +.Fa current_span , and -.Va last_span +.Fa last_span members of .Vt struct tbl_node , and from the -.Va span +.Fa span members of .Vt struct man_node and @@ -149,18 +180,48 @@ from .In man.h and .In mdoc.h . +.Pp +The +.Fa first , +.Fa last , +.Fa prev , +and +.Fa next +members may be +.Dv NULL . +The function +.Fn newspan Bq Pa tbl_data.c +guarantees that the +.Fa opts +and +.Fa layout +members are not +.Dv NULL . .It Vt struct tbl_dat This structure describes one data cell in a table by specifying whether it contains a line or data, whether it spans additional layout cells, and by storing the data. It is allocated and filled in -.Fn data +.Fn tbl_data and referenced from the -.Va first +.Fa first and -.Va last +.Fa last members of .Vt struct tbl_span . +.Pp +The +.Fa string +and +.Fa next +members may be +.Dv NULL . +The function +.Fn getdata +guarantees that the +.Fa layout +member is not +.Dv NULL . .El .Ss Interface functions The following functions are implemented in @@ -185,7 +246,7 @@ Called from .Fn roff_parseln . .It Fn tbl_restart Resets the -.Va part +.Fa part member of .Vt struct tbl_node to @@ -210,7 +271,7 @@ and .It Fn tbl_free Frees the specified .Vt struct tbl_node -and all the tbl_row, tbl_cell, tbl_span, tbl_dat and tbl_head structures +and all the tbl_row, tbl_cell, tbl_span, and tbl_dat structures referenced from it. Called from .Fn roff_free @@ -228,10 +289,8 @@ called from .Fn tbl_read . .It Ft int Fn tbl_layout "struct tbl_node *tbl" "int ln" "const char *p" Allocates and fills one -.Vt struct tbl_head -for each layout column, one .Vt struct tbl_row -for each layout line, and one +for each layout line and one .Vt struct tbl_cell for each layout cell. Implemented in @@ -242,8 +301,8 @@ called from Allocates one .Vt struct tbl_span for each data line and calls -.Fn data -on that line. +.Fn getdata +for each data cell. Implemented in .Pa tbl_data.c , called from @@ -255,7 +314,7 @@ When finding switches back to .Dv TBL_PART_DATA mode and calls -.Fn data +.Fn getdata if there are more data cells on the line. Otherwise, appends the data to the current data cell. Implemented in @@ -264,7 +323,7 @@ called from .Fn tbl_read . .It Xo .Ft int -.Fo data +.Fo getdata .Fa "struct tbl_node *tbl" .Fa "struct tbl_span *dp" .Fa "int ln" diff --git a/contrib/mdocml/tbl.7 b/contrib/mdocml/tbl.7 index 04f5b47f8c5d..c8fa8e484499 100644 --- a/contrib/mdocml/tbl.7 +++ b/contrib/mdocml/tbl.7 @@ -1,7 +1,7 @@ -.\" $Id: tbl.7,v 1.21 2014/11/26 17:51:55 schwarze Exp $ +.\" $Id: tbl.7,v 1.26 2015/01/29 00:33:57 schwarze Exp $ .\" .\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> -.\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org> +.\" Copyright (c) 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -15,7 +15,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: November 26 2014 $ +.Dd $Mdocdate: January 29 2015 $ .Dt TBL 7 .Os .Sh NAME @@ -50,7 +50,7 @@ macro tags, whose precise syntax is documented in Tables consist of a series of options on a single line, followed by the table layout, followed by data. .Pp -For example, the following creates a boxed table with digits centred in +For example, the following creates a boxed table with digits centered in the cells. .Bd -literal -offset indent \&.TS @@ -133,58 +133,59 @@ c c c. in the case of .Xr man 7 . .Ss Options -The first line of a table consists of space-separated option keys and -modifiers terminated by a semicolon. -For GNU compatibility, option keys can also be separated by commas. +The first line of a table may contain options separated by spaces, tabs, +or commas and terminated by a semicolon. If the first line does not have a terminating semicolon, it is assumed that no options are specified and instead a .Sx Layout is processed. -Some options accept arguments enclosed by parenthesis. +Some options require arguments enclosed by parentheses. The following case-insensitive options are available: .Bl -tag -width Ds -.It Cm center -This option is not supported by -.Xr mandoc 1 . -This may also be invoked with -.Cm centre . -.It Cm delim -Accepts a two-character argument. -This option is not supported by -.Xr mandoc 1 . -.It Cm expand -This option is not supported by -.Xr mandoc 1 . +.It Cm allbox +Draw a single-line box around each table cell. +Currently treated as a synonym for +.Cm box . .It Cm box Draw a single-line box around the table. -This may also be invoked with +For GNU compatibility, this may also be invoked with .Cm frame . +.It Cm center +Center the table instead of left-adjusting it. +For GNU compatibility, this may also be invoked with +.Cm centre . +.It Cm decimalpoint +Use the single-character argument as the decimal point with the +.Cm n +layout key. +This is a GNU extension. +.It Cm delim +Use the two characters of the argument as +.Xr eqn 7 +delimiters. +Currently unsupported. .It Cm doublebox Draw a double-line box around the table. -This may also be invoked with +For GNU compatibility, this may also be invoked with .Cm doubleframe . -.It Cm allbox -This option is not supported by -.Xr mandoc 1 . -.It Cm tab -Accepts a single-character argument. -This character is used as a delimiter between data cells, which otherwise -defaults to the tab character. +.It Cm expand +Increase the width of the table to the current line length. +Currently ignored. .It Cm linesize -Accepts a natural number (all digits). -This option is not supported by -.Xr mandoc 1 . +Draw lines with the point size given by the unsigned integer argument. +Currently ignored. .It Cm nokeep -This option is not supported by -.Xr mandoc 1 . -.It Cm decimalpoint -Accepts a single-character argument. -This character will be used as the decimal point with the -.Cm n -layout key. +Allow page breaks within the table. +This is a GNU extension and currently ignored. .It Cm nospaces -This option is not supported by -.Xr mandoc 1 . +Ignore leading and trailing spaces in data cells. +This is a GNU extension and currently ignored. +.It Cm nowarn +Suppress warnings about tables exceeding the current line length. +This is a GNU extension and currently ignored. +.It Cm tab +Use the single-character argument as a delimiter between data cells. +By default, the tab character is used. .El .Ss Layout The table layout follows @@ -199,7 +200,7 @@ Layout lines may also be separated by a comma. Each layout cell consists of one of the following case-insensitive keys: .Bl -tag -width 2n .It Cm c -Centre a literal string within its column. +Center a literal string within its column. .It Cm r Right-justify a literal string within its column. .It Cm l @@ -249,6 +250,9 @@ The following case-insensitive modifier keys are available: .Bl -tag -width 2n .It Cm b Use a bold font for the contents of this column. +.It Cm d +Move cell content down to the last cell of a vertical span. +Currently ignored. .It Cm e Make this column wider to match the maximum width of any other column also having the @@ -261,6 +265,27 @@ See the manual for supported one-character font names. .It Cm i Use an italic font for the contents of this column. +.It Cm m +Specify a cell start macro. +This is a GNU extension and currently unsupported. +.It Cm p +Set the point size to the following unsigned argument, +or change it by the following signed argument. +Currently ignored. +.It Cm v +Set the vertical line spacing to the following unsigned argument, +or change it by the following signed argument. +Currently ignored. +.It Cm t +Do not vertically center cell content in the vertical span, +leave it at the top. +Currently ignored. +.It Cm u +Move cell content up by half a table line. +Currently ignored. +.It Cm w +Specify minimum column width. +Currently ignored. .It Cm x After determining the width of all other columns, distribute the rest of the line length among all columns having the @@ -270,16 +295,7 @@ modifier. Do not use this cell for determining the width of this column. .El .Pp -The modifiers -.Cm d , -.Cm t , -.Cm u , -and -.Cm w -are ignored by -.Xr mandoc 1 . -.Pp -For example, the following layout specifies a centre-justified column of +For example, the following layout specifies a center-justified column of minimum width 10, followed by vertical bar, followed by a left-justified column of minimum width 10, another vertical bar, then a column using bold font justified about the decimal point in numbers: @@ -312,18 +328,17 @@ It may then be followed by a tab .Pq or as designated by Cm tab or an end-of-line to terminate the row. .Sh COMPATIBILITY -This section documents compatibility between mandoc and other -.Nm -implementations, at this time limited to GNU tbl. -.Pp -.Bl -dash -compact -.It -In GNU tbl, comments and macros are disallowed prior to the data block -of a table. The .Xr mandoc 1 -implementation allows them. -.El +implementation of +.Nm +doesn't support +.Xr mdoc 7 +and +.Xr man 7 +macros and +.Xr eqn 7 +equations inside tables. .Sh SEE ALSO .Xr mandoc 1 , .Xr man 7 , diff --git a/contrib/mdocml/tbl.c b/contrib/mdocml/tbl.c index bfed242b9d9e..00ee4661254b 100644 --- a/contrib/mdocml/tbl.c +++ b/contrib/mdocml/tbl.c @@ -1,7 +1,7 @@ -/* $Id: tbl.c,v 1.30 2014/08/10 23:54:41 schwarze Exp $ */ +/* $Id: tbl.c,v 1.39 2015/01/30 17:32:16 schwarze Exp $ */ /* * Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2011 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2011, 2015 Ingo Schwarze <schwarze@openbsd.org> * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -32,43 +32,58 @@ enum rofferr -tbl_read(struct tbl_node *tbl, int ln, const char *p, int offs) +tbl_read(struct tbl_node *tbl, int ln, const char *p, int pos) { - int len; const char *cp; - - cp = &p[offs]; - len = (int)strlen(cp); + int active; /* - * If we're in the options section and we don't have a - * terminating semicolon, assume we've moved directly into the - * layout section. No need to report a warning: this is, - * apparently, standard behaviour. + * In the options section, proceed to the layout section + * after a semicolon, or right away if there is no semicolon. + * Ignore semicolons in arguments. */ - if (TBL_PART_OPTS == tbl->part && len) - if (';' != cp[len - 1]) - tbl->part = TBL_PART_LAYOUT; + if (tbl->part == TBL_PART_OPTS) { + tbl->part = TBL_PART_LAYOUT; + active = 1; + for (cp = p + pos; *cp != '\0'; cp++) { + switch (*cp) { + case '(': + active = 0; + continue; + case ')': + active = 1; + continue; + case ';': + if (active) + break; + continue; + default: + continue; + } + break; + } + if (*cp == ';') { + tbl_option(tbl, ln, p, &pos); + if (p[pos] == '\0') + return(ROFF_IGN); + } + } - /* Now process each logical section of the table. */ + /* Process the other section types. */ switch (tbl->part) { - case TBL_PART_OPTS: - return(tbl_option(tbl, ln, p) ? ROFF_IGN : ROFF_ERR); case TBL_PART_LAYOUT: - return(tbl_layout(tbl, ln, p) ? ROFF_IGN : ROFF_ERR); + tbl_layout(tbl, ln, p, pos); + return(ROFF_IGN); case TBL_PART_CDATA: - return(tbl_cdata(tbl, ln, p) ? ROFF_TBL : ROFF_IGN); + return(tbl_cdata(tbl, ln, p, pos) ? ROFF_TBL : ROFF_IGN); default: break; } - /* - * This only returns zero if the line is empty, so we ignore it - * and continue on. - */ - return(tbl_data(tbl, ln, p) ? ROFF_TBL : ROFF_IGN); + tbl_data(tbl, ln, p, pos); + return(ROFF_TBL); } struct tbl_node * @@ -76,13 +91,12 @@ tbl_alloc(int pos, int line, struct mparse *parse) { struct tbl_node *tbl; - tbl = mandoc_calloc(1, sizeof(struct tbl_node)); + tbl = mandoc_calloc(1, sizeof(*tbl)); tbl->line = line; tbl->pos = pos; tbl->parse = parse; tbl->part = TBL_PART_OPTS; tbl->opts.tab = '\t'; - tbl->opts.linesize = 12; tbl->opts.decimal = '.'; return(tbl); } @@ -94,11 +108,10 @@ tbl_free(struct tbl_node *tbl) struct tbl_cell *cp; struct tbl_span *sp; struct tbl_dat *dp; - struct tbl_head *hp; - while (NULL != (rp = tbl->first_row)) { + while ((rp = tbl->first_row) != NULL) { tbl->first_row = rp->next; - while (rp->first) { + while (rp->first != NULL) { cp = rp->first; rp->first = cp->next; free(cp); @@ -106,40 +119,30 @@ tbl_free(struct tbl_node *tbl) free(rp); } - while (NULL != (sp = tbl->first_span)) { + while ((sp = tbl->first_span) != NULL) { tbl->first_span = sp->next; - while (sp->first) { + while (sp->first != NULL) { dp = sp->first; sp->first = dp->next; - if (dp->string) - free(dp->string); + free(dp->string); free(dp); } free(sp); } - while (NULL != (hp = tbl->first_head)) { - tbl->first_head = hp->next; - free(hp); - } - free(tbl); } void tbl_restart(int line, int pos, struct tbl_node *tbl) { - if (TBL_PART_CDATA == tbl->part) - mandoc_msg(MANDOCERR_TBLBLOCK, tbl->parse, - tbl->line, tbl->pos, NULL); + if (tbl->part == TBL_PART_CDATA) + mandoc_msg(MANDOCERR_TBLDATA_BLK, tbl->parse, + line, pos, "T&"); tbl->part = TBL_PART_LAYOUT; tbl->line = line; tbl->pos = pos; - - if (NULL == tbl->first_span || NULL == tbl->first_span->first) - mandoc_msg(MANDOCERR_TBLNODATA, tbl->parse, - tbl->line, tbl->pos, NULL); } const struct tbl_span * @@ -155,22 +158,26 @@ tbl_span(struct tbl_node *tbl) return(span); } -void +int tbl_end(struct tbl_node **tblp) { struct tbl_node *tbl; + struct tbl_span *sp; tbl = *tblp; *tblp = NULL; - if (NULL == tbl->first_span || NULL == tbl->first_span->first) - mandoc_msg(MANDOCERR_TBLNODATA, tbl->parse, - tbl->line, tbl->pos, NULL); - - if (tbl->last_span) - tbl->last_span->flags |= TBL_SPAN_LAST; + if (tbl->part == TBL_PART_CDATA) + mandoc_msg(MANDOCERR_TBLDATA_BLK, tbl->parse, + tbl->line, tbl->pos, "TE"); - if (TBL_PART_CDATA == tbl->part) - mandoc_msg(MANDOCERR_TBLBLOCK, tbl->parse, + sp = tbl->first_span; + while (sp != NULL && sp->first == NULL) + sp = sp->next; + if (sp == NULL) { + mandoc_msg(MANDOCERR_TBLDATA_NONE, tbl->parse, tbl->line, tbl->pos, NULL); + return(0); + } + return(1); } diff --git a/contrib/mdocml/tbl_data.c b/contrib/mdocml/tbl_data.c index 43244dabd464..e2be64eb811a 100644 --- a/contrib/mdocml/tbl_data.c +++ b/contrib/mdocml/tbl_data.c @@ -1,7 +1,7 @@ -/* $Id: tbl_data.c,v 1.32 2014/08/10 23:54:41 schwarze Exp $ */ +/* $Id: tbl_data.c,v 1.39 2015/01/30 17:32:16 schwarze Exp $ */ /* * Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2011 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2011, 2015 Ingo Schwarze <schwarze@openbsd.org> * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -30,32 +30,24 @@ #include "libmandoc.h" #include "libroff.h" -static int getdata(struct tbl_node *, struct tbl_span *, +static void getdata(struct tbl_node *, struct tbl_span *, int, const char *, int *); static struct tbl_span *newspan(struct tbl_node *, int, struct tbl_row *); -static int +static void getdata(struct tbl_node *tbl, struct tbl_span *dp, int ln, const char *p, int *pos) { struct tbl_dat *dat; struct tbl_cell *cp; - int sv, spans; + int sv; - cp = NULL; - if (dp->last && dp->last->layout) - cp = dp->last->layout->next; - else if (NULL == dp->last) - cp = dp->layout->first; + /* Advance to the next layout cell, skipping spanners. */ - /* - * Skip over spanners, since - * we want to match data with data layout cells in the header. - */ - - while (cp && TBL_CELL_SPAN == cp->pos) + cp = dp->last == NULL ? dp->layout->first : dp->last->layout->next; + while (cp != NULL && cp->pos == TBL_CELL_SPAN) cp = cp->next; /* @@ -63,34 +55,30 @@ getdata(struct tbl_node *tbl, struct tbl_span *dp, * cells. This means that we have extra input. */ - if (NULL == cp) { - mandoc_msg(MANDOCERR_TBLEXTRADAT, tbl->parse, - ln, *pos, NULL); + if (cp == NULL) { + mandoc_msg(MANDOCERR_TBLDATA_EXTRA, tbl->parse, + ln, *pos, p + *pos); /* Skip to the end... */ while (p[*pos]) (*pos)++; - return(1); + return; } - dat = mandoc_calloc(1, sizeof(struct tbl_dat)); + dat = mandoc_calloc(1, sizeof(*dat)); dat->layout = cp; dat->pos = TBL_DATA_NONE; - - assert(TBL_CELL_SPAN != cp->pos); - - for (spans = 0, cp = cp->next; cp; cp = cp->next) - if (TBL_CELL_SPAN == cp->pos) - spans++; + dat->spans = 0; + for (cp = cp->next; cp != NULL; cp = cp->next) + if (cp->pos == TBL_CELL_SPAN) + dat->spans++; else break; - dat->spans = spans; - - if (dp->last) { + if (dp->last == NULL) + dp->first = dat; + else dp->last->next = dat; - dp->last = dat; - } else - dp->last = dp->first = dat; + dp->last = dat; sv = *pos; while (p[*pos] && p[*pos] != tbl->opts.tab) @@ -102,16 +90,12 @@ getdata(struct tbl_node *tbl, struct tbl_span *dp, * until a standalone `T}', are included in our cell. */ - if (*pos - sv == 2 && 'T' == p[sv] && '{' == p[sv + 1]) { + if (*pos - sv == 2 && p[sv] == 'T' && p[sv + 1] == '{') { tbl->part = TBL_PART_CDATA; - return(1); + return; } - assert(*pos - sv >= 0); - - dat->string = mandoc_malloc((size_t)(*pos - sv + 1)); - memcpy(dat->string, &p[sv], (size_t)(*pos - sv)); - dat->string[*pos - sv] = '\0'; + dat->string = mandoc_strndup(p + sv, *pos - sv); if (p[*pos]) (*pos)++; @@ -127,24 +111,19 @@ getdata(struct tbl_node *tbl, struct tbl_span *dp, else dat->pos = TBL_DATA_DATA; - if (TBL_CELL_HORIZ == dat->layout->pos || - TBL_CELL_DHORIZ == dat->layout->pos || - TBL_CELL_DOWN == dat->layout->pos) - if (TBL_DATA_DATA == dat->pos && '\0' != *dat->string) - mandoc_msg(MANDOCERR_TBLIGNDATA, - tbl->parse, ln, sv, NULL); - - return(1); + if ((dat->layout->pos == TBL_CELL_HORIZ || + dat->layout->pos == TBL_CELL_DHORIZ || + dat->layout->pos == TBL_CELL_DOWN) && + dat->pos == TBL_DATA_DATA && *dat->string != '\0') + mandoc_msg(MANDOCERR_TBLDATA_SPAN, + tbl->parse, ln, sv, dat->string); } int -tbl_cdata(struct tbl_node *tbl, int ln, const char *p) +tbl_cdata(struct tbl_node *tbl, int ln, const char *p, int pos) { struct tbl_dat *dat; size_t sz; - int pos; - - pos = 0; dat = tbl->last_span->last; @@ -153,8 +132,9 @@ tbl_cdata(struct tbl_node *tbl, int ln, const char *p) if (p[pos] == tbl->opts.tab) { tbl->part = TBL_PART_DATA; pos++; - return(getdata(tbl, tbl->last_span, ln, p, &pos)); - } else if ('\0' == p[pos]) { + getdata(tbl, tbl->last_span, ln, p, &pos); + return(1); + } else if (p[pos] == '\0') { tbl->part = TBL_PART_DATA; return(1); } @@ -164,17 +144,17 @@ tbl_cdata(struct tbl_node *tbl, int ln, const char *p) dat->pos = TBL_DATA_DATA; - if (dat->string) { - sz = strlen(p) + strlen(dat->string) + 2; + if (dat->string != NULL) { + sz = strlen(p + pos) + strlen(dat->string) + 2; dat->string = mandoc_realloc(dat->string, sz); (void)strlcat(dat->string, " ", sz); - (void)strlcat(dat->string, p, sz); + (void)strlcat(dat->string, p + pos, sz); } else - dat->string = mandoc_strdup(p); + dat->string = mandoc_strdup(p + pos); - if (TBL_CELL_DOWN == dat->layout->pos) - mandoc_msg(MANDOCERR_TBLIGNDATA, tbl->parse, - ln, pos, NULL); + if (dat->layout->pos == TBL_CELL_DOWN) + mandoc_msg(MANDOCERR_TBLDATA_SPAN, tbl->parse, + ln, pos, dat->string); return(0); } @@ -184,37 +164,27 @@ newspan(struct tbl_node *tbl, int line, struct tbl_row *rp) { struct tbl_span *dp; - dp = mandoc_calloc(1, sizeof(struct tbl_span)); + dp = mandoc_calloc(1, sizeof(*dp)); dp->line = line; dp->opts = &tbl->opts; dp->layout = rp; - dp->head = tbl->first_head; + dp->prev = tbl->last_span; - if (tbl->last_span) { - tbl->last_span->next = dp; - tbl->last_span = dp; - } else { - tbl->last_span = tbl->first_span = dp; + if (dp->prev == NULL) { + tbl->first_span = dp; tbl->current_span = NULL; - dp->flags |= TBL_SPAN_FIRST; - } + } else + dp->prev->next = dp; + tbl->last_span = dp; return(dp); } -int -tbl_data(struct tbl_node *tbl, int ln, const char *p) +void +tbl_data(struct tbl_node *tbl, int ln, const char *p, int pos) { struct tbl_span *dp; struct tbl_row *rp; - int pos; - - pos = 0; - - if ('\0' == p[pos]) { - mandoc_msg(MANDOCERR_TBL, tbl->parse, ln, pos, NULL); - return(0); - } /* * Choose a layout row: take the one following the last parsed @@ -224,11 +194,11 @@ tbl_data(struct tbl_node *tbl, int ln, const char *p) * (it doesn't "consume" the layout). */ - if (tbl->last_span) { - assert(tbl->last_span->layout); + if (tbl->last_span != NULL) { if (tbl->last_span->pos == TBL_SPAN_DATA) { for (rp = tbl->last_span->layout->next; - rp && rp->first; rp = rp->next) { + rp != NULL && rp->first != NULL; + rp = rp->next) { switch (rp->first->pos) { case TBL_CELL_HORIZ: dp = newspan(tbl, ln, rp); @@ -246,7 +216,7 @@ tbl_data(struct tbl_node *tbl, int ln, const char *p) } else rp = tbl->last_span->layout; - if (NULL == rp) + if (rp == NULL) rp = tbl->last_span->layout; } else rp = tbl->first_row; @@ -257,19 +227,14 @@ tbl_data(struct tbl_node *tbl, int ln, const char *p) if ( ! strcmp(p, "_")) { dp->pos = TBL_SPAN_HORIZ; - return(1); + return; } else if ( ! strcmp(p, "=")) { dp->pos = TBL_SPAN_DHORIZ; - return(1); + return; } dp->pos = TBL_SPAN_DATA; - /* This returns 0 when TBL_PART_CDATA is entered. */ - - while ('\0' != p[pos]) - if ( ! getdata(tbl, dp, ln, p, &pos)) - return(0); - - return(1); + while (p[pos] != '\0') + getdata(tbl, dp, ln, p, &pos); } diff --git a/contrib/mdocml/tbl_html.c b/contrib/mdocml/tbl_html.c index 1de1bb8bdc9d..e7940381d203 100644 --- a/contrib/mdocml/tbl_html.c +++ b/contrib/mdocml/tbl_html.c @@ -1,4 +1,4 @@ -/* $Id: tbl_html.c,v 1.13 2014/10/14 02:16:06 schwarze Exp $ */ +/* $Id: tbl_html.c,v 1.16 2015/01/30 17:32:16 schwarze Exp $ */ /* * Copyright (c) 2011 Kristaps Dzonsons <kristaps@bsd.lv> * @@ -49,12 +49,12 @@ html_tbl_strlen(const char *p, void *arg) static void html_tblopen(struct html *h, const struct tbl_span *sp) { - const struct tbl_head *hp; struct htmlpair tag; struct roffsu su; struct roffcol *col; + int ic; - if (TBL_SPAN_FIRST & sp->flags) { + if (h->tbl.cols == NULL) { h->tbl.len = html_tbl_len; h->tbl.slen = html_tbl_strlen; tblcalc(&h->tbl, sp, 0); @@ -64,9 +64,9 @@ html_tblopen(struct html *h, const struct tbl_span *sp) PAIR_CLASS_INIT(&tag, "tbl"); h->tblt = print_otag(h, TAG_TABLE, 1, &tag); - for (hp = sp->head; hp; hp = hp->next) { + for (ic = 0; ic < sp->opts->cols; ic++) { bufinit(h); - col = &h->tbl.cols[hp->ident]; + col = h->tbl.cols + ic; SCALE_HS_INIT(&su, col->width); bufcat_su(h, "width", &su); PAIR_STYLE_INIT(&tag, h); @@ -88,14 +88,14 @@ print_tblclose(struct html *h) void print_tbl(struct html *h, const struct tbl_span *sp) { - const struct tbl_head *hp; const struct tbl_dat *dp; struct htmlpair tag; struct tag *tt; + int ic; /* Inhibit printing of spaces: we do padding ourselves. */ - if (NULL == h->tblt) + if (h->tblt == NULL) html_tblopen(h, sp); assert(h->tblt); @@ -114,14 +114,14 @@ print_tbl(struct html *h, const struct tbl_span *sp) break; default: dp = sp->first; - for (hp = sp->head; hp; hp = hp->next) { + for (ic = 0; ic < sp->opts->cols; ic++) { print_stagq(h, tt); print_otag(h, TAG_TD, 0, NULL); - if (NULL == dp) - break; - if (TBL_CELL_DOWN != dp->layout->pos) - if (dp->string) + if (dp == NULL || dp->layout->col > ic) + continue; + if (dp->layout->pos != TBL_CELL_DOWN) + if (dp->string != NULL) print_text(h, dp->string); dp = dp->next; } @@ -132,7 +132,7 @@ print_tbl(struct html *h, const struct tbl_span *sp) h->flags &= ~HTML_NONOSPACE; - if (TBL_SPAN_LAST & sp->flags) { + if (sp->next == NULL) { assert(h->tbl.cols); free(h->tbl.cols); h->tbl.cols = NULL; diff --git a/contrib/mdocml/tbl_layout.c b/contrib/mdocml/tbl_layout.c index 033074afbb10..ed9acc9c0a5a 100644 --- a/contrib/mdocml/tbl_layout.c +++ b/contrib/mdocml/tbl_layout.c @@ -1,7 +1,7 @@ -/* $Id: tbl_layout.c,v 1.30 2014/11/25 21:41:47 schwarze Exp $ */ +/* $Id: tbl_layout.c,v 1.38 2015/02/10 11:03:13 schwarze Exp $ */ /* * Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2012, 2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2012, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -34,15 +34,7 @@ struct tbl_phrase { enum tbl_cellt key; }; -/* - * FIXME: we can make this parse a lot nicer by, when an error is - * encountered in a layout key, bailing to the next key (i.e. to the - * next whitespace then continuing). - */ - -#define KEYS_MAX 11 - -static const struct tbl_phrase keys[KEYS_MAX] = { +static const struct tbl_phrase keys[] = { { 'c', TBL_CELL_CENTRE }, { 'r', TBL_CELL_RIGHT }, { 'l', TBL_CELL_LEFT }, @@ -55,57 +47,30 @@ static const struct tbl_phrase keys[KEYS_MAX] = { { '=', TBL_CELL_DHORIZ } }; -static int mods(struct tbl_node *, struct tbl_cell *, +#define KEYS_MAX ((int)(sizeof(keys)/sizeof(keys[0]))) + +static void mods(struct tbl_node *, struct tbl_cell *, int, const char *, int *); -static int cell(struct tbl_node *, struct tbl_row *, +static void cell(struct tbl_node *, struct tbl_row *, int, const char *, int *); static struct tbl_cell *cell_alloc(struct tbl_node *, struct tbl_row *, - enum tbl_cellt, int vert); + enum tbl_cellt); -static int +static void mods(struct tbl_node *tbl, struct tbl_cell *cp, int ln, const char *p, int *pos) { - char buf[5]; - int i; + char *endptr; - /* Not all types accept modifiers. */ +mod: + while (p[*pos] == ' ' || p[*pos] == '\t') + (*pos)++; - switch (cp->pos) { - case TBL_CELL_DOWN: - /* FALLTHROUGH */ - case TBL_CELL_HORIZ: - /* FALLTHROUGH */ - case TBL_CELL_DHORIZ: - return(1); - default: - break; - } + /* Row delimiters and cell specifiers end modifier lists. */ -mod: - /* - * XXX: since, at least for now, modifiers are non-conflicting - * (are separable by value, regardless of position), we let - * modifiers come in any order. The existing tbl doesn't let - * this happen. - */ - switch (p[*pos]) { - case '\0': - /* FALLTHROUGH */ - case ' ': - /* FALLTHROUGH */ - case '\t': - /* FALLTHROUGH */ - case ',': - /* FALLTHROUGH */ - case '.': - /* FALLTHROUGH */ - case '|': - return(1); - default: - break; - } + if (strchr(".,-=^_ACLNRSaclnrs", p[*pos]) != NULL) + return; /* Throw away parenthesised expression. */ @@ -117,123 +82,138 @@ mod: (*pos)++; goto mod; } - mandoc_msg(MANDOCERR_TBLLAYOUT, tbl->parse, + mandoc_msg(MANDOCERR_TBLLAYOUT_PAR, tbl->parse, ln, *pos, NULL); - return(0); + return; } /* Parse numerical spacing from modifier string. */ if (isdigit((unsigned char)p[*pos])) { - for (i = 0; i < 4; i++) { - if ( ! isdigit((unsigned char)p[*pos + i])) - break; - buf[i] = p[*pos + i]; - } - buf[i] = '\0'; - - /* No greater than 4 digits. */ - - if (4 == i) { - mandoc_msg(MANDOCERR_TBLLAYOUT, - tbl->parse, ln, *pos, NULL); - return(0); - } - - *pos += i; - cp->spacing = (size_t)atoi(buf); - + cp->spacing = strtoull(p + *pos, &endptr, 10); + *pos = endptr - p; goto mod; - /* NOTREACHED */ } - /* TODO: GNU has many more extensions. */ - switch (tolower((unsigned char)p[(*pos)++])) { - case 'z': - cp->flags |= TBL_CELL_WIGN; + case 'b': + cp->flags |= TBL_CELL_BOLD; goto mod; - case 'u': - cp->flags |= TBL_CELL_UP; + case 'd': + cp->flags |= TBL_CELL_BALIGN; goto mod; case 'e': cp->flags |= TBL_CELL_EQUAL; goto mod; + case 'f': + break; + case 'i': + cp->flags |= TBL_CELL_ITALIC; + goto mod; + case 'm': + mandoc_msg(MANDOCERR_TBLLAYOUT_MOD, tbl->parse, + ln, *pos, "m"); + goto mod; + case 'p': + /* FALLTHROUGH */ + case 'v': + if (p[*pos] == '-' || p[*pos] == '+') + (*pos)++; + while (isdigit((unsigned char)p[*pos])) + (*pos)++; + goto mod; case 't': cp->flags |= TBL_CELL_TALIGN; goto mod; - case 'd': - cp->flags |= TBL_CELL_BALIGN; + case 'u': + cp->flags |= TBL_CELL_UP; goto mod; case 'w': /* XXX for now, ignore minimal column width */ goto mod; case 'x': cp->flags |= TBL_CELL_WMAX; goto mod; - case 'f': - break; - case 'r': - /* FALLTHROUGH */ - case 'b': - /* FALLTHROUGH */ - case 'i': - (*pos)--; - break; + case 'z': + cp->flags |= TBL_CELL_WIGN; + goto mod; + case '|': + if (cp->vert < 2) + cp->vert++; + else + mandoc_msg(MANDOCERR_TBLLAYOUT_VERT, + tbl->parse, ln, *pos - 1, NULL); + goto mod; default: - mandoc_msg(MANDOCERR_TBLLAYOUT, tbl->parse, - ln, *pos - 1, NULL); - return(0); + mandoc_vmsg(MANDOCERR_TBLLAYOUT_CHAR, tbl->parse, + ln, *pos - 1, "%c", p[*pos - 1]); + goto mod; } - switch (tolower((unsigned char)p[(*pos)++])) { + /* Ignore parenthised font names for now. */ + + if (p[*pos] == '(') + goto mod; + + /* Support only one-character font-names for now. */ + + if (p[*pos] == '\0' || (p[*pos + 1] != ' ' && p[*pos + 1] != '.')) { + mandoc_vmsg(MANDOCERR_FT_BAD, tbl->parse, + ln, *pos, "TS %s", p + *pos - 1); + if (p[*pos] != '\0') + (*pos)++; + if (p[*pos] != '\0') + (*pos)++; + goto mod; + } + + switch (p[(*pos)++]) { case '3': /* FALLTHROUGH */ - case 'b': + case 'B': cp->flags |= TBL_CELL_BOLD; goto mod; case '2': /* FALLTHROUGH */ - case 'i': + case 'I': cp->flags |= TBL_CELL_ITALIC; goto mod; case '1': /* FALLTHROUGH */ - case 'r': + case 'R': goto mod; default: - break; - } - if (isalnum((unsigned char)p[*pos - 1])) { mandoc_vmsg(MANDOCERR_FT_BAD, tbl->parse, ln, *pos - 1, "TS f%c", p[*pos - 1]); goto mod; } - - mandoc_msg(MANDOCERR_TBLLAYOUT, tbl->parse, - ln, *pos - 1, NULL); - return(0); } -static int +static void cell(struct tbl_node *tbl, struct tbl_row *rp, int ln, const char *p, int *pos) { - int vert, i; + int i; enum tbl_cellt c; - /* Handle vertical lines. */ + /* Handle leading vertical lines */ - for (vert = 0; '|' == p[*pos]; ++*pos) - vert++; - while (' ' == p[*pos]) + while (p[*pos] == ' ' || p[*pos] == '\t' || p[*pos] == '|') { + if (p[*pos] == '|') { + if (rp->vert < 2) + rp->vert++; + else + mandoc_msg(MANDOCERR_TBLLAYOUT_VERT, + tbl->parse, ln, *pos, NULL); + } (*pos)++; + } - /* Handle trailing vertical lines */ +again: + while (p[*pos] == ' ' || p[*pos] == '\t') + (*pos)++; - if ('.' == p[*pos] || '\0' == p[*pos]) { - rp->vert = vert; - return(1); - } + if (p[*pos] == '.' || p[*pos] == '\0') + return; /* Parse the column position (`c', `l', `r', ...). */ @@ -241,77 +221,44 @@ cell(struct tbl_node *tbl, struct tbl_row *rp, if (tolower((unsigned char)p[*pos]) == keys[i].name) break; - if (KEYS_MAX == i) { - mandoc_msg(MANDOCERR_TBLLAYOUT, tbl->parse, - ln, *pos, NULL); - return(0); + if (i == KEYS_MAX) { + mandoc_vmsg(MANDOCERR_TBLLAYOUT_CHAR, tbl->parse, + ln, *pos, "%c", p[*pos]); + (*pos)++; + goto again; } - c = keys[i].key; - /* - * If a span cell is found first, raise a warning and abort the - * parse. If a span cell is found and the last layout element - * isn't a "normal" layout, bail. - * - * FIXME: recover from this somehow? - */ - - if (TBL_CELL_SPAN == c) { - if (NULL == rp->first) { - mandoc_msg(MANDOCERR_TBLLAYOUT, tbl->parse, - ln, *pos, NULL); - return(0); - } else if (rp->last) - switch (rp->last->pos) { - case TBL_CELL_HORIZ: - /* FALLTHROUGH */ - case TBL_CELL_DHORIZ: - mandoc_msg(MANDOCERR_TBLLAYOUT, - tbl->parse, ln, *pos, NULL); - return(0); - default: - break; - } - } - - /* - * If a vertical spanner is found, we may not be in the first - * row. - */ + /* Special cases of spanners. */ - if (TBL_CELL_DOWN == c && rp == tbl->first_row) { - mandoc_msg(MANDOCERR_TBLLAYOUT, tbl->parse, ln, *pos, NULL); - return(0); - } + if (c == TBL_CELL_SPAN) { + if (rp->last == NULL) + mandoc_msg(MANDOCERR_TBLLAYOUT_SPAN, + tbl->parse, ln, *pos, NULL); + else if (rp->last->pos == TBL_CELL_HORIZ || + rp->last->pos == TBL_CELL_DHORIZ) + c = rp->last->pos; + } else if (c == TBL_CELL_DOWN && rp == tbl->first_row) + mandoc_msg(MANDOCERR_TBLLAYOUT_DOWN, + tbl->parse, ln, *pos, NULL); (*pos)++; - /* Disallow adjacent spacers. */ - - if (vert > 2) { - mandoc_msg(MANDOCERR_TBLLAYOUT, tbl->parse, ln, *pos - 1, NULL); - return(0); - } - /* Allocate cell then parse its modifiers. */ - return(mods(tbl, cell_alloc(tbl, rp, c, vert), ln, p, pos)); + mods(tbl, cell_alloc(tbl, rp, c), ln, p, pos); } -int -tbl_layout(struct tbl_node *tbl, int ln, const char *p) +void +tbl_layout(struct tbl_node *tbl, int ln, const char *p, int pos) { struct tbl_row *rp; - int pos; - pos = 0; rp = NULL; - for (;;) { /* Skip whitespace before and after each cell. */ - while (isspace((unsigned char)p[pos])) + while (p[pos] == ' ' || p[pos] == '\t') pos++; switch (p[pos]) { @@ -320,74 +267,92 @@ tbl_layout(struct tbl_node *tbl, int ln, const char *p) rp = NULL; continue; case '\0': /* Next row on next input line. */ - return(1); + return; case '.': /* End of layout. */ pos++; tbl->part = TBL_PART_DATA; - if (tbl->first_row != NULL) - return(1); - mandoc_msg(MANDOCERR_TBLNOLAYOUT, - tbl->parse, ln, pos, NULL); - rp = mandoc_calloc(1, sizeof(*rp)); - cell_alloc(tbl, rp, TBL_CELL_LEFT, 0); - tbl->first_row = tbl->last_row = rp; - return(1); + + /* + * When the layout is completely empty, + * default to one left-justified column. + */ + + if (tbl->first_row == NULL) { + tbl->first_row = tbl->last_row = + mandoc_calloc(1, sizeof(*rp)); + } + if (tbl->first_row->first == NULL) { + mandoc_msg(MANDOCERR_TBLLAYOUT_NONE, + tbl->parse, ln, pos, NULL); + cell_alloc(tbl, tbl->first_row, + TBL_CELL_LEFT); + return; + } + + /* + * Search for the widest line + * along the left and right margins. + */ + + for (rp = tbl->first_row; rp; rp = rp->next) { + if (tbl->opts.lvert < rp->vert) + tbl->opts.lvert = rp->vert; + if (rp->last != NULL && + rp->last->col + 1 == tbl->opts.cols && + tbl->opts.rvert < rp->last->vert) + tbl->opts.rvert = rp->last->vert; + + /* If the last line is empty, drop it. */ + + if (rp->next != NULL && + rp->next->first == NULL) { + free(rp->next); + rp->next = NULL; + } + } + return; default: /* Cell. */ break; } - if (rp == NULL) { /* First cell on this line. */ - rp = mandoc_calloc(1, sizeof(*rp)); - if (tbl->last_row) - tbl->last_row->next = rp; - else - tbl->first_row = rp; - tbl->last_row = rp; + /* + * If the last line had at least one cell, + * start a new one; otherwise, continue it. + */ + + if (rp == NULL) { + if (tbl->last_row == NULL || + tbl->last_row->first != NULL) { + rp = mandoc_calloc(1, sizeof(*rp)); + if (tbl->last_row) + tbl->last_row->next = rp; + else + tbl->first_row = rp; + tbl->last_row = rp; + } else + rp = tbl->last_row; } - if ( ! cell(tbl, rp, ln, p, &pos)) - return(1); + cell(tbl, rp, ln, p, &pos); } } static struct tbl_cell * -cell_alloc(struct tbl_node *tbl, struct tbl_row *rp, enum tbl_cellt pos, - int vert) +cell_alloc(struct tbl_node *tbl, struct tbl_row *rp, enum tbl_cellt pos) { struct tbl_cell *p, *pp; - struct tbl_head *h, *hp; - p = mandoc_calloc(1, sizeof(struct tbl_cell)); + p = mandoc_calloc(1, sizeof(*p)); + p->pos = pos; - if (NULL != (pp = rp->last)) { + if ((pp = rp->last) != NULL) { pp->next = p; - h = pp->head->next; - } else { + p->col = pp->col + 1; + } else rp->first = p; - h = tbl->first_head; - } rp->last = p; - p->pos = pos; - p->vert = vert; - - /* Re-use header. */ - - if (h) { - p->head = h; - return(p); - } - - hp = mandoc_calloc(1, sizeof(struct tbl_head)); - hp->ident = tbl->opts.cols++; - hp->vert = vert; - - if (tbl->last_head) { - hp->prev = tbl->last_head; - tbl->last_head->next = hp; - } else - tbl->first_head = hp; - tbl->last_head = hp; + if (tbl->opts.cols <= p->col) + tbl->opts.cols = p->col + 1; - p->head = hp; return(p); } diff --git a/contrib/mdocml/tbl_opts.c b/contrib/mdocml/tbl_opts.c index d5ad42f73e5e..c012a3c88545 100644 --- a/contrib/mdocml/tbl_opts.c +++ b/contrib/mdocml/tbl_opts.c @@ -1,6 +1,7 @@ -/* $Id: tbl_opts.c,v 1.15 2014/11/26 17:51:55 schwarze Exp $ */ +/* $Id: tbl_opts.c,v 1.20 2015/01/28 17:32:07 schwarze Exp $ */ /* * Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> + * Copyright (c) 2015 Ingo Schwarze <schwarze@openbsd.org> * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -27,245 +28,147 @@ #include "libmandoc.h" #include "libroff.h" -enum tbl_ident { - KEY_CENTRE = 0, - KEY_DELIM, - KEY_EXPAND, - KEY_BOX, - KEY_DBOX, - KEY_ALLBOX, - KEY_TAB, - KEY_LINESIZE, - KEY_NOKEEP, - KEY_DPOINT, - KEY_NOSPACE, - KEY_FRAME, - KEY_DFRAME, - KEY_MAX -}; +#define KEY_DPOINT 0 +#define KEY_DELIM 1 +#define KEY_LINESIZE 2 +#define KEY_TAB 3 struct tbl_phrase { const char *name; int key; - enum tbl_ident ident; }; -/* Handle Commonwealth/American spellings. */ -#define KEY_MAXKEYS 14 - -/* Maximum length of key name string. */ -#define KEY_MAXNAME 13 - -/* Maximum length of key number size. */ -#define KEY_MAXNUMSZ 10 - -static const struct tbl_phrase keys[KEY_MAXKEYS] = { - { "center", TBL_OPT_CENTRE, KEY_CENTRE}, - { "centre", TBL_OPT_CENTRE, KEY_CENTRE}, - { "delim", 0, KEY_DELIM}, - { "expand", TBL_OPT_EXPAND, KEY_EXPAND}, - { "box", TBL_OPT_BOX, KEY_BOX}, - { "doublebox", TBL_OPT_DBOX, KEY_DBOX}, - { "allbox", TBL_OPT_ALLBOX, KEY_ALLBOX}, - { "frame", TBL_OPT_BOX, KEY_FRAME}, - { "doubleframe", TBL_OPT_DBOX, KEY_DFRAME}, - { "tab", 0, KEY_TAB}, - { "linesize", 0, KEY_LINESIZE}, - { "nokeep", TBL_OPT_NOKEEP, KEY_NOKEEP}, - { "decimalpoint", 0, KEY_DPOINT}, - { "nospaces", TBL_OPT_NOSPACE, KEY_NOSPACE}, +static const struct tbl_phrase keys[] = { + {"decimalpoint", 0}, + {"delim", 0}, + {"linesize", 0}, + {"tab", 0}, + {"allbox", TBL_OPT_ALLBOX | TBL_OPT_BOX}, + {"box", TBL_OPT_BOX}, + {"frame", TBL_OPT_BOX}, + {"center", TBL_OPT_CENTRE}, + {"centre", TBL_OPT_CENTRE}, + {"doublebox", TBL_OPT_DBOX}, + {"doubleframe", TBL_OPT_DBOX}, + {"expand", TBL_OPT_EXPAND}, + {"nokeep", TBL_OPT_NOKEEP}, + {"nospaces", TBL_OPT_NOSPACE}, + {"nowarn", TBL_OPT_NOWARN}, }; -static int arg(struct tbl_node *, int, - const char *, int *, enum tbl_ident); -static void opt(struct tbl_node *, int, - const char *, int *); +#define KEY_MAXKEYS ((int)(sizeof(keys)/sizeof(keys[0]))) +static void arg(struct tbl_node *, int, const char *, int *, int); -static int -arg(struct tbl_node *tbl, int ln, const char *p, int *pos, enum tbl_ident key) + +static void +arg(struct tbl_node *tbl, int ln, const char *p, int *pos, int key) { - int i; - char buf[KEY_MAXNUMSZ]; + int len, want; - while (isspace((unsigned char)p[*pos])) + while (p[*pos] == ' ' || p[*pos] == '\t') (*pos)++; - /* Arguments always begin with a parenthesis. */ + /* Arguments are enclosed in parentheses. */ - if ('(' != p[*pos]) { - mandoc_msg(MANDOCERR_TBL, tbl->parse, - ln, *pos, NULL); - return(0); + len = 0; + if (p[*pos] == '(') { + (*pos)++; + while (p[*pos + len] != ')') + len++; } - (*pos)++; - - /* - * The arguments can be ANY value, so we can't just stop at the - * next close parenthesis (the argument can be a closed - * parenthesis itself). - */ - switch (key) { case KEY_DELIM: - if ('\0' == p[(*pos)++]) { - mandoc_msg(MANDOCERR_TBL, tbl->parse, - ln, *pos - 1, NULL); - return(0); - } - - if ('\0' == p[(*pos)++]) { - mandoc_msg(MANDOCERR_TBL, tbl->parse, - ln, *pos - 1, NULL); - return(0); - } + mandoc_vmsg(MANDOCERR_TBLOPT_EQN, tbl->parse, + ln, *pos, "%.*s", len, p + *pos); + want = 2; break; case KEY_TAB: - if ('\0' != (tbl->opts.tab = p[(*pos)++])) - break; - - mandoc_msg(MANDOCERR_TBL, tbl->parse, - ln, *pos - 1, NULL); - return(0); + want = 1; + if (len == want) + tbl->opts.tab = p[*pos]; + break; case KEY_LINESIZE: - for (i = 0; i < KEY_MAXNUMSZ && p[*pos]; i++, (*pos)++) { - buf[i] = p[*pos]; - if ( ! isdigit((unsigned char)buf[i])) - break; - } - - if (i < KEY_MAXNUMSZ) { - buf[i] = '\0'; - tbl->opts.linesize = atoi(buf); - break; - } - - mandoc_msg(MANDOCERR_TBL, tbl->parse, ln, *pos, NULL); - return(0); + want = 0; + break; case KEY_DPOINT: - if ('\0' != (tbl->opts.decimal = p[(*pos)++])) - break; - - mandoc_msg(MANDOCERR_TBL, tbl->parse, - ln, *pos - 1, NULL); - return(0); + want = 1; + if (len == want) + tbl->opts.decimal = p[*pos]; + break; default: abort(); /* NOTREACHED */ } - /* End with a close parenthesis. */ - - if (')' == p[(*pos)++]) - return(1); + if (len == 0) + mandoc_msg(MANDOCERR_TBLOPT_NOARG, + tbl->parse, ln, *pos, keys[key].name); + else if (want && len != want) + mandoc_vmsg(MANDOCERR_TBLOPT_ARGSZ, + tbl->parse, ln, *pos, "%s want %d have %d", + keys[key].name, want, len); - mandoc_msg(MANDOCERR_TBL, tbl->parse, ln, *pos - 1, NULL); - return(0); + *pos += len; + if (p[*pos] == ')') + (*pos)++; } -static void -opt(struct tbl_node *tbl, int ln, const char *p, int *pos) +/* + * Parse one line of options up to the semicolon. + * Each option can be preceded by blanks and/or commas, + * and some options are followed by arguments. + */ +void +tbl_option(struct tbl_node *tbl, int ln, const char *p, int *offs) { - int i, sv; - char buf[KEY_MAXNAME]; + int i, pos, len; - /* - * Parse individual options from the stream as surrounded by - * this goto. Each pass through the routine parses out a single - * option and registers it. Option arguments are processed in - * the arg() function. - */ + pos = *offs; + for (;;) { + while (p[pos] == ' ' || p[pos] == '\t' || p[pos] == ',') + pos++; -again: /* - * EBNF describing this section: - * - * options ::= option_list [:space:]* [;][\n] - * option_list ::= option option_tail - * option_tail ::= [,:space:]+ option_list | - * ::= epsilon - * option ::= [:alpha:]+ args - * args ::= [:space:]* [(] [:alpha:]+ [)] - */ - - while (isspace((unsigned char)p[*pos])) - (*pos)++; - - /* Safe exit point. */ - - if (';' == p[*pos]) - return; - - /* Copy up to first non-alpha character. */ - - for (sv = *pos, i = 0; i < KEY_MAXNAME; i++, (*pos)++) { - buf[i] = (char)tolower((unsigned char)p[*pos]); - if ( ! isalpha((unsigned char)buf[i])) - break; - } + if (p[pos] == ';') { + *offs = pos + 1; + return; + } - /* Exit if buffer is empty (or overrun). */ + /* Parse one option name. */ - if (KEY_MAXNAME == i || 0 == i) { - mandoc_msg(MANDOCERR_TBL, tbl->parse, ln, *pos, NULL); - return; - } + len = 0; + while (isalpha((unsigned char)p[pos + len])) + len++; - buf[i] = '\0'; + if (len == 0) { + mandoc_vmsg(MANDOCERR_TBLOPT_ALPHA, + tbl->parse, ln, pos, "%c", p[pos]); + pos++; + continue; + } - while (isspace((unsigned char)p[*pos]) || p[*pos] == ',') - (*pos)++; + /* Look up the option name. */ - /* - * Look through all of the available keys to find one that - * matches the input. FIXME: hashtable this. - */ + i = 0; + while (i < KEY_MAXKEYS && + (strncasecmp(p + pos, keys[i].name, len) || + keys[i].name[len] != '\0')) + i++; - for (i = 0; i < KEY_MAXKEYS; i++) { - if (strcmp(buf, keys[i].name)) + if (i == KEY_MAXKEYS) { + mandoc_vmsg(MANDOCERR_TBLOPT_BAD, tbl->parse, + ln, pos, "%.*s", len, p + pos); + pos += len; continue; + } - /* - * Note: this is more difficult to recover from, as we - * can be anywhere in the option sequence and it's - * harder to jump to the next. Meanwhile, just bail out - * of the sequence altogether. - */ + /* Handle the option. */ + pos += len; if (keys[i].key) tbl->opts.opts |= keys[i].key; - else if ( ! arg(tbl, ln, p, pos, keys[i].ident)) - return; - - break; + else + arg(tbl, ln, p, &pos, i); } - - /* - * Allow us to recover from bad options by continuing to another - * parse sequence. - */ - - if (KEY_MAXKEYS == i) - mandoc_msg(MANDOCERR_TBLOPT, tbl->parse, ln, sv, NULL); - - goto again; - /* NOTREACHED */ -} - -int -tbl_option(struct tbl_node *tbl, int ln, const char *p) -{ - int pos; - - /* - * Table options are always on just one line, so automatically - * switch into the next input mode here. - */ - tbl->part = TBL_PART_LAYOUT; - - pos = 0; - opt(tbl, ln, p, &pos); - - /* Always succeed. */ - return(1); } diff --git a/contrib/mdocml/tbl_term.c b/contrib/mdocml/tbl_term.c index 0275b1a2a670..a6354b51c4ea 100644 --- a/contrib/mdocml/tbl_term.c +++ b/contrib/mdocml/tbl_term.c @@ -1,7 +1,7 @@ -/* $Id: tbl_term.c,v 1.31 2014/10/14 18:18:05 schwarze Exp $ */ +/* $Id: tbl_term.c,v 1.38 2015/01/31 00:12:41 schwarze Exp $ */ /* * Copyright (c) 2009, 2011 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2011, 2012, 2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2011, 2012, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -34,15 +34,12 @@ static void tbl_char(struct termp *, char, size_t); static void tbl_data(struct termp *, const struct tbl_opts *, const struct tbl_dat *, const struct roffcol *); -static size_t tbl_rulewidth(struct termp *, const struct tbl_head *); -static void tbl_hframe(struct termp *, const struct tbl_span *, int); static void tbl_literal(struct termp *, const struct tbl_dat *, const struct roffcol *); static void tbl_number(struct termp *, const struct tbl_opts *, const struct tbl_dat *, const struct roffcol *); -static void tbl_hrule(struct termp *, const struct tbl_span *); -static void tbl_vrule(struct termp *, const struct tbl_head *); +static void tbl_hrule(struct termp *, const struct tbl_span *, int); static void tbl_word(struct termp *, const struct tbl_dat *); @@ -63,11 +60,11 @@ term_tbl_len(size_t sz, void *arg) void term_tbl(struct termp *tp, const struct tbl_span *sp) { - const struct tbl_head *hp; + const struct tbl_cell *cp; const struct tbl_dat *dp; - struct roffcol *col; - int spans; - size_t rmargin, maxrmargin; + static size_t offset; + size_t rmargin, maxrmargin, tsz; + int ic, horiz, spans, vert; rmargin = tp->rmargin; maxrmargin = tp->maxrmargin; @@ -84,7 +81,7 @@ term_tbl(struct termp *tp, const struct tbl_span *sp) * calculate the table widths and decimal positions. */ - if (TBL_SPAN_FIRST & sp->flags) { + if (tp->tbl.cols == NULL) { term_flushln(tp); tp->tbl.len = term_tbl_len; @@ -92,79 +89,99 @@ term_tbl(struct termp *tp, const struct tbl_span *sp) tp->tbl.arg = tp; tblcalc(&tp->tbl, sp, rmargin - tp->offset); - } - /* Horizontal frame at the start of boxed tables. */ + /* Center the table as a whole. */ + + offset = tp->offset; + if (sp->opts->opts & TBL_OPT_CENTRE) { + tsz = sp->opts->opts & (TBL_OPT_BOX | TBL_OPT_DBOX) + ? 2 : !!sp->opts->lvert + !!sp->opts->rvert; + for (ic = 0; ic < sp->opts->cols; ic++) + tsz += tp->tbl.cols[ic].width + 3; + tsz -= 3; + if (offset + tsz > rmargin) + tsz -= 1; + tp->offset = (offset + rmargin > tsz) ? + (offset + rmargin - tsz) / 2 : 0; + } + + /* Horizontal frame at the start of boxed tables. */ - if (TBL_SPAN_FIRST & sp->flags) { - if (TBL_OPT_DBOX & sp->opts->opts) - tbl_hframe(tp, sp, 1); - if (TBL_OPT_DBOX & sp->opts->opts || - TBL_OPT_BOX & sp->opts->opts) - tbl_hframe(tp, sp, 0); + if (sp->opts->opts & TBL_OPT_DBOX) + tbl_hrule(tp, sp, 2); + if (sp->opts->opts & (TBL_OPT_DBOX | TBL_OPT_BOX)) + tbl_hrule(tp, sp, 1); } /* Vertical frame at the start of each row. */ - if ((TBL_OPT_BOX | TBL_OPT_DBOX) & sp->opts->opts || - (sp->head != NULL && sp->head->vert)) - term_word(tp, TBL_SPAN_HORIZ == sp->pos || - TBL_SPAN_DHORIZ == sp->pos ? "+" : "|"); + horiz = sp->pos == TBL_SPAN_HORIZ || sp->pos == TBL_SPAN_DHORIZ; + + if (sp->layout->vert || + (sp->prev != NULL && sp->prev->layout->vert) || + sp->opts->opts & (TBL_OPT_BOX | TBL_OPT_DBOX)) + term_word(tp, horiz ? "+" : "|"); + else if (sp->opts->lvert) + tbl_char(tp, horiz ? '-' : ASCII_NBRSP, 1); /* * Now print the actual data itself depending on the span type. - * Spanner spans get a horizontal rule; data spanners have their - * data printed by matching data to header. + * Match data cells to column numbers. */ - switch (sp->pos) { - case TBL_SPAN_HORIZ: - /* FALLTHROUGH */ - case TBL_SPAN_DHORIZ: - tbl_hrule(tp, sp); - break; - case TBL_SPAN_DATA: - /* Iterate over template headers. */ + if (sp->pos == TBL_SPAN_DATA) { + cp = sp->layout->first; dp = sp->first; spans = 0; - for (hp = sp->head; hp; hp = hp->next) { + for (ic = 0; ic < sp->opts->cols; ic++) { /* - * If the current data header is invoked during - * a spanner ("spans" > 0), don't emit anything - * at all. + * Remeber whether we need a vertical bar + * after this cell. */ - if (--spans >= 0) - continue; - - /* Separate columns. */ + vert = cp == NULL ? 0 : cp->vert; - if (NULL != hp->prev) - tbl_vrule(tp, hp); + /* + * Print the data and advance to the next cell. + */ - col = &tp->tbl.cols[hp->ident]; - tbl_data(tp, sp->opts, dp, col); + if (spans == 0) { + tbl_data(tp, sp->opts, dp, tp->tbl.cols + ic); + if (dp != NULL) { + spans = dp->spans; + dp = dp->next; + } + } else + spans--; + if (cp != NULL) + cp = cp->next; /* - * Go to the next data cell and assign the - * number of subsequent spans, if applicable. + * Separate columns, except in the middle + * of spans and after the last cell. */ - if (dp) { - spans = dp->spans; - dp = dp->next; - } + if (ic + 1 == sp->opts->cols || spans) + continue; + + tbl_char(tp, ASCII_NBRSP, 1); + if (vert > 0) + tbl_char(tp, '|', vert); + if (vert < 2) + tbl_char(tp, ASCII_NBRSP, 2 - vert); } - break; - } + } else if (horiz) + tbl_hrule(tp, sp, 0); /* Vertical frame at the end of each row. */ - if ((TBL_OPT_BOX | TBL_OPT_DBOX) & sp->opts->opts || - sp->layout->vert) - term_word(tp, TBL_SPAN_HORIZ == sp->pos || - TBL_SPAN_DHORIZ == sp->pos ? "+" : " |"); + if (sp->layout->last->vert || + (sp->prev != NULL && sp->prev->layout->last->vert) || + (sp->opts->opts & (TBL_OPT_BOX | TBL_OPT_DBOX))) + term_word(tp, horiz ? "+" : " |"); + else if (sp->opts->rvert) + tbl_char(tp, horiz ? '-' : ASCII_NBRSP, 1); term_flushln(tp); /* @@ -172,88 +189,67 @@ term_tbl(struct termp *tp, const struct tbl_span *sp) * existing table configuration and set it to NULL. */ - if (TBL_SPAN_LAST & sp->flags) { - if (TBL_OPT_DBOX & sp->opts->opts || - TBL_OPT_BOX & sp->opts->opts) { - tbl_hframe(tp, sp, 0); + if (sp->next == NULL) { + if (sp->opts->opts & (TBL_OPT_DBOX | TBL_OPT_BOX)) { + tbl_hrule(tp, sp, 1); tp->skipvsp = 1; } - if (TBL_OPT_DBOX & sp->opts->opts) { - tbl_hframe(tp, sp, 1); + if (sp->opts->opts & TBL_OPT_DBOX) { + tbl_hrule(tp, sp, 2); tp->skipvsp = 2; } assert(tp->tbl.cols); free(tp->tbl.cols); tp->tbl.cols = NULL; + tp->offset = offset; } tp->flags &= ~TERMP_NONOSPACE; tp->rmargin = rmargin; tp->maxrmargin = maxrmargin; - -} - -/* - * Horizontal rules extend across the entire table. - * Calculate the width by iterating over columns. - */ -static size_t -tbl_rulewidth(struct termp *tp, const struct tbl_head *hp) -{ - size_t width; - - width = tp->tbl.cols[hp->ident].width; - - /* Account for leading blanks. */ - if (hp->prev) - width += 2 - hp->vert; - - /* Account for trailing blank. */ - width++; - - return(width); } /* - * Rules inside the table can be single or double - * and have crossings with vertical rules marked with pluses. + * Kinds of horizontal rulers: + * 0: inside the table (single or double line with crossings) + * 1: inner frame (single line with crossings and ends) + * 2: outer frame (single line without crossings with ends) */ static void -tbl_hrule(struct termp *tp, const struct tbl_span *sp) +tbl_hrule(struct termp *tp, const struct tbl_span *sp, int kind) { - const struct tbl_head *hp; - char c; - - c = '-'; - if (TBL_SPAN_DHORIZ == sp->pos) - c = '='; - - for (hp = sp->head; hp; hp = hp->next) { - if (hp->prev && hp->vert) - tbl_char(tp, '+', hp->vert); - tbl_char(tp, c, tbl_rulewidth(tp, hp)); + const struct tbl_cell *c1, *c2; + int vert; + char line, cross; + + line = (kind == 0 && TBL_SPAN_DHORIZ == sp->pos) ? '=' : '-'; + cross = (kind < 2) ? '+' : '-'; + + if (kind) + term_word(tp, "+"); + c1 = sp->layout->first; + c2 = sp->prev == NULL ? NULL : sp->prev->layout->first; + if (c2 == c1) + c2 = NULL; + for (;;) { + tbl_char(tp, line, tp->tbl.cols[c1->col].width + 1); + vert = c1->vert; + if ((c1 = c1->next) == NULL) + break; + if (c2 != NULL) { + if (vert < c2->vert) + vert = c2->vert; + c2 = c2->next; + } + if (vert) + tbl_char(tp, cross, vert); + if (vert < 2) + tbl_char(tp, line, 2 - vert); } -} - -/* - * Rules above and below the table are always single - * and have an additional plus at the beginning and end. - * For double frames, this function is called twice, - * and the outer one does not have crossings. - */ -static void -tbl_hframe(struct termp *tp, const struct tbl_span *sp, int outer) -{ - const struct tbl_head *hp; - - term_word(tp, "+"); - for (hp = sp->head; hp; hp = hp->next) { - if (hp->prev && hp->vert) - tbl_char(tp, (outer ? '-' : '+'), hp->vert); - tbl_char(tp, '-', tbl_rulewidth(tp, hp)); + if (kind) { + term_word(tp, "+"); + term_flushln(tp); } - term_word(tp, "+"); - term_flushln(tp); } static void @@ -262,11 +258,10 @@ tbl_data(struct termp *tp, const struct tbl_opts *opts, const struct roffcol *col) { - if (NULL == dp) { + if (dp == NULL) { tbl_char(tp, ASCII_NBRSP, col->width); return; } - assert(dp->layout); switch (dp->pos) { case TBL_DATA_NONE: @@ -315,17 +310,6 @@ tbl_data(struct termp *tp, const struct tbl_opts *opts, } static void -tbl_vrule(struct termp *tp, const struct tbl_head *hp) -{ - - tbl_char(tp, ASCII_NBRSP, 1); - if (0 < hp->vert) - tbl_char(tp, '|', hp->vert); - if (2 > hp->vert) - tbl_char(tp, ASCII_NBRSP, 2 - hp->vert); -} - -static void tbl_char(struct termp *tp, char c, size_t len) { size_t i, sz; @@ -344,17 +328,16 @@ static void tbl_literal(struct termp *tp, const struct tbl_dat *dp, const struct roffcol *col) { - struct tbl_head *hp; - size_t width, len, padl, padr; - int spans; + size_t len, padl, padr, width; + int ic, spans; assert(dp->string); len = term_strlen(tp, dp->string); - - hp = dp->layout->head->next; width = col->width; - for (spans = dp->spans; spans--; hp = hp->next) - width += tp->tbl.cols[hp->ident].width + 3; + ic = dp->layout->col; + spans = dp->spans; + while (spans--) + width += tp->tbl.cols[++ic].width + 3; padr = width > len ? width - len : 0; padl = 0; @@ -407,8 +390,7 @@ tbl_number(struct termp *tp, const struct tbl_opts *opts, psz = term_strlen(tp, buf); - if (NULL != (cp = strrchr(dp->string, opts->decimal))) { - buf[1] = '\0'; + if ((cp = strrchr(dp->string, opts->decimal)) != NULL) { for (ssz = 0, i = 0; cp != &dp->string[i]; i++) { buf[0] = dp->string[i]; ssz += term_strlen(tp, buf); @@ -417,9 +399,13 @@ tbl_number(struct termp *tp, const struct tbl_opts *opts, } else d = sz + psz; - padl = col->decimal - d; - - tbl_char(tp, ASCII_NBRSP, padl); + if (col->decimal > d && col->width > sz) { + padl = col->decimal - d; + if (padl + sz > col->width) + padl = col->width - sz; + tbl_char(tp, ASCII_NBRSP, padl); + } else + padl = 0; tbl_word(tp, dp); if (col->width > sz + padl) tbl_char(tp, ASCII_NBRSP, col->width - sz - padl); @@ -428,9 +414,9 @@ tbl_number(struct termp *tp, const struct tbl_opts *opts, static void tbl_word(struct termp *tp, const struct tbl_dat *dp) { - const void *prev_font; + int prev_font; - prev_font = term_fontq(tp); + prev_font = tp->fonti; if (dp->layout->flags & TBL_CELL_BOLD) term_fontpush(tp, TERMFONT_BOLD); else if (dp->layout->flags & TBL_CELL_ITALIC) diff --git a/contrib/mdocml/term.c b/contrib/mdocml/term.c index 33f8f90027ac..75c12f4af21e 100644 --- a/contrib/mdocml/term.c +++ b/contrib/mdocml/term.c @@ -1,7 +1,7 @@ -/* $Id: term.c,v 1.237 2014/12/02 10:08:06 schwarze Exp $ */ +/* $Id: term.c,v 1.244 2015/01/31 00:12:41 schwarze Exp $ */ /* * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2010-2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2010-2015 Ingo Schwarze <schwarze@openbsd.org> * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -43,6 +43,7 @@ term_free(struct termp *p) { free(p->buf); + free(p->fontq); free(p); } @@ -100,7 +101,6 @@ term_flushln(struct termp *p) size_t j; /* temporary loop index for p->buf */ size_t jhy; /* last hyph before overflow w/r/t j */ size_t maxvis; /* output position of visible boundary */ - size_t rmargin; /* the rightmost of the two margins */ /* * First, establish the maximum columns of "visible" content. @@ -113,8 +113,7 @@ term_flushln(struct termp *p) * is negative, it gets sign extended. Subtracting that * very large size_t effectively adds a small number to dv. */ - rmargin = p->rmargin > p->offset ? p->rmargin : p->offset; - dv = p->rmargin - p->offset; + dv = p->rmargin > p->offset ? p->rmargin - p->offset : 0; maxvis = (int)dv > p->overstep ? dv - (size_t)p->overstep : 0; if (p->flags & TERMP_NOBREAK) { @@ -192,8 +191,9 @@ term_flushln(struct termp *p) (*p->endline)(p); p->viscol = 0; if (TERMP_BRIND & p->flags) { - vbl = rmargin; - vend += rmargin - p->offset; + vbl = p->rmargin; + vend += p->rmargin; + vend -= p->offset; } else vbl = p->offset; @@ -273,7 +273,7 @@ term_flushln(struct termp *p) } if (TERMP_HANG & p->flags) { - p->overstep = (int)(vis - maxvis + + p->overstep += (int)(p->offset + vis - p->rmargin + p->trailspace * (*p->width)(p, ' ')); /* @@ -329,6 +329,7 @@ term_vspace(struct termp *p) (*p->endline)(p); } +/* Swap current and previous font; for \fP and .ft P */ void term_fontlast(struct termp *p) { @@ -339,6 +340,7 @@ term_fontlast(struct termp *p) p->fontq[p->fonti] = f; } +/* Set font, save current, discard previous; for \f, .ft, .B etc. */ void term_fontrepl(struct termp *p, enum termfont f) { @@ -347,38 +349,31 @@ term_fontrepl(struct termp *p, enum termfont f) p->fontq[p->fonti] = f; } +/* Set font, save previous. */ void term_fontpush(struct termp *p, enum termfont f) { - assert(p->fonti + 1 < 10); p->fontl = p->fontq[p->fonti]; - p->fontq[++p->fonti] = f; -} - -const void * -term_fontq(struct termp *p) -{ - - return(&p->fontq[p->fonti]); -} - -enum termfont -term_fonttop(struct termp *p) -{ - - return(p->fontq[p->fonti]); + if (++p->fonti == p->fontsz) { + p->fontsz += 8; + p->fontq = mandoc_reallocarray(p->fontq, + p->fontsz, sizeof(enum termfont *)); + } + p->fontq[p->fonti] = f; } +/* Flush to make the saved pointer current again. */ void -term_fontpopq(struct termp *p, const void *key) +term_fontpopq(struct termp *p, int i) { - while (p->fonti >= 0 && key < (void *)(p->fontq + p->fonti)) - p->fonti--; - assert(p->fonti >= 0); + assert(i >= 0); + if (p->fonti > i) + p->fonti = i; } +/* Pop one font off the stack. */ void term_fontpop(struct termp *p) { @@ -492,6 +487,17 @@ term_word(struct termp *p, const char *word) case ESCAPE_SKIPCHAR: p->flags |= TERMP_SKIPCHAR; continue; + case ESCAPE_OVERSTRIKE: + cp = seq + sz; + while (seq < cp) { + if (*seq == '\\') { + mandoc_escape(&seq, NULL, NULL); + continue; + } + encode1(p, *seq++); + if (seq < cp) + encode(p, "\b", 1); + } default: continue; } @@ -554,7 +560,7 @@ encode1(struct termp *p, int c) if (p->col + 6 >= p->maxcols) adjbuf(p, p->col + 6); - f = term_fonttop(p); + f = p->fontq[p->fonti]; if (TERMFONT_UNDER == f || TERMFONT_BI == f) { p->buf[p->col++] = '_'; @@ -586,7 +592,7 @@ encode(struct termp *p, const char *word, size_t sz) * character by character. */ - if (TERMFONT_NONE == term_fonttop(p)) { + if (p->fontq[p->fonti] == TERMFONT_NONE) { if (p->col + sz >= p->maxcols) adjbuf(p, p->col + sz); for (i = 0; i < sz; i++) @@ -713,6 +719,20 @@ term_strlen(const struct termp *p, const char *cp) case ESCAPE_SKIPCHAR: skip = 1; continue; + case ESCAPE_OVERSTRIKE: + rsz = 0; + rhs = seq + ssz; + while (seq < rhs) { + if (*seq == '\\') { + mandoc_escape(&seq, NULL, NULL); + continue; + } + i = (*p->width)(p, *seq++); + if (rsz < i) + rsz = i; + } + sz += rsz; + continue; default: continue; } @@ -766,47 +786,55 @@ term_strlen(const struct termp *p, const char *cp) return(sz); } -size_t +int term_vspan(const struct termp *p, const struct roffsu *su) { double r; + int ri; switch (su->unit) { + case SCALE_BU: + r = su->scale / 40.0; + break; case SCALE_CM: - r = su->scale * 2.0; + r = su->scale * 6.0 / 2.54; + break; + case SCALE_FS: + r = su->scale * 65536.0 / 40.0; break; case SCALE_IN: r = su->scale * 6.0; break; + case SCALE_MM: + r = su->scale * 0.006; + break; case SCALE_PC: r = su->scale; break; case SCALE_PT: - r = su->scale / 8.0; + r = su->scale / 12.0; break; - case SCALE_MM: - r = su->scale / 1000.0; + case SCALE_EN: + /* FALLTHROUGH */ + case SCALE_EM: + r = su->scale * 0.6; break; case SCALE_VS: r = su->scale; break; default: - r = su->scale - 1.0; - break; + abort(); + /* NOTREACHED */ } - - if (r < 0.0) - r = 0.0; - return((size_t)(r + 0.0005)); + ri = r > 0.0 ? r + 0.4995 : r - 0.4995; + return(ri < 66 ? ri : 1); } -size_t +int term_hspan(const struct termp *p, const struct roffsu *su) { double v; v = (*p->hspan)(p, su); - if (v < 0.0) - v = 0.0; - return((size_t)(v + 0.0005)); + return(v > 0.0 ? v + 0.0005 : v - 0.0005); } diff --git a/contrib/mdocml/term.h b/contrib/mdocml/term.h index 62c6ffe8af89..b65524b610c4 100644 --- a/contrib/mdocml/term.h +++ b/contrib/mdocml/term.h @@ -1,4 +1,4 @@ -/* $Id: term.h,v 1.108 2014/12/02 10:08:06 schwarze Exp $ */ +/* $Id: term.h,v 1.111 2015/01/31 00:12:41 schwarze Exp $ */ /* * Copyright (c) 2008, 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> * Copyright (c) 2011, 2012, 2013, 2014 Ingo Schwarze <schwarze@openbsd.org> @@ -84,7 +84,8 @@ struct termp { enum termenc enc; /* Type of encoding. */ const struct mchars *symtab; /* Character table. */ enum termfont fontl; /* Last font set. */ - enum termfont fontq[10]; /* Symmetric fonts. */ + enum termfont *fontq; /* Symmetric fonts. */ + int fontsz; /* Allocated size of font stack */ int fonti; /* Index of font stack. */ term_margin headf; /* invoked to print head */ term_margin footf; /* invoked to print foot */ @@ -120,18 +121,14 @@ void term_begin(struct termp *, term_margin, void term_end(struct termp *); void term_setwidth(struct termp *, const char *); -size_t term_hspan(const struct termp *, - const struct roffsu *); -size_t term_vspan(const struct termp *, - const struct roffsu *); +int term_hspan(const struct termp *, const struct roffsu *); +int term_vspan(const struct termp *, const struct roffsu *); size_t term_strlen(const struct termp *, const char *); size_t term_len(const struct termp *, size_t); -enum termfont term_fonttop(struct termp *); -const void *term_fontq(struct termp *); void term_fontpush(struct termp *, enum termfont); void term_fontpop(struct termp *); -void term_fontpopq(struct termp *, const void *); +void term_fontpopq(struct termp *, int); void term_fontrepl(struct termp *, enum termfont); void term_fontlast(struct termp *); diff --git a/contrib/mdocml/term_ascii.c b/contrib/mdocml/term_ascii.c index 71d8af4c6c79..4ce4b686c4f5 100644 --- a/contrib/mdocml/term_ascii.c +++ b/contrib/mdocml/term_ascii.c @@ -1,4 +1,4 @@ -/* $Id: term_ascii.c,v 1.40 2014/11/20 13:56:20 schwarze Exp $ */ +/* $Id: term_ascii.c,v 1.43 2015/02/16 14:11:41 schwarze Exp $ */ /* * Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> * Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org> @@ -63,12 +63,17 @@ ascii_init(enum termenc enc, const struct mchars *mchars, char *outopts) const char *toks[5]; char *v; struct termp *p; + const char *errstr; + int num; p = mandoc_calloc(1, sizeof(struct termp)); p->symtab = mchars; p->tabwidth = 5; p->defrmargin = p->lastrmargin = 78; + p->fontq = mandoc_reallocarray(NULL, + (p->fontsz = 8), sizeof(enum termfont)); + p->fontq[0] = p->fontl = TERMFONT_NONE; p->begin = ascii_begin; p->end = ascii_end; @@ -106,10 +111,14 @@ ascii_init(enum termenc enc, const struct mchars *mchars, char *outopts) while (outopts && *outopts) switch (getsubopt(&outopts, UNCONST(toks), &v)) { case 0: - p->defindent = (size_t)atoi(v); + num = strtonum(v, 0, 1000, &errstr); + if (!errstr) + p->defindent = num; break; case 1: - p->defrmargin = (size_t)atoi(v); + num = strtonum(v, 0, 1000, &errstr); + if (!errstr) + p->defrmargin = num; break; case 2: /* @@ -171,6 +180,20 @@ ascii_setwidth(struct termp *p, int iop, size_t width) p->rmargin = p->maxrmargin = p->defrmargin; } +void +ascii_sepline(void *arg) +{ + struct termp *p; + size_t i; + + p = (struct termp *)arg; + putchar('\n'); + for (i = 0; i < p->defrmargin; i++) + putchar('-'); + putchar('\n'); + putchar('\n'); +} + static size_t ascii_width(const struct termp *p, int c) { diff --git a/contrib/mdocml/term_ps.c b/contrib/mdocml/term_ps.c index e3299d70640b..12ca7d67165c 100644 --- a/contrib/mdocml/term_ps.c +++ b/contrib/mdocml/term_ps.c @@ -1,7 +1,7 @@ -/* $Id: term_ps.c,v 1.70 2014/12/01 08:05:52 schwarze Exp $ */ +/* $Id: term_ps.c,v 1.72 2015/01/21 19:40:54 schwarze Exp $ */ /* * Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -60,6 +60,7 @@ struct termp_ps { #define PS_NEWPAGE (1 << 2) /* new page, no words yet */ #define PS_BACKSP (1 << 3) /* last character was backspace */ size_t pscol; /* visible column (AFM units) */ + size_t pscolnext; /* used for overstrike */ size_t psrow; /* visible row (AFM units) */ char *psmarg; /* margin buf */ size_t psmargsz; /* margin buf size */ @@ -540,6 +541,9 @@ pspdf_alloc(const struct mchars *mchars, char *outopts) p = mandoc_calloc(1, sizeof(struct termp)); p->symtab = mchars; p->enc = TERMENC_ASCII; + p->fontq = mandoc_reallocarray(NULL, + (p->fontsz = 8), sizeof(enum termfont)); + p->fontq[0] = p->fontl = TERMFONT_NONE; p->ps = mandoc_calloc(1, sizeof(struct termp_ps)); p->advance = ps_advance; @@ -1069,7 +1073,7 @@ ps_fclose(struct termp *p) static void ps_letter(struct termp *p, int arg) { - size_t savecol; + size_t savecol, wx; char c; c = arg >= 128 || arg <= 0 ? '?' : arg; @@ -1141,7 +1145,30 @@ ps_letter(struct termp *p, int arg) ps_setfont(p, p->ps->nextf); } p->ps->nextf = TERMFONT_NONE; + + /* + * For an overstrike, if a previous character + * was wider, advance to center the new one. + */ + + if (p->ps->pscolnext) { + wx = fonts[p->ps->lastf].gly[(int)p->ps->last-32].wx; + if (p->ps->pscol + wx < p->ps->pscolnext) + p->ps->pscol = (p->ps->pscol + + p->ps->pscolnext - wx) / 2; + } + ps_pletter(p, p->ps->last); + + /* + * For an overstrike, if a previous character + * was wider, advance to the end of the old one. + */ + + if (p->ps->pscol < p->ps->pscolnext) { + ps_pclose(p); + p->ps->pscol = p->ps->pscolnext; + } } /* @@ -1155,13 +1182,19 @@ ps_letter(struct termp *p, int arg) /* * For an overstrike, back up to the previous position. + * If the previous character is wider than any it overstrikes, + * remember the current position, because it might also be + * wider than all that will overstrike it. */ if (savecol != SIZE_MAX) { + if (p->ps->pscolnext < p->ps->pscol) + p->ps->pscolnext = p->ps->pscol; ps_pclose(p); p->ps->pscol = savecol; p->ps->flags &= ~PS_BACKSP; - } + } else + p->ps->pscolnext = 0; } static void diff --git a/contrib/mdocml/test-strtonum.c b/contrib/mdocml/test-strtonum.c new file mode 100644 index 000000000000..ce70dd660513 --- /dev/null +++ b/contrib/mdocml/test-strtonum.c @@ -0,0 +1,42 @@ +/* $Id: test-strtonum.c,v 1.1 2015/02/16 14:56:22 schwarze Exp $ */ +/* + * Copyright (c) 2015 Ingo Schwarze <schwarze@openbsd.org> + * + * Permission to use, copy, modify, and distribute this software for any + * purpose with or without fee is hereby granted, provided that the above + * copyright notice and this permission notice appear in all copies. + * + * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR + * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN + * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF + * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + */ + +#include <stdlib.h> + +int +main(void) +{ + const char *errstr; + + if (strtonum("1", 0, 2, &errstr) != 1) + return(1); + if (errstr != NULL) + return(2); + if (strtonum("1x", 0, 2, &errstr) != 0) + return(3); + if (errstr == NULL) + return(4); + if (strtonum("2", 0, 1, &errstr) != 0) + return(5); + if (errstr == NULL) + return(6); + if (strtonum("0", 1, 2, &errstr) != 0) + return(7); + if (errstr == NULL) + return(8); + return(0); +} diff --git a/contrib/mdocml/tree.c b/contrib/mdocml/tree.c index 4753219c8e7f..a5a7f2c7d232 100644 --- a/contrib/mdocml/tree.c +++ b/contrib/mdocml/tree.c @@ -1,7 +1,7 @@ -/* $Id: tree.c,v 1.60 2014/11/28 05:51:32 schwarze Exp $ */ +/* $Id: tree.c,v 1.62 2015/02/05 00:14:13 schwarze Exp $ */ /* * Copyright (c) 2008, 2009, 2011, 2014 Kristaps Dzonsons <kristaps@bsd.lv> - * Copyright (c) 2013, 2014 Ingo Schwarze <schwarze@openbsd.org> + * Copyright (c) 2013, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above @@ -40,14 +40,14 @@ void tree_mdoc(void *arg, const struct mdoc *mdoc) { - print_mdoc(mdoc_node(mdoc), 0); + print_mdoc(mdoc_node(mdoc)->child, 0); } void tree_man(void *arg, const struct man *man) { - print_man(man_node(man), 0); + print_man(man_node(man)->child, 0); } static void @@ -58,6 +58,9 @@ print_mdoc(const struct mdoc_node *n, int indent) size_t argc; struct mdoc_argv *argv; + if (n == NULL) + return; + argv = NULL; argc = 0; t = p = NULL; @@ -142,7 +145,7 @@ print_mdoc(const struct mdoc_node *n, int indent) print_span(n->span, indent); } else { for (i = 0; i < indent; i++) - putchar('\t'); + putchar(' '); printf("%s (%s)", p, t); @@ -159,16 +162,14 @@ print_mdoc(const struct mdoc_node *n, int indent) putchar(' '); if (MDOC_LINE & n->flags) putchar('*'); - printf("%d:%d", n->line, n->pos + 1); - if (n->lastline != n->line) - printf("-%d", n->lastline); - putchar('\n'); + printf("%d:%d\n", n->line, n->pos + 1); } if (n->eqn) - print_box(n->eqn->root->first, indent + 1); + print_box(n->eqn->root->first, indent + 4); if (n->child) - print_mdoc(n->child, indent + 1); + print_mdoc(n->child, indent + + (n->type == MDOC_BLOCK ? 2 : 4)); if (n->next) print_mdoc(n->next, indent); } @@ -179,6 +180,9 @@ print_man(const struct man_node *n, int indent) const char *p, *t; int i; + if (n == NULL) + return; + t = p = NULL; switch (n->type) { @@ -241,7 +245,7 @@ print_man(const struct man_node *n, int indent) print_span(n->span, indent); } else { for (i = 0; i < indent; i++) - putchar('\t'); + putchar(' '); printf("%s (%s) ", p, t); if (MAN_LINE & n->flags) putchar('*'); @@ -249,9 +253,10 @@ print_man(const struct man_node *n, int indent) } if (n->eqn) - print_box(n->eqn->root->first, indent + 1); + print_box(n->eqn->root->first, indent + 4); if (n->child) - print_man(n->child, indent + 1); + print_man(n->child, indent + + (n->type == MAN_BLOCK ? 2 : 4)); if (n->next) print_man(n->next, indent); } @@ -270,7 +275,7 @@ print_box(const struct eqn_box *ep, int indent) if (NULL == ep) return; for (i = 0; i < indent; i++) - putchar('\t'); + putchar(' '); t = NULL; switch (ep->type) { @@ -318,7 +323,7 @@ print_box(const struct eqn_box *ep, int indent) printf(" args=%zu", ep->args); putchar('\n'); - print_box(ep->first, indent + 1); + print_box(ep->first, indent + 4); print_box(ep->next, indent); } @@ -329,7 +334,7 @@ print_span(const struct tbl_span *sp, int indent) int i; for (i = 0; i < indent; i++) - putchar('\t'); + putchar(' '); switch (sp->pos) { case TBL_SPAN_HORIZ: diff --git a/contrib/netbsd-tests/lib/libc/gen/t_nice.c b/contrib/netbsd-tests/lib/libc/gen/t_nice.c index f4a62e9ac751..7c6d23287dd8 100644 --- a/contrib/netbsd-tests/lib/libc/gen/t_nice.c +++ b/contrib/netbsd-tests/lib/libc/gen/t_nice.c @@ -93,7 +93,11 @@ ATF_TC_HEAD(nice_priority, tc) ATF_TC_BODY(nice_priority, tc) { +#ifdef __FreeBSD__ + int i, pri, pri2, nic; +#else int i, pri, nic; +#endif pid_t pid; int sta; @@ -106,8 +110,10 @@ ATF_TC_BODY(nice_priority, tc) pri = getpriority(PRIO_PROCESS, 0); ATF_REQUIRE(errno == 0); +#ifdef __NetBSD__ if (nic != pri) atf_tc_fail("nice(3) and getpriority(2) conflict"); +#endif /* * Also verify that the nice(3) values @@ -119,10 +125,18 @@ ATF_TC_BODY(nice_priority, tc) if (pid == 0) { errno = 0; +#ifdef __FreeBSD__ pri = getpriority(PRIO_PROCESS, 0); +#else + pri2 = getpriority(PRIO_PROCESS, 0); +#endif ATF_REQUIRE(errno == 0); +#ifdef __FreeBSD__ + if (pri != pri2) +#else if (nic != pri) +#endif _exit(EXIT_FAILURE); _exit(EXIT_SUCCESS); @@ -161,7 +175,11 @@ ATF_TC_HEAD(nice_thread, tc) ATF_TC_BODY(nice_thread, tc) { pthread_t tid[5]; +#ifdef __FreeBSD__ + int pri, rv, val; +#else int rv, val; +#endif size_t i; /* @@ -173,7 +191,12 @@ ATF_TC_BODY(nice_thread, tc) val = nice(i); ATF_REQUIRE(val != -1); +#ifdef __FreeBSD__ + pri = getpriority(PRIO_PROCESS, 0); + rv = pthread_create(&tid[i], NULL, threadfunc, &pri); +#else rv = pthread_create(&tid[i], NULL, threadfunc, &val); +#endif ATF_REQUIRE(rv == 0); rv = pthread_join(tid[i], NULL); |