gnu/usr.bin/as/as.1

   1 .\" Copyright (c) 1991, 1992 Free Software Foundation
   2 .\" See section COPYING for conditions for redistribution
   3 .\" $FreeBSD: src/gnu/usr.bin/as/as.1,v 1.9 1999/08/27 23:34:11 peter Exp $
   4 .TH as 1 "21 January 1992" "cygnus support" "GNU Development Tools"
   5
   6 .SH NAME
   7 as \- the portable GNU assembler.
   8
   9 .SH SYNOPSIS
  10 .na
  11 .B as
  12 .RB "[\|" \-a "\||\|" \-al "\||\|" -as\c
  13 \&\|]
  14 .RB "[\|" \-D "\|]"
  15 .RB "[\|" \-f "\|]"
  16 .RB "[\|" \-I
  17 .I path\c
  18 \&\|]
  19 .RB "[\|" \-k "\|]"
  20 .RB "[\|" \-K "\|]"
  21 .RB "[\|" \-L "\|]"
  22 .RB "[\|" \-o
  23 .I objfile\c
  24 \&\|]
  25 .RB "[\|" \-R "\|]"
  26 .RB "[\|" \-v "\|]"
  27 .RB "[\|" \-w "\|]"
  28 .RB "[\|" \-\^\- "\ |\ " \c
  29 .I files\c
  30 \&\|.\|.\|.\|]
  31
  32 .I i960-only options:
  33 .br
  34 .RB "[\|" \-ACA "\||\|" \-ACA_A "\||\|" \-ACB\c
  35 .RB "\||\|" \-ACC "\||\|" \-AKA "\||\|" \-AKB\c
  36 .RB "\||\|" \-AKC "\||\|" \-AMC "\|]"
  37 .RB "[\|" \-b "\|]"
  38 .RB "[\|" \-norelax "\|]"
  39
  40 .I m680x0-only options:
  41 .br
  42 .RB "[\|" \-l "\|]"
  43 .RB "[\|" \-mc68000 "\||\|" \-mc68010 "\||\|" \-mc68020 "\|]"
  44 .ad b
  45
  46 .SH DESCRIPTION
  47 GNU \c
  48 .B as\c
  49 \& is really a family of assemblers.
  50 If you use (or have used) the GNU assembler on one architecture, you
  51 should find a fairly similar environment when you use it on another
  52 architecture.  Each version has much in common with the others,
  53 including object file formats, most assembler directives (often called
  54 \c
  55 .I pseudo-ops)\c
  56 \& and assembler syntax.
  57
  58 For information on the syntax and pseudo-ops used by GNU \c
  59 .B as\c
  60 \&, see `\|\c
  61 .B as\c
  62 \|' entry in \c
  63 .B info \c
  64 (or the manual \c
  65 .I
  66 .I
  67 Using as: The GNU Assembler\c
  68 \&).
  69
  70 \c
  71 .B as\c
  72 \& is primarily intended to assemble the output of the GNU C
  73 compiler \c
  74 .B gcc\c
  75 \& for use by the linker \c
  76 .B ld\c
  77 \&.  Nevertheless,
  78 we've tried to make \c
  79 .B as\c
  80 \& assemble correctly everything that the native
  81 assembler would.
  82 This doesn't mean \c
  83 .B as\c
  84 \& always uses the same syntax as another
  85 assembler for the same architecture; for example, we know of several
  86 incompatible versions of 680x0 assembly language syntax.
  87
  88 Each time you run \c
  89 .B as\c
  90 \& it assembles exactly one source
  91 program.  The source program is made up of one or more files.
  92 (The standard input is also a file.)
  93
  94 If \c
  95 .B as\c
  96 \& is given no file names it attempts to read one input file
  97 from the \c
  98 .B as\c
  99 \& standard input, which is normally your terminal.  You
 100 may have to type \c
 101 .B ctl-D\c
 102 \& to tell \c
 103 .B as\c
 104 \& there is no more program
 105 to assemble.  Use `\|\c
 106 .B \-\^\-\c
 107 \|' if you need to explicitly name the standard input file
 108 in your command line.
 109
 110 .B as\c
 111 \& may write warnings and error messages to the standard error
 112 file (usually your terminal).  This should not happen when \c
 113 .B as\c
 114 \& is
 115 run automatically by a compiler.  Warnings report an assumption made so
 116 that \c
 117 .B as\c
 118 \& could keep assembling a flawed program; errors report a
 119 grave problem that stops the assembly.
 120
 121 .SH OPTIONS
 122 .TP
 123 .BR \-a \||\| \-al \||\| \-as
 124 Turn on assembly listings; `\|\c
 125 .B \-al\c
 126 \&\|', listing only, `\|\c
 127 .B \-as\c
 128 \&\|', symbols
 129 only, `\|\c
 130 .B \-a\c
 131 \&\|', everything.
 132 .TP
 133 .B \-D
 134 This option is accepted only for script compatibility with calls to
 135 other assemblers; it has no effect on \c
 136 .B as\c
 137 \&.
 138 .TP
 139 .B \-f
 140 ``fast''--skip preprocessing (assume source is compiler output).
 141 .TP
 142 .BI "\-I\ " path
 143 Add
 144 .I path
 145 to the search list for
 146 .B .include
 147 directives.
 148 .TP
 149 .B \-k
 150 Handle position independent code, generated by gcc -fpic.
 151 .TP
 152 .B \-K
 153 Handle position independent code, generated by gcc -fPIC.
 154 This is normally the same as -k.
 155 .TP
 156 .B \-L
 157 Keep (in symbol table) local symbols, starting with `\|\c
 158 .B L\c
 159 \|'
 160 .TP
 161 .BI "\-o\ " objfile
 162 Name the object-file output from \c
 163 .B as
 164 .TP
 165 .B \-R
 166 Fold data section into text section
 167 .TP
 168 .B \-v
 169 Announce \c
 170 .B as\c
 171 \& version
 172 .TP
 173 .B \-W
 174 Suppress warning messages
 175 .TP
 176 .IR "\-\^\-" "\ |\ " "files\|.\|.\|."
 177 Source files to assemble, or standard input (\c
 178 .BR "\-\^\-" ")"
 179 .TP
 180 .BI \-A var
 181 .I
 182 (When configured for Intel 960.)
 183 Specify which variant of the 960 architecture is the target.
 184 .TP
 185 .B \-b
 186 .I
 187 (When configured for Intel 960.)
 188 Add code to collect statistics about branches taken.
 189 .TP
 190 .B \-norelax
 191 .I
 192 (When configured for Intel 960.)
 193 Do not alter compare-and-branch instructions for long displacements;
 194 error if necessary.
 195 .TP
 196 .B \-l
 197 .I
 198 (When configured for Motorola 68000).
 199 .br
 200 Shorten references to undefined symbols, to one word instead of two.
 201 .TP
 202 .BR "\-mc68000" "\||\|" "\-mc68010" "\||\|" "\-mc68020"
 203 .I
 204 (When configured for Motorola 68000).
 205 .br
 206 Specify what processor in the 68000 family is the target (default 68020)
 207
 208 .PP
 209 Options may be in any order, and may be
 210 before, after, or between file names.  The order of file names is
 211 significant.
 212
 213 `\|\c
 214 .B \-\^\-\c
 215 \|' (two hyphens) by itself names the standard input file
 216 explicitly, as one of the files for \c
 217 .B as\c
 218 \& to assemble.
 219
 220 Except for `\|\c
 221 .B \-\^\-\c
 222 \|' any command line argument that begins with a
 223 hyphen (`\|\c
 224 .B \-\c
 225 \|') is an option.  Each option changes the behavior of
 226 \c
 227 .B as\c
 228 \&.  No option changes the way another option works.  An
 229 option is a `\|\c
 230 .B \-\c
 231 \|' followed by one or more letters; the case of
 232 the letter is important.   All options are optional.
 233
 234 The `\|\c
 235 .B \-o\c
 236 \|' option expects exactly one file name to follow.  The file
 237 name may either immediately follow the option's letter (compatible
 238 with older assemblers) or it may be the next command argument (GNU
 239 standard).
 240
 241 These two command lines are equivalent:
 242 .br
 243 .B
 244 as\ \ \-o\ \ my\-object\-file.o\ \ mumble.s
 245 .br
 246 .B
 247 as\ \ \-omy\-object\-file.o\ \ mumble.s
 248
 249 .SH "SEE ALSO"
 250 .RB "`\|" as "\|'"
 251 entry in
 252 .B
 253 info\c
 254 \&;
 255 .I
 256 Using as: The GNU Assembler\c
 257 \&;
 258 .BR gcc "(" 1 "),"
 259 .BR ld "(" 1 ")."
 260
 261 .SH HISTORY
 262 A
 263 .I as
 264 command appeared in
 265 Version 1 AT&T UNIX.
 266
 267 .SH COPYING
 268 Copyright (c) 1991, 1992 Free Software Foundation, Inc.
 269 .PP
 270 Permission is granted to make and distribute verbatim copies of
 271 this manual provided the copyright notice and this permission notice
 272 are preserved on all copies.
 273 .PP
 274 Permission is granted to copy and distribute modified versions of this
 275 manual under the conditions for verbatim copying, provided that the
 276 entire resulting derived work is distributed under the terms of a
 277 permission notice identical to this one.
 278 .PP
 279 Permission is granted to copy and distribute translations of this
 280 manual into another language, under the above conditions for modified
 281 versions, except that this permission notice may be included in
 282 translations approved by the Free Software Foundation instead of in
 283 the original English.