'\" t
.\" @(#)fbe.1 140 96/10/28 SMI;
.\" Copyright 1989 AT&T
.\"Copyright (c) 1996 Sun Microsystems, Inc.
.\"All Rights Reserved.
.TH fbe 1 "18 Jan 2000"
.SH NAME
fbe \- assembler
.SH SPARC SYNOPSIS
.B fbe
[
.B \-b
] [
.B \-K PIC
] [
.B \-L
] [
.B \-m
] [
.B \-n 
] [
.BI \-o " outfile"
] 
.if n .br
[
.\".BR \-O [\f2n\f1]\|]
.\"[
.B \-P
] 
[
.BI \-D name
] [
.BI \-D name=def
]
.if t .ti +5n
[
.BI \-I path
] [
.BI \-U name \|.\|.\|. \|.
]
.if n .br
[
.B \-q
] [
.BR \-Q {\f2y\f1\f2\||\|\\f1\f2n\f1
] [
.B \-s
] [
.BR \-S [\f2a|C\f1]
] [
.B \-T
] [
.B \-V
] 
.if t .ti +5n
.if n .br
[
.B \-xarch=\f2v\f1
]
.if t .ti +5n
[
.B \-xF
]
.\".if t .ti +5n
.IR filename \|.\|.\|.
.SH x86 SYNOPSIS
.B fbe
[
.\".B \-b
.\"] [
.\"[
.\".B \-K PIC
.\] [
.\".B \-L
.\"] [
.B \-m
] [
.B \-n
] [
.BI \-o " outfile"
.\"] [
.\".BR \-O [\f2n\f1]\|]
.\".if n .br
] [
.B \-P
] [
.BI \-D name
]
.if n .br
[
.BI \-D name=def
]
[
.BI \-I path
]
.if t .ti +5n
[
.BI \-U name \|.\|.\|.\|]
.if n .br
.\"[
.\".B \-q
.\"]
[
.BR \-Q \f2y\f1\f2\||\|\f1\f2n\f1
] [
.B \-s
]
.\"[
/\".BR \-S [\f2C\f1]
.\"] [
.\".B \-T
.\"]
[
.B \-V
]
.\" [
.\".B -xF
.\"]
IF filename \|.\|.\|.
.SH AVAILABILITY
.LP
SUNWsprot
.SH DESCRIPTION
.IX "fbe" "" "\fLfbe\fP \(em assembler"
.IX "assembler" "fbe" "" "\(em \fLfbe\fP"
.IX "programming tools" "assembler" "" "assembler \(em \fLfbe\fP"
.LP
The 
.B fbe
command
creates object files from assembly language source
.IR files .
.if ''b16' \{\
The output file is executable if no errors
occurred during the assembly, transfer vectors were not used,
and there are no unresolved external references.\}
.SH COMMON OPTIONS
.LP
The following flags are common to both SPARC and x86. They
may be specified in any order.
.\" .if "m32' \{\
.\" .TP
.\" \f3\-v\f1\f2 type\f1
.\" type is either an 'x' indicating the original
.\" \f3\f1
.\" assembler or an 'a' indicating the
.\" \f3a\f1
.\" assembler.
.\" \}
.TP 15
.PD 0
\f3\-D\f1\f2name\f1
.TP
\f3\-D\f1\f2name=def\f1
.PD
When the \f3\-P\f1 option is in effect, these options are passed to the 
.BR cpp (1)
preprocessor without interpretation by the \f3fbe\f1 command; 
otherwise, they are ignored. 
.TP
\f3\-I\f1\f2path\f1
When the \f3\-P\f1 option is in effect, this option is passed to the
.BR cpp (1)
preprocessor without interpretation by the \f3fbe\f1 command; 
otherwise, it is ignored. 
.TP
.B \-m
Run the 
.BR m4 (1)
macro processor
on the input to the assembler.
.TP
.B \-n
Suppress all the warnings while assembling.
.TP
.BI \-o " outfile"
Put the output of the assembly in
.IR outfile .
By default, the output file name is formed by
removing the 
\f3\&.s\f1
suffix, if there is one, from the input file name
and appending a 
\f3\&.o\f1
suffix.
.\".TP
.\"\f3\-O\f1[\f2n\f1] 
.\"Enable peephole optimization corresponding to optimization level \f2n\f1 
.\"of the Sun high-level language compilers.  
.\"If \f2n\f1 is not specified, the default is 1.
.\"This option can be used safely only when assembling code 
.\"produced by a SPARC compiler. 
.if ''x86' \{\
.TP
\f3\-x\f1
This
flag is
.I required
\}
.if ''3b' \{
.TP
\f3\-Q\f1
Warn the user if a transfer vector operand is used
in any context other than a "call" instruction.
\}
.TP
.B \-P
Run 
.BR cpp (1),
the C preprocessor, on the files being assembled. 
The preprocessor is run separately on each input file, 
not on their concatenation.
The preprocessor output is passed to the assembler. 
.if ''vax' \{\
.TP
\f3\-j\f1
Invoke the long-jump assembler
(for the \s-1VAX\s+1 version of the common assembler only).
The address optimization algorithm chooses between long and short
address lengths, with short lengths chosen when possible.
Often, three distinct lengths are allowed by the machine architecture;
a choice must be made between two of those lengths.
When the two choices given to the assembler exclude the largest length
allowed, then some addresses might be unrepresentable.
The long-jump assembler will always have the largest length as one of
its allowable choices.
If the assembler is invoked without this option, and the case arises
where an address is unrepresentable by either of the two allowed choices,
then the user will be informed of the error, and advised to try again
using the
\f3\-j\f1
option.
\}
.if ''vax' \{\
.TP
\f3\-r\f1
Place all assembled data
(normally placed in the \f3\&.data\f1 section)
into the \f3\&.text\f1 section
(for the \s-1VAX\s+1 version of the common assembler only).
This option effectively disables the
\f3\&.data\f1
pseudo operation.
This option is off by default.
\}
.if ''vax' \{\
.TP
\f3\-[bwl]\f1
Create byte
\f1(\f3b\f1),
halfword
\f1(\f3w\f1)
or long
\f1(\f3l\f1)
displacements for undefined symbols
(for the \s-1VAX\s+1 version of the common assembler only).
(An undefined symbol is a reference to a symbol
whose definition is external to the input file or a forward reference.)
The default value for this option is long 
\f1(\f3l\f1)
displacements.
\}
.br
.ne 3
.TP
\f3\-Q\f1\f3y\f1\||\f3n\f1
If the \f2n\f1 option is specified, it produces the "assembler version" 
information in the comment section of the output object file. 
If the \f2y\f1 option is specified, the information is suppressed. 
.br
.ne 7
.TP
.B \-s
Place all stabs in the \f3\&.stabs\f1 section. By default, stabs ares
placed in \f3stabs.excl\f1 sections, which are stripped out by the
static linker,
.BR ld (1),
during final execution. 
When the \f3\-s\f1 option is used, stabs remain in the
final executable because \f3\&.stab\f1 sections are not stripped by the static 
linker.
.TP
.BI -U name 
When the \f3\-P\f1 option is in effect, 
this option is passed to the 
.BR cpp (1)
preprocessor
without interpretation by the as command; otherwise, it is ignored. 
.TP
.B \-V
Write the version number of the assembler being run
on the standard error output.
.SS SPARC Options
.TP 15
.B \-b
Generate extra symbol table information
for the Sun SourceBrowser. 
.TP
.B \-K PIC
Generate position-independent code.  The x86 assembler does not support
the -K PIC flag.
.TP
.B \-L
Save all symbols, including temporary labels that are normally discarded 
to save space, in the ELF symbol table. 
.TP
.B \-q
Perform a quick assembly. 
When the \f3\-q\f1 option is used, many error checks are not
performed. 
.br
\f3Note:\f1 This option disables many error checks. 
It is recommended that you do not use this 
option to assemble handwritten assembly language.
.TP
\f3\-S\f1[\f2a|C\f1] 
Produce a disassembly of the emitted code to the standard output. 
.\"This option is most useful in combination with the \f3\-O\f1 option to review 
.\"optimized code. 
.br
.RS
\(bu
Adding the character \f2a\f1 to the option appends a comment line to each 
assembly code which indicates its relative address in its own section.
.br
\(bu
Adding the character \f2C\f1 to the option prevents comment lines from appearing in the output. 
.RE
.TP
.B \-T
This is a migration option for 4.x assembly files to be assembled
on 5.x systems. With this option, the symbol names in 4.x assembly
files will be interpreted as 5.x symbol names.
.TP
.if t .B \-xarch=v7
.if n .B -xarch=v7
Enables the assembler to accept instructions defined 
in the SPARC version 7 (V7) architecture. 
The resulting object code is in ELF32 format.
.TP 
.if t .B \-xarch=v8
.if n .B -xarch=v8
Enables the assembler to accept instructions
defined in the SPARC-V8 architecture.
The resulting object code is in ELF32 format. 
.TP
.if t .B \-xarch=v8a
.if n .B -xarch=v8a
Enables the assembler to accept instructions
defined in the SPARC-V8 architecture, 
less the 
.IR fsmuld 
instruction.
The resulting object code is in ELF32 format. 
This is the default choice of the -xarch= options.
.TP
.if t .B \-xarch=v8plus
.if n .B -xarch=v8plus
Enables the assembler to accept instructions
defined in the SPARC-V9 architecture.
The resulting object code is in ELF32 format.
It will not execute on a Solaris V8 system (a machine
with a V8 processor).
It will execute on a Solaris V8+ system.
.TP
.if t .B \-xarch=v8plusa
.if n .B -xarch=v8plusa
Enables the assembler to accept instructions
defined in the SPARC-V9 architecture 
plus the instructions in the Visual Instruction Set (VIS).
The resulting object code is in V8+ ELF32 format.
It will not execute on a Solaris V8 system (a machine with a 
V8 processor).
It will execute on a Solaris V8+ system
.TP
.B \-xarch=v8plusb
Enables the assembler to accept instructions
defined in the SPARC-V9 architecture, 
plus the instructions in the Visual Instruction Set (VIS),
with UltraSPARC-III extensions.
The resulting object code is in V8+ ELF32 format.
It will execute only on an UltraSPARC-III processor.
.TP
.if t .B \-xarch=v9
.if n .B -xarch=v9
Enables the assembler to accept instructions
defined  in the SPARC-V9
architecture, but without the Visual Instruction Set (VIS).
The resulting 
.B .o
object files are in ELF64 format and can only be linked
with other V9 object files in the same format.
The resulting executable can only be run
on a 64-bit UltraSPARC processor running a 64-bit Solaris operating
environment with the 64-bit kernel. 
.TP
.if t .B \-xarch=v9a
.if n .B -xarch=v9a
Enables the assembler to accept instructions
defined in the SPARC-V9
architecture, plus the Visual Instruction Set (VIS).
The resulting 
.B .o
object files are in ELF64 format and can only be linked
with other V9 object files in the same format.
The resulting executable can only be run
on a 64-bit UltraSPARC processor running a 64-bit Solaris operating
environment with the 64-bit kernel. 
.TP
.B \-xarch=v9b
Enables the assembler to accept instructions
defined in the SPARC-V9 
architecture, plus the Visual Instruction Set (VIS),
with UltraSPARC-III extensions.
The resulting                                                              
.B .o
object files are in ELF64 format and can only be linked
with other V9 object files in the same format.
The resulting executable can only be run
on a 64-bit UltraSPARC-III processor running a 64-bit Solaris operating
environment with the 64-bit kernel.
.TP
.B \-xF
Generates additional information for performance
analysis of the executable using SPARCworks analyzer.
If the input file does not contain any stabs (debugging
directives), then the assembler will generate
some default stabs which are
needed by the SPARCworks analyzer.  Also see the
manual page 
.BR dbx .
.br
.ne 5
.SH "ENVIRONMENT"
.TP 1
.B TMPDIR 
.B as
normally creates temporary files in the directory 
\f3/tmp\f1.  You may specify another directory by setting the 
environment variable 
.SB TMPDIR 
to your chosen directory.  
(If 
.SB TMPDIR 
isn't a valid directory, then \f3as\f1 will use \f3/tmp\f1).
.SH "FILES"
.LP
By default,
\f3as\f1
creates its temporary files in
\f3/tmp\f1.
.SH ATTRIBUTES
See
.BR attributes (5)
for descriptions of the following attributes:
.sp
.TS
box;
cbp-1 | cbp-1
l | l .
ATTRIBUTE TYPE  ATTRIBUTE VALUE
=
Availability    SPROlang
.TE
.SH "SEE ALSO"
.BR attributes (5),
.BR cc (1B),
.BR cpp (1),
.BR ld (1),
.BR m4 (1),
.BR nm (1),
.BR strip (1),
.BR tmpnam (3S),
.BR a.out (4)
.SH NOTES
On SPARC, the 
.B cpp
symbol 
.B __sparc
is set when the flag
.B \-P
appears, as well as
.B __sparcv8 
with any of the 
.B \-xarch=v8*
flags, and
.B __sparcv9
with any of the 
.B \-xarch=v9*
flags.
.if ''3b' \{
.P
If the input file does not contain a 
\f3\&.file\f1
assembler directive and the
\f3\-m\f1
flag was not specified,
the file name given by the assembler when an
error occurs is one of the temporary files
\f1(\f3/tmp/as\f1\s-1XXXXXX\s+1)
\}
.P
If the 
\f3\-m\f1
(invoke the
.BR m4 (1)
macro processor) option is used,
keywords for
.BR m4 (1)
cannot be used as symbols (variables, functions, labels)
in the input file since
.BR m4 (1)
cannot determine which keywords are assembler symbols and 
which keywords are real 
.BR m4 (1)
macros.
.if ''vax' \{\
.P
Use the
\f3\-b\f1
or 
\f3\-w\f1
option only when undefined symbols are known to refer to locations
representable by the specified default displacement.
Use of either option when assembling a file containing a reference
to a symbol that is to be resolved by the loader can lead to
unpredictable results,
since the loader may be unable to place the address of the symbol
into the space provided.
\}
.P
Whenever possible, you should access the assembler through a
compilation system interface program such as 
.BR cc (1B).
.P
All undefined symbols are treated as global.