* doc/as.texinfo (Symbol Names): Don't use obsolete @ctrl macro.

This commit is contained in:
Ian Lance Taylor
1997-03-21 00:19:44 +00:00
parent 9b07de4901
commit 35cfacf0da
2 changed files with 115 additions and 17 deletions

View File

@ -1,3 +1,7 @@
Thu Mar 20 19:18:58 1997 Ian Lance Taylor <ian@cygnus.com>
* doc/as.texinfo (Symbol Names): Don't use obsolete @ctrl macro.
Thu Mar 20 16:49:14 1997 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de> Thu Mar 20 16:49:14 1997 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de>
* config/tc-m68k.c (mri_chip): Replace calls to get_symbol_end by * config/tc-m68k.c (mri_chip): Replace calls to get_symbol_end by

View File

@ -195,7 +195,7 @@ Here is a brief summary of how to invoke @code{@value{AS}}. For details,
@c We don't use deffn and friends for the following because they seem @c We don't use deffn and friends for the following because they seem
@c to be limited to one line for the header. @c to be limited to one line for the header.
@smallexample @smallexample
@value{AS} [ -a[dhlns][=file] ] [ -D ] [ --defsym @var{sym}=@var{val} ] @value{AS} [ -a[cdhlns][=file] ] [ -D ] [ --defsym @var{sym}=@var{val} ]
[ -f ] [ --help ] [ -I @var{dir} ] [ -J ] [ -K ] [ -L ] [ -f ] [ --help ] [ -I @var{dir} ] [ -J ] [ -K ] [ -L ]
[ -o @var{objfile} ] [ -R ] [ --statistics ] [ -v ] [ -version ] [ -o @var{objfile} ] [ -R ] [ --statistics ] [ -v ] [ -version ]
[ --version ] [ -W ] [ -w ] [ -x ] [ -Z ] [ --version ] [ -W ] [ -w ] [ -x ] [ -Z ]
@ -862,7 +862,7 @@ precisely what options it passes to each compilation pass, including the
assembler.) assembler.)
@menu @menu
* a:: -a[dhlns] enable listings * a:: -a[cdhlns] enable listings
* D:: -D for compatibility * D:: -D for compatibility
* f:: -f to work faster * f:: -f to work faster
* I:: -I for .include search path * I:: -I for .include search path
@ -884,9 +884,10 @@ assembler.)
@end menu @end menu
@node a @node a
@section Enable Listings: @code{-a[dhlns]} @section Enable Listings: @code{-a[cdhlns]}
@kindex -a @kindex -a
@kindex -ac
@kindex -ad @kindex -ad
@kindex -ah @kindex -ah
@kindex -al @kindex -al
@ -905,6 +906,11 @@ High-level listings require that a compiler debugging option like
@samp{-g} be used, and that assembly listings (@samp{-al}) be requested @samp{-g} be used, and that assembly listings (@samp{-al}) be requested
also. also.
Use the @samp{-ac} option to omit false conditionals from a listing. Any lines
which are not assembled because of a false @code{.if} (or @code{.ifdef}, or any
other conditional), or a true @code{.if} followed by an @code{.else}, will be
omitted from the listing.
Use the @samp{-ad} option to omit debugging directives from the Use the @samp{-ad} option to omit debugging directives from the
listing. listing.
@ -2324,10 +2330,19 @@ not dictate data to load into it before your program executes. When
your program starts running, all the contents of the bss your program starts running, all the contents of the bss
section are zeroed bytes. section are zeroed bytes.
Addresses in the bss section are allocated with special directives; you The @code{.lcomm} pseudo-op defines a symbol in the bss section; see
may not assemble anything directly into the bss section. Hence there @ref{Lcomm,,@code{.lcomm}}.
are no bss subsections. @xref{Comm,,@code{.comm}},
@pxref{Lcomm,,@code{.lcomm}}. The @code{.comm} pseudo-op may be used to declare a common symbol, which is
another form of uninitialized symbol; see @xref{Comm,,@code{.comm}}.
@ifset GENERIC
When assembling for a target which supports multiple sections, such as ELF or
COFF, you may switch into the @code{.bss} section and define symbols as usual;
see @ref{Section,,@code{.section}}. You may only assemble zero values into the
section. Typically the section will only contain symbol definitions and
@code{.skip} directives (@pxref{Skip,,@code{.skip}}).
@end ifset
@node Symbols @node Symbols
@chapter Symbols @chapter Symbols
@ -2456,7 +2471,7 @@ If the label is written @samp{0:} then the digit is @samp{0}.
If the label is written @samp{1:} then the digit is @samp{1}. If the label is written @samp{1:} then the digit is @samp{1}.
And so on up through @samp{9:}. And so on up through @samp{9:}.
@item @ctrl{A} @item @kbd{C-A}
This unusual character is included so you do not accidentally invent This unusual character is included so you do not accidentally invent
a symbol of the same name. The character has ASCII value a symbol of the same name. The character has ASCII value
@samp{\001}. @samp{\001}.
@ -2468,8 +2483,8 @@ number @samp{15}; @emph{etc.}. Likewise for the other labels @samp{1:}
through @samp{9:}. through @samp{9:}.
@end table @end table
For instance, the first @code{1:} is named @code{L1@ctrl{A}1}, the 44th For instance, the first @code{1:} is named @code{L1@kbd{C-A}1}, the 44th
@code{3:} is named @code{L3@ctrl{A}44}. @code{3:} is named @code{L3@kbd{C-A}44}.
@node Dot @node Dot
@section The Special Dot Symbol @section The Special Dot Symbol
@ -2908,6 +2923,8 @@ Some machine configurations provide additional directives.
* Endif:: @code{.endif} * Endif:: @code{.endif}
* Equ:: @code{.equ @var{symbol}, @var{expression}} * Equ:: @code{.equ @var{symbol}, @var{expression}}
* Equiv:: @code{.equiv @var{symbol}, @var{expression}}
* Err:: @code{.err}
* Extern:: @code{.extern} * Extern:: @code{.extern}
@ifclear no-file-dir @ifclear no-file-dir
* File:: @code{.file @var{string}} * File:: @code{.file @var{string}}
@ -2969,6 +2986,9 @@ Some machine configurations provide additional directives.
@end ifset @end ifset
* String:: @code{.string "@var{str}"} * String:: @code{.string "@var{str}"}
@ifset ELF
* Symver:: @code{.symver @var{name},@var{name2@@nodename}}
@end ifset
@ifset COFF @ifset COFF
* Tag:: @code{.tag @var{structname}} * Tag:: @code{.tag @var{structname}}
@end ifset @end ifset
@ -3137,13 +3157,26 @@ Each expression is assembled into the next byte.
@cindex @code{comm} directive @cindex @code{comm} directive
@cindex symbol, common @cindex symbol, common
@code{.comm} declares a named common area in the bss section. Normally @code{.comm} declares a common symbol named @var{symbol}. When linking, a
@code{@value{LD}} reserves memory addresses for it during linking, so no partial common symbol in one object file may be merged with a defined or common symbol
program defines the location of the symbol. Use @code{.comm} to tell of the same name in another object file. If @code{@value{LD}} does not see a
@code{@value{LD}} that it must be at least @var{length} bytes long. @code{@value{LD}} definition for the symbol--just one or more common symbols--then it will
allocates space for each @code{.comm} symbol that is at least as allocate @var{length} bytes of uninitialized memory. @var{length} must be an
long as the longest @code{.comm} request in any of the partial programs absolute expression. If @code{@value{LD}} sees multiple common symbols with
linked. @var{length} is an absolute expression. the same name, and they do not all have the same size, it will allocate space
using the largest size.
@ifset ELF
When using ELF, the @code{.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 @code{@value{LD}} allocates uninitialized memory
for the common symbol, it will use the alignment when placing the symbol. If
no alignment is specified, @code{@value{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.
@end ifset
@ifset HPPA @ifset HPPA
The syntax for @code{.comm} differs slightly on the HPPA. The syntax is The syntax for @code{.comm} differs slightly on the HPPA. The syntax is
@ -3295,6 +3328,27 @@ The syntax for @code{equ} on the HPPA is
@samp{@var{symbol} .equ @var{expression}}. @samp{@var{symbol} .equ @var{expression}}.
@end ifset @end ifset
@node Equiv
@section @code{.equiv @var{symbol}, @var{expression}}
@cindex @code{equiv} directive
The @code{.equiv} directive is like @code{.equ} and @code{.set}, except that
the assembler will signal an error if @var{symbol} is already defined.
Except for the contents of the error message, this is roughly equivalent to
@smallexample
.ifdef SYM
.err
.endif
.equ SYM,VAL
@end smallexample
@node Err
@section @code{.err}
@cindex @code{err} directive
If @code{@value{AS}} assembles a @code{.err} directive, it will print an error
message and, unless the @code{-Z} option was used, it will not generate an
object file. This can be used to signal error an conditionally compiled code.
@node Extern @node Extern
@section @code{.extern} @section @code{.extern}
@ -3556,6 +3610,11 @@ section, so that at run-time the bytes start off zeroed. @var{Symbol}
is not declared global (@pxref{Global,,@code{.global}}), so is normally is not declared global (@pxref{Global,,@code{.global}}), so is normally
not visible to @code{@value{LD}}. not visible to @code{@value{LD}}.
@ifset GENERIC
Some targets permit a third argument to be used with @code{.lcomm}. This
argument specifies the desired alignment of the symbol in the bss section.
@end ifset
@ifset HPPA @ifset HPPA
The syntax for @code{.lcomm} differs slightly on the HPPA. The syntax is The syntax for @code{.lcomm} differs slightly on the HPPA. The syntax is
@samp{@var{symbol} .lcomm, @var{length}}; @var{symbol} is optional. @samp{@var{symbol} .lcomm, @var{length}}; @var{symbol} is optional.
@ -4036,6 +4095,8 @@ section is not loaded
writable section writable section
@item d @item d
data section data section
@item r
read-only section
@item x @item x
executable section executable section
@end table @end table
@ -4293,6 +4354,39 @@ 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. particular machine, the assembler marks the end of each string with a 0 byte.
You can use any of the escape sequences described in @ref{Strings,,Strings}. You can use any of the escape sequences described in @ref{Strings,,Strings}.
@ifset ELF
@node Symver
@section @code{.symver}
@cindex @code{symver} directive
@cindex symbol versioning
@cindex versions of symbols
Use the @code{.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 @code{.symver} directive is used like this:
@smallexample
.symver @var{name}, @var{name2@@nodename}
@end smallexample
In this case, the symbol @var{name} must exist and be defined within the file
being assembled. The @code{.versym} directive effectively creates a symbol
alias with the name @var{name2@@nodename}, and in fact the main reason that we
just don't try and create a regular alias is that the @var{@@} character isn't
permitted in symbol names. The @var{name2} part of the name is the actual name
of the symbol by which it will be externally referenced. The name @var{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 @var{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 @var{nodename} should correspond to the
nodename of the symbol you are trying to override.
@end ifset
@ifset COFF @ifset COFF
@node Tag @node Tag
@section @code{.tag @var{structname}} @section @code{.tag @var{structname}}