@var{objfile}] [@b{-R}] [@b{--reduce-memory-overheads}] [@b{--statistics}]
[@b{-v}] [@b{-version}] [@b{--version}] [@b{-W}] [@b{--warn}]
[@b{--fatal-warnings}] [@b{-w}] [@b{-x}] [@b{-Z}] [@b{@@@var{FILE}}]
- [@b{--size-check=[error|warning]}]
+ [@b{--sectname-subst}] [@b{--size-check=[error|warning]}]
[@b{--target-help}] [@var{target-options}]
[@b{--}|@var{files} @dots{}]
@c
assembly processes slower. Currently this switch is a synonym for
@samp{--hash-size=4051}, but in the future it may have other effects as well.
+@ifset ELF
+@item --sectname-subst
+Honor substitution sequences in section names.
+@ifclear man
+@xref{Section Name Substitutions,,@code{.section @var{name}}}.
+@end ifclear
+@end ifset
+
@item --statistics
Print the maximum space (in bytes) and total time (in seconds) used by
assembly.
Case of letters is significant: @code{foo} is a different symbol name
than @code{Foo}.
+Symbol names do not start with a digit. An exception to this rule is made for
+Local Labels. See below.
+
Multibyte characters are supported. To generate a symbol name containing
multibyte characters enclose it within double quotes and use escape codes. cf
@xref{Strings}. Generating a multibyte symbol name from a label is not
@cindex local labels
@cindex temporary symbol names
@cindex symbol names, temporary
-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 @samp{@b{N}:} (where @b{N}
-represents any positive integer). To refer to the most recent previous
-definition of that label write @samp{@b{N}b}, using the same number as when
-you defined the label. To refer to the next definition of a local label, write
-@samp{@b{N}f}---the @samp{b} stands for ``backwards'' and the @samp{f} stands
-for ``forwards''.
+Local labels are different from local symbols. 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 @samp{@b{N}:} (where @b{N} represents any positive integer). To refer
+to the most recent previous definition of that label write @samp{@b{N}b}, using
+the same number as when you defined the label. To refer to the next definition
+of a local label, write @samp{@b{N}f}---the @samp{b} stands for ``backwards''
+and the @samp{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
@subheading Dollar Local Labels
@cindex dollar local symbols
-@code{@value{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.
+On some targets @code{@value{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 they have a dollar sign suffix to their numeric value, e.g.,
* Weak:: @code{.weak @var{names}}
* Weakref:: @code{.weakref @var{alias}, @var{symbol}}
* Word:: @code{.word @var{expressions}}
+@ifclear no-space-dir
+* Zero:: @code{.zero @var{size}}
+@end ifclear
* Deprecated:: Deprecated Directives
@end menu
To emit both use @code{.eh_frame, .debug_frame}. The default if this
directive is not used is @code{.cfi_sections .eh_frame}.
+On targets that support compact unwinding tables these can be generated
+by specifying @code{.eh_frame_entry} instead of @code{.eh_frame}.
+
@subsection @code{.cfi_startproc [simple]}
@cindex @code{cfi_startproc} directive
@code{.cfi_startproc} is used at the beginning of each function that
@code{.cfi_startproc}, and emits it to @code{.eh_frame}.
@subsection @code{.cfi_personality @var{encoding} [, @var{exp}]}
+@cindex @code{cfi_personality} directive
@code{.cfi_personality} defines personality routine and its encoding.
@var{encoding} must be a constant determining how the personality
should be encoded. If it is 255 (@code{DW_EH_PE_omit}), second
The default after @code{.cfi_startproc} is @code{.cfi_personality 0xff},
no personality routine.
+@subsection @code{.cfi_personality_id @var{id}}
+@cindex @code{cfi_personality_id} directive
+@code{cfi_personality_id} defines a personality routine by its index as
+defined in a compact unwinding format.
+Only valid when generating compact EH frames (i.e.
+with @code{.cfi_sections eh_frame_entry}.
+
+@subsection @code{.cfi_fde_data [@var{opcode1} [, @dots{}]]}
+@cindex @code{cfi_fde_data} directive
+@code{cfi_fde_data} is used to describe the compact unwind opcodes to be
+used for the current function. These are emitted inline in the
+@code{.eh_frame_entry} section if small enough and there is no LSDA, or
+in the @code{.gnu.extab} section otherwise.
+Only valid when generating compact EH frames (i.e.
+with @code{.cfi_sections eh_frame_entry}.
+
@subsection @code{.cfi_lsda @var{encoding} [, @var{exp}]}
@code{.cfi_lsda} defines LSDA and its encoding.
@var{encoding} must be a constant determining how the LSDA
-should be encoded. If it is 255 (@code{DW_EH_PE_omit}), second
-argument is not present, otherwise second argument should be a constant
+should be encoded. If it is 255 (@code{DW_EH_PE_omit}), the second
+argument is not present, otherwise the second argument should be a constant
or a symbol name. The default after @code{.cfi_startproc} is @code{.cfi_lsda 0xff},
-no LSDA.
+meaning that no LSDA is present.
+
+@subsection @code{.cfi_inline_lsda} [@var{align}]
+@code{.cfi_inline_lsda} marks the start of a LSDA data section and
+switches to the corresponding @code{.gnu.extab} section.
+Must be preceded by a CFI block containing a @code{.cfi_lsda} directive.
+Only valid when generating compact EH frames (i.e.
+with @code{.cfi_sections eh_frame_entry}.
+
+The table header and unwinding opcodes will be generated at this point,
+so that they are immediately followed by the LSDA data. The symbol
+referenced by the @code{.cfi_lsda} directive should still be defined
+in case a fallback FDE based encoding is used. The LSDA data is terminated
+by a section directive.
+
+The optional @var{align} argument specifies the alignment required.
+The alignment is specified as a power of two, as with the
+@code{.p2align} directive.
@subsection @code{.cfi_def_cfa @var{register}, @var{offset}}
@code{.cfi_def_cfa} defines a rule for computing CFA as: @i{take
.section @var{name} [, "@var{flags}"[, @@@var{type}[,@var{flag_specific_arguments}]]]
@end smallexample
+@anchor{Section Name Substitutions}
+@kindex --sectname-subst
+@cindex section name substitution
+If the @samp{--sectname-subst} command-line option is provided, the @var{name}
+argument may contain a substitution sequence. Only @code{%S} is supported
+at the moment, and substitutes the current section name. For example:
+
+@smallexample
+.macro exception_code
+.section %S.exception
+[exception code here]
+.previous
+.endm
+
+.text
+[code]
+exception_code
+[...]
+
+.section .init
+[init code]
+exception_code
+[...]
+@end smallexample
+
+The two @code{exception_code} invocations above would create the
+@code{.text.exception} and @code{.init.exception} sections respectively.
+This is useful e.g. to discriminate between anciliary sections that are
+tied to setup code to be discarded after use from anciliary sections that
+need to stay resident without having to define multiple @code{exception_code}
+macros just for that purpose.
+
The optional @var{flags} argument is a quoted string which may contain any
combination of the following characters:
@table @code
@var{expression}. If @var{symbol} was flagged as external, it remains
flagged (@pxref{Symbol Attributes}).
-You may @code{.set} a symbol many times in the same assembly.
+You may @code{.set} a symbol many times in the same assembly provided that the
+values given to the symbol are constants. Values that are based on expressions
+involving other symbols are allowed, but some targets may restrict this to only
+being done once per assembly. This is because those targets do not set the
+addresses of symbols at assembly time, but rather delay the assignment until a
+final link is performed. This allows the linker a chance to change the code in
+the files, changing the location of, and the relative distance between, various
+different symbols.
If you @code{.set} a global symbol, the value stored in the object
file is the last value stored into it.
@end ifset
@c end DIFF-TBL-KLUGE
+@ifclear no-space-dir
+@node Zero
+@section @code{.zero @var{size}}
+
+@cindex @code{zero} directive
+@cindex filling memory with zero bytes
+This directive emits @var{size} 0-valued bytes. @var{size} must be an absolute
+expression. This directive is actually an alias for the @samp{.skip} directive
+so in can take an optional second argument of the value to store in the bytes
+instead of zero. Using @samp{.zero} in this way would be confusing however.
+@end ifclear
+
@node Deprecated
@section Deprecated Directives
@end itemize
@end table
+@subsection IBM z Systems Attributes
+
+@table @r
+@item Tag_GNU_S390_ABI_Vector (8)
+The vector ABI used by this object file. The value will be:
+
+@itemize @bullet
+@item
+0 for files not affected by the vector ABI.
+@item
+1 for files using software vector ABI.
+@item
+2 for files using hardware vector ABI.
+@end itemize
+@end table
+
@node Defining New Object Attributes
@section Defining New Object Attributes
projects / deliverable / binutils-gdb.git / blobdiff