as.texinfo revision 1.4
1\input texinfo @c -*-Texinfo-*- 2@c Copyright (c) 1991, 92, 93, 94, 95, 1996 Free Software Foundation, Inc. 3@c UPDATE!! On future updates-- 4@c (1) check for new machine-dep cmdline options in 5@c md_parse_option definitions in config/tc-*.c 6@c (2) for platform-specific directives, examine md_pseudo_op 7@c in config/tc-*.c 8@c (3) for object-format specific directives, examine obj_pseudo_op 9@c in config/obj-*.c 10@c (4) portable directives in potable[] in read.c 11@c %**start of header 12@setfilename as.info 13@c ---config--- 14@c defaults, config file may override: 15@set have-stabs 16@c --- 17@include asconfig.texi 18@c --- 19@c common OR combinations of conditions 20@ifset AOUT 21@set aout-bout 22@end ifset 23@ifset BOUT 24@set aout-bout 25@end ifset 26@ifset H8/300 27@set H8 28@end ifset 29@ifset H8/500 30@set H8 31@end ifset 32@ifset SH 33@set H8 34@end ifset 35@ifset HPPA 36@set abnormal-separator 37@end ifset 38@c ------------ 39@ifset GENERIC 40@settitle Using @value{AS} 41@end ifset 42@ifclear GENERIC 43@settitle Using @value{AS} (@value{TARGET}) 44@end ifclear 45@setchapternewpage odd 46@c %**end of header 47 48@c @smallbook 49@c @set SMALL 50@c WARE! Some of the machine-dependent sections contain tables of machine 51@c instructions. Except in multi-column format, these tables look silly. 52@c Unfortunately, Texinfo doesn't have a general-purpose multi-col format, so 53@c the multi-col format is faked within @example sections. 54@c 55@c Again unfortunately, the natural size that fits on a page, for these tables, 56@c is different depending on whether or not smallbook is turned on. 57@c This matters, because of order: text flow switches columns at each page 58@c break. 59@c 60@c The format faked in this source works reasonably well for smallbook, 61@c not well for the default large-page format. This manual expects that if you 62@c turn on @smallbook, you will also uncomment the "@set SMALL" to enable the 63@c tables in question. You can turn on one without the other at your 64@c discretion, of course. 65@ifinfo 66@set SMALL 67@c the insn tables look just as silly in info files regardless of smallbook, 68@c might as well show 'em anyways. 69@end ifinfo 70 71@ifinfo 72@format 73START-INFO-DIR-ENTRY 74* As: (as). The GNU assembler. 75END-INFO-DIR-ENTRY 76@end format 77@end ifinfo 78 79@finalout 80@syncodeindex ky cp 81 82@ifinfo 83This file documents the GNU Assembler "@value{AS}". 84 85Copyright (C) 1991, 92, 93, 94, 95, 1996 Free Software Foundation, Inc. 86 87Permission is granted to make and distribute verbatim copies of 88this manual provided the copyright notice and this permission notice 89are preserved on all copies. 90 91@ignore 92Permission is granted to process this file through Tex and print the 93results, provided the printed document carries copying permission 94notice identical to this one except for the removal of this paragraph 95(this paragraph not being relevant to the printed manual). 96 97@end ignore 98Permission is granted to copy and distribute modified versions of this manual 99under the conditions for verbatim copying, provided that the entire resulting 100derived work is distributed under the terms of a permission notice identical to 101this one. 102 103Permission is granted to copy and distribute translations of this manual 104into another language, under the above conditions for modified versions. 105@end ifinfo 106 107@titlepage 108@title Using @value{AS} 109@subtitle The @sc{gnu} Assembler 110@ifclear GENERIC 111@subtitle for the @value{TARGET} family 112@end ifclear 113@sp 1 114@subtitle January 1994 115@sp 1 116@sp 13 117The Free Software Foundation Inc. thanks The Nice Computer 118Company of Australia for loaning Dean Elsner to write the 119first (Vax) version of @code{as} for Project @sc{gnu}. 120The proprietors, management and staff of TNCCA thank FSF for 121distracting the boss while they got some work 122done. 123@sp 3 124@author Dean Elsner, Jay Fenlason & friends 125@page 126@tex 127{\parskip=0pt 128\hfill {\it Using {\tt @value{AS}}}\par 129\hfill Edited by Cygnus Support\par 130} 131%"boxit" macro for figures: 132%Modified from Knuth's ``boxit'' macro from TeXbook (answer to exercise 21.3) 133\gdef\boxit#1#2{\vbox{\hrule\hbox{\vrule\kern3pt 134 \vbox{\parindent=0pt\parskip=0pt\hsize=#1\kern3pt\strut\hfil 135#2\hfil\strut\kern3pt}\kern3pt\vrule}\hrule}}%box with visible outline 136\gdef\ibox#1#2{\hbox to #1{#2\hfil}\kern8pt}% invisible box 137@end tex 138 139@vskip 0pt plus 1filll 140Copyright @copyright{} 1991, 92, 93, 94, 95, 1996 Free Software Foundation, Inc. 141 142Permission is granted to make and distribute verbatim copies of 143this manual provided the copyright notice and this permission notice 144are preserved on all copies. 145 146Permission is granted to copy and distribute modified versions of this manual 147under the conditions for verbatim copying, provided that the entire resulting 148derived work is distributed under the terms of a permission notice identical to 149this one. 150 151Permission is granted to copy and distribute translations of this manual 152into another language, under the above conditions for modified versions. 153@end titlepage 154 155@ifinfo 156@node Top 157@top Using @value{AS} 158 159This file is a user guide to the @sc{gnu} assembler @code{@value{AS}}. 160@ifclear GENERIC 161This version of the file describes @code{@value{AS}} configured to generate 162code for @value{TARGET} architectures. 163@end ifclear 164@menu 165* Overview:: Overview 166* Invoking:: Command-Line Options 167* Syntax:: Syntax 168* Sections:: Sections and Relocation 169* Symbols:: Symbols 170* Expressions:: Expressions 171* Pseudo Ops:: Assembler Directives 172* Machine Dependencies:: Machine Dependent Features 173* Reporting Bugs:: Reporting Bugs 174* Acknowledgements:: Who Did What 175* Index:: Index 176@end menu 177@end ifinfo 178 179@node Overview 180@chapter Overview 181@iftex 182This manual is a user guide to the @sc{gnu} assembler @code{@value{AS}}. 183@ifclear GENERIC 184This version of the manual describes @code{@value{AS}} configured to generate 185code for @value{TARGET} architectures. 186@end ifclear 187@end iftex 188 189@cindex invocation summary 190@cindex option summary 191@cindex summary of options 192Here is a brief summary of how to invoke @code{@value{AS}}. For details, 193@pxref{Invoking,,Comand-Line Options}. 194 195@c We don't use deffn and friends for the following because they seem 196@c to be limited to one line for the header. 197@smallexample 198@value{AS} [ -a[dhlns][=file] ] [ -D ] [ --defsym @var{sym}=@var{val} ] 199 [ -f ] [ --help ] [ -I @var{dir} ] [ -J ] [ -k ] [ -K ] [ -L ] 200 [ -o @var{objfile} ] [ -R ] [ --statistics ] [ -v ] [ -version ] 201 [ --version ] [ -W ] [ -w ] [ -x ] [ -Z ] 202@ifset A29K 203@c am29k has no machine-dependent assembler options 204@end ifset 205 206@ifset H8 207@c Hitachi family chips have no machine-dependent assembler options 208@end ifset 209@ifset HPPA 210@c HPPA has no machine-dependent assembler options (yet). 211@end ifset 212@ifset SPARC 213@c The order here is important. See c-sparc.texi. 214 [ -Av6 | -Av7 | -Av8 | -Asparclite | -Av9 | -Av9a ] 215 [ -xarch=v8plus | -xarch=v8plusa ] [ -bump ] 216@end ifset 217@ifset Z8000 218@c Z8000 has no machine-dependent assembler options 219@end ifset 220@ifset I960 221@c see md_parse_option in tc-i960.c 222 [ -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC ] 223 [ -b ] [ -no-relax ] 224@end ifset 225@ifset M680X0 226 [ -l ] [ -m68000 | -m68010 | -m68020 | ... ] 227@end ifset 228@ifset MIPS 229 [ -nocpp ] [ -EL ] [ -EB ] [ -G @var{num} ] [ -mcpu=@var{CPU} ] 230 [ -mips1 ] [ -mips2 ] [ -mips3 ] [ -m4650 ] [ -no-m4650 ] 231 [ --trap ] [ --break ] 232 [ --emulation=@var{name} ] 233@end ifset 234 [ -- | @var{files} @dots{} ] 235@end smallexample 236 237@table @code 238@item -a[dhlns] 239Turn on listings, in any of a variety of ways: 240 241@table @code 242@item -ad 243omit debugging directives 244 245@item -ah 246include high-level source 247 248@item -al 249include assembly 250 251@item -an 252omit forms processing 253 254@item -as 255include symbols 256 257@item =file 258set the name of the listing file 259@end table 260 261You may combine these options; for example, use @samp{-aln} for assembly 262listing without forms processing. The @samp{=file} option, if used, must be 263the last one. By itself, @samp{-a} defaults to @samp{-ahls}---that is, all 264listings turned on. 265 266@item -D 267Ignored. This option is accepted for script compatibility with calls to 268other assemblers. 269 270@item --defsym @var{sym}=@var{value} 271Define the symbol @var{sym} to be @var{value} before assembling the input file. 272@var{value} must be an integer constant. As in C, a leading @samp{0x} 273indicates a hexadecimal value, and a leading @samp{0} indicates an octal value. 274 275@item -f 276``fast''---skip whitespace and comment preprocessing (assume source is 277compiler output). 278 279@item --help 280Print a summary of the command line options and exit. 281 282@item -I @var{dir} 283Add directory @var{dir} to the search list for @code{.include} directives. 284 285@item -J 286Don't warn about signed overflow. 287 288@item -k 289Handle position independent code generated by @samp{gcc -fpic}. This 290option only actually has an effect in the Net- & OpenBSD environment, 291otherwise it's a no-op. 292 293@item -K 294@ifclear DIFF-TBL-KLUGE 295This option is accepted but has no effect on the @value{TARGET} family. 296@end ifclear 297@ifset DIFF-TBL-KLUGE 298Issue warnings when difference tables altered for long displacements. 299@end ifset 300 301@item -L 302Keep (in the symbol table) local symbols, starting with @samp{L}. 303 304@item -o @var{objfile} 305Name the object-file output from @code{@value{AS}} @var{objfile}. 306 307@item -R 308Fold the data section into the text section. 309 310@item --statistics 311Print the maximum space (in bytes) and total time (in seconds) used by 312assembly. 313 314@item -v 315@itemx -version 316Print the @code{as} version. 317 318@item --version 319Print the @code{as} version and exit. 320 321@item -W 322Suppress warning messages. 323 324@item -w 325Ignored. 326 327@item -x 328Ignored. 329 330@item -Z 331Generate an object file even after errors. 332 333@item -- | @var{files} @dots{} 334Standard input, or source files to assemble. 335 336@end table 337 338@ifset ARC 339The following options are available when @value{AS} is configured for 340an ARC processor. 341 342@table @code 343 344@cindex ARC endianness 345@cindex endianness, ARC 346@cindex big endian output, ARC 347@item -mbig-endian 348Generate ``big endian'' format output. 349 350@cindex little endian output, ARC 351@item -mlittle-endian 352Generate ``little endian'' format output. 353 354@end table 355@end ifset 356 357 358@ifset I960 359The following options are available when @value{AS} is configured for the 360Intel 80960 processor. 361 362@table @code 363@item -ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC 364Specify which variant of the 960 architecture is the target. 365 366@item -b 367Add code to collect statistics about branches taken. 368 369@item -no-relax 370Do not alter compare-and-branch instructions for long displacements; 371error if necessary. 372 373@end table 374@end ifset 375 376@ifset M680X0 377The following options are available when @value{AS} is configured for the 378Motorola 68000 series. 379 380@table @code 381 382@item -l 383Shorten references to undefined symbols, to one word instead of two. 384 385@item -m68000 | -m68008 | -m68010 | -m68020 | -m68030 | -m68040 | -m68060 386@itemx | -m68302 | -m68331 | -m68332 | -m68333 | -m68340 | -mcpu32 | -m5200 387Specify what processor in the 68000 family is the target. The default 388is normally the 68020, but this can be changed at configuration time. 389 390@item -m68881 | -m68882 | -mno-68881 | -mno-68882 391The target machine does (or does not) have a floating-point coprocessor. 392The default is to assume a coprocessor for 68020, 68030, and cpu32. Although 393the basic 68000 is not compatible with the 68881, a combination of the 394two can be specified, since it's possible to do emulation of the 395coprocessor instructions with the main processor. 396 397@item -m68851 | -mno-68851 398The target machine does (or does not) have a memory-management 399unit coprocessor. The default is to assume an MMU for 68020 and up. 400 401@end table 402@end ifset 403 404@ifset SPARC 405The following options are available when @code{@value{AS}} is configured 406for the SPARC architecture: 407 408@table @code 409@item -Av6 | -Av7 | -Av8 | -Asparclite | -Av9 | -Av9a 410Explicitly select a variant of the SPARC architecture. 411 412@item -xarch=v8plus | -xarch=v8plusa 413For compatibility with the Solaris v9 assembler. These options are 414equivalent to -Av9 and -Av9a, respectively. 415 416@item -bump 417Warn when the assembler switches to another architecture. 418@end table 419@end ifset 420 421@ifset MIPS 422The following options are available when @value{AS} is configured for 423a MIPS processor. 424 425@table @code 426@item -G @var{num} 427This option sets the largest size of an object that can be referenced 428implicitly with the @code{gp} register. It is only accepted for targets that 429use ECOFF format, such as a DECstation running Ultrix. The default value is 8. 430 431@cindex MIPS endianness 432@cindex endianness, MIPS 433@cindex big endian output, MIPS 434@item -EB 435Generate ``big endian'' format output. 436 437@cindex little endian output, MIPS 438@item -EL 439Generate ``little endian'' format output. 440 441@cindex MIPS ISA 442@item -mips1 443@itemx -mips2 444@itemx -mips3 445Generate code for a particular MIPS Instruction Set Architecture level. 446@samp{-mips1} corresponds to the @sc{r2000} and @sc{r3000} processors, 447@samp{-mips2} to the @sc{r6000} processor, and @samp{-mips3} to the @sc{r4000} 448processor. 449 450@item -m4650 451@item -no-m4650 452Generate code for the MIPS @sc{r4650} chip. This tells the assembler to accept 453the @samp{mad} and @samp{madu} instruction, and to not schedule @samp{nop} 454instructions around accesses to the @samp{HI} and @samp{LO} registers. 455@samp{-no-m4650} turns off this option. 456 457@item -mcpu=@var{CPU} 458Generate code for a particular MIPS cpu. This has little effect on the 459assembler, but it is passed by @code{@value{GCC}}. 460 461@cindex emulation 462@item --emulation=@var{name} 463This option causes @code{@value{AS}} to emulated @code{@value{AS}} configured 464for some other target, in all respects, including output format (choosing 465between ELF and ECOFF only), handling of pseudo-opcodes which may generate 466debugging information or store symbol table information, and default 467endianness. The available configuration names are: @samp{mipsecoff}, 468@samp{mipself}, @samp{mipslecoff}, @samp{mipsbecoff}, @samp{mipslelf}, 469@samp{mipsbelf}. The first two do not alter the default endianness from that 470of the primary target for which the assembler was configured; the others change 471the default to little- or big-endian as indicated by the @samp{b} or @samp{l} 472in the name. Using @samp{-EB} or @samp{-EL} will override the endianness 473selection in any case. 474 475This option is currently supported only when the primary target 476@code{@value{AS}} is configured for is a MIPS ELF or ECOFF target. 477Furthermore, the primary target or others specified with 478@samp{--enable-targets=@dots{}} at configuration time must include support for 479the other format, if both are to be available. For example, the Irix 5 480configuration includes support for both. 481 482Eventually, this option will support more configurations, with more 483fine-grained control over the assembler's behavior, and will be supported for 484more processors. 485 486@item -nocpp 487@code{@value{AS}} ignores this option. It is accepted for compatibility with 488the native tools. 489 490@need 900 491@item --trap 492@itemx --no-trap 493@itemx --break 494@itemx --no-break 495Control how to deal with multiplication overflow and division by zero. 496@samp{--trap} or @samp{--no-break} (which are synonyms) take a trap exception 497(and only work for Instruction Set Architecture level 2 and higher); 498@samp{--break} or @samp{--no-trap} (also synonyms, and the default) take a 499break exception. 500@end table 501@end ifset 502 503@menu 504* Manual:: Structure of this Manual 505* GNU Assembler:: @value{AS}, the GNU Assembler 506* Object Formats:: Object File Formats 507* Command Line:: Command Line 508* Input Files:: Input Files 509* Object:: Output (Object) File 510* Errors:: Error and Warning Messages 511@end menu 512 513@node Manual 514@section Structure of this Manual 515 516@cindex manual, structure and purpose 517This manual is intended to describe what you need to know to use 518@sc{gnu} @code{@value{AS}}. We cover the syntax expected in source files, including 519notation for symbols, constants, and expressions; the directives that 520@code{@value{AS}} understands; and of course how to invoke @code{@value{AS}}. 521 522@ifclear GENERIC 523We also cover special features in the @value{TARGET} 524configuration of @code{@value{AS}}, including assembler directives. 525@end ifclear 526@ifset GENERIC 527This manual also describes some of the machine-dependent features of 528various flavors of the assembler. 529@end ifset 530 531@cindex machine instructions (not covered) 532On the other hand, this manual is @emph{not} intended as an introduction 533to programming in assembly language---let alone programming in general! 534In a similar vein, we make no attempt to introduce the machine 535architecture; we do @emph{not} describe the instruction set, standard 536mnemonics, registers or addressing modes that are standard to a 537particular architecture. 538@ifset GENERIC 539You may want to consult the manufacturer's 540machine architecture manual for this information. 541@end ifset 542@ifclear GENERIC 543@ifset H8/300 544For information on the H8/300 machine instruction set, see @cite{H8/300 545Series Programming Manual} (Hitachi ADE--602--025). For the H8/300H, 546see @cite{H8/300H Series Programming Manual} (Hitachi). 547@end ifset 548@ifset H8/500 549For information on the H8/500 machine instruction set, see @cite{H8/500 550Series Programming Manual} (Hitachi M21T001). 551@end ifset 552@ifset SH 553For information on the Hitachi SH machine instruction set, see 554@cite{SH-Microcomputer User's Manual} (Hitachi Micro Systems, Inc.). 555@end ifset 556@ifset Z8000 557For information on the Z8000 machine instruction set, see @cite{Z8000 CPU Technical Manual} 558@end ifset 559@end ifclear 560 561@c I think this is premature---doc@cygnus.com, 17jan1991 562@ignore 563Throughout this manual, we assume that you are running @dfn{GNU}, 564the portable operating system from the @dfn{Free Software 565Foundation, Inc.}. This restricts our attention to certain kinds of 566computer (in particular, the kinds of computers that @sc{gnu} can run on); 567once this assumption is granted examples and definitions need less 568qualification. 569 570@code{@value{AS}} is part of a team of programs that turn a high-level 571human-readable series of instructions into a low-level 572computer-readable series of instructions. Different versions of 573@code{@value{AS}} are used for different kinds of computer. 574@end ignore 575 576@c There used to be a section "Terminology" here, which defined 577@c "contents", "byte", "word", and "long". Defining "word" to any 578@c particular size is confusing when the .word directive may generate 16 579@c bits on one machine and 32 bits on another; in general, for the user 580@c version of this manual, none of these terms seem essential to define. 581@c They were used very little even in the former draft of the manual; 582@c this draft makes an effort to avoid them (except in names of 583@c directives). 584 585@node GNU Assembler 586@section @value{AS}, the GNU Assembler 587 588@sc{gnu} @code{as} is really a family of assemblers. 589@ifclear GENERIC 590This manual describes @code{@value{AS}}, a member of that family which is 591configured for the @value{TARGET} architectures. 592@end ifclear 593If you use (or have used) the @sc{gnu} assembler on one architecture, you 594should find a fairly similar environment when you use it on another 595architecture. Each version has much in common with the others, 596including object file formats, most assembler directives (often called 597@dfn{pseudo-ops}) and assembler syntax.@refill 598 599@cindex purpose of @sc{gnu} @code{@value{AS}} 600@code{@value{AS}} is primarily intended to assemble the output of the 601@sc{gnu} C compiler @code{@value{GCC}} for use by the linker 602@code{@value{LD}}. Nevertheless, we've tried to make @code{@value{AS}} 603assemble correctly everything that other assemblers for the same 604machine would assemble. 605@ifset VAX 606Any exceptions are documented explicitly (@pxref{Machine Dependencies}). 607@end ifset 608@ifset M680X0 609@c This remark should appear in generic version of manual; assumption 610@c here is that generic version sets M680x0. 611This doesn't mean @code{@value{AS}} always uses the same syntax as another 612assembler for the same architecture; for example, we know of several 613incompatible versions of 680x0 assembly language syntax. 614@end ifset 615 616Unlike older assemblers, @code{@value{AS}} is designed to assemble a source 617program in one pass of the source file. This has a subtle impact on the 618@kbd{.org} directive (@pxref{Org,,@code{.org}}). 619 620@node Object Formats 621@section Object File Formats 622 623@cindex object file format 624The @sc{gnu} assembler can be configured to produce several alternative 625object file formats. For the most part, this does not affect how you 626write assembly language programs; but directives for debugging symbols 627are typically different in different file formats. @xref{Symbol 628Attributes,,Symbol Attributes}. 629@ifclear GENERIC 630@ifclear MULTI-OBJ 631On the @value{TARGET}, @code{@value{AS}} is configured to produce 632@value{OBJ-NAME} format object files. 633@end ifclear 634@c The following should exhaust all configs that set MULTI-OBJ, ideally 635@ifset A29K 636On the @value{TARGET}, @code{@value{AS}} can be configured to produce either 637@code{a.out} or COFF format object files. 638@end ifset 639@ifset I960 640On the @value{TARGET}, @code{@value{AS}} can be configured to produce either 641@code{b.out} or COFF format object files. 642@end ifset 643@ifset HPPA 644On the @value{TARGET}, @code{@value{AS}} can be configured to produce either 645SOM or ELF format object files. 646@end ifset 647@end ifclear 648 649@node Command Line 650@section Command Line 651 652@cindex command line conventions 653After the program name @code{@value{AS}}, the command line may contain 654options and file names. Options may appear in any order, and may be 655before, after, or between file names. The order of file names is 656significant. 657 658@cindex standard input, as input file 659@kindex -- 660@file{--} (two hyphens) by itself names the standard input file 661explicitly, as one of the files for @code{@value{AS}} to assemble. 662 663@cindex options, command line 664Except for @samp{--} any command line argument that begins with a 665hyphen (@samp{-}) is an option. Each option changes the behavior of 666@code{@value{AS}}. No option changes the way another option works. An 667option is a @samp{-} followed by one or more letters; the case of 668the letter is important. All options are optional. 669 670Some options expect exactly one file name to follow them. The file 671name may either immediately follow the option's letter (compatible 672with older assemblers) or it may be the next command argument (@sc{gnu} 673standard). These two command lines are equivalent: 674 675@smallexample 676@value{AS} -o my-object-file.o mumble.s 677@value{AS} -omy-object-file.o mumble.s 678@end smallexample 679 680@node Input Files 681@section Input Files 682 683@cindex input 684@cindex source program 685@cindex files, input 686We use the phrase @dfn{source program}, abbreviated @dfn{source}, to 687describe the program input to one run of @code{@value{AS}}. The program may 688be in one or more files; how the source is partitioned into files 689doesn't change the meaning of the source. 690 691@c I added "con" prefix to "catenation" just to prove I can overcome my 692@c APL training... doc@cygnus.com 693The source program is a concatenation of the text in all the files, in the 694order specified. 695 696Each time you run @code{@value{AS}} it assembles exactly one source 697program. The source program is made up of one or more files. 698(The standard input is also a file.) 699 700You give @code{@value{AS}} a command line that has zero or more input file 701names. The input files are read (from left file name to right). A 702command line argument (in any position) that has no special meaning 703is taken to be an input file name. 704 705If you give @code{@value{AS}} no file names it attempts to read one input file 706from the @code{@value{AS}} standard input, which is normally your terminal. You 707may have to type @key{ctl-D} to tell @code{@value{AS}} there is no more program 708to assemble. 709 710Use @samp{--} if you need to explicitly name the standard input file 711in your command line. 712 713If the source is empty, @code{@value{AS}} produces a small, empty object 714file. 715 716@subheading Filenames and Line-numbers 717 718@cindex input file linenumbers 719@cindex line numbers, in input files 720There are two ways of locating a line in the input file (or files) and 721either may be used in reporting error messages. One way refers to a line 722number in a physical file; the other refers to a line number in a 723``logical'' file. @xref{Errors, ,Error and Warning Messages}. 724 725@dfn{Physical files} are those files named in the command line given 726to @code{@value{AS}}. 727 728@dfn{Logical files} are simply names declared explicitly by assembler 729directives; they bear no relation to physical files. Logical file names 730help error messages reflect the original source file, when @code{@value{AS}} 731source is itself synthesized from other files. 732@xref{App-File,,@code{.app-file}}. 733 734@node Object 735@section Output (Object) File 736 737@cindex object file 738@cindex output file 739@kindex a.out 740@kindex .o 741Every time you run @code{@value{AS}} it produces an output file, which is 742your assembly language program translated into numbers. This file 743is the object file. Its default name is 744@ifclear BOUT 745@code{a.out}. 746@end ifclear 747@ifset BOUT 748@ifset GENERIC 749@code{a.out}, or 750@end ifset 751@code{b.out} when @code{@value{AS}} is configured for the Intel 80960. 752@end ifset 753You can give it another name by using the @code{-o} option. Conventionally, 754object file names end with @file{.o}. The default name is used for historical 755reasons: older assemblers were capable of assembling self-contained programs 756directly into a runnable program. (For some formats, this isn't currently 757possible, but it can be done for the @code{a.out} format.) 758 759@cindex linker 760@kindex ld 761The object file is meant for input to the linker @code{@value{LD}}. It contains 762assembled program code, information to help @code{@value{LD}} integrate 763the assembled program into a runnable file, and (optionally) symbolic 764information for the debugger. 765 766@c link above to some info file(s) like the description of a.out. 767@c don't forget to describe @sc{gnu} info as well as Unix lossage. 768 769@node Errors 770@section Error and Warning Messages 771 772@cindex error messsages 773@cindex warning messages 774@cindex messages from @code{@value{AS}} 775@code{@value{AS}} may write warnings and error messages to the standard error 776file (usually your terminal). This should not happen when a compiler 777runs @code{@value{AS}} automatically. Warnings report an assumption made so 778that @code{@value{AS}} could keep assembling a flawed program; errors report a 779grave problem that stops the assembly. 780 781@cindex format of warning messages 782Warning messages have the format 783 784@smallexample 785file_name:@b{NNN}:Warning Message Text 786@end smallexample 787 788@noindent 789@cindex line numbers, in warnings/errors 790(where @b{NNN} is a line number). If a logical file name has been given 791(@pxref{App-File,,@code{.app-file}}) it is used for the filename, 792otherwise the name of the current input file is used. If a logical line 793number was given 794@ifset GENERIC 795(@pxref{Line,,@code{.line}}) 796@end ifset 797@ifclear GENERIC 798@ifclear A29K 799(@pxref{Line,,@code{.line}}) 800@end ifclear 801@ifset A29K 802(@pxref{Ln,,@code{.ln}}) 803@end ifset 804@end ifclear 805then it is used to calculate the number printed, 806otherwise the actual line in the current source file is printed. The 807message text is intended to be self explanatory (in the grand Unix 808tradition). 809 810@cindex format of error messages 811Error messages have the format 812@smallexample 813file_name:@b{NNN}:FATAL:Error Message Text 814@end smallexample 815The file name and line number are derived as for warning 816messages. The actual message text may be rather less explanatory 817because many of them aren't supposed to happen. 818 819@node Invoking 820@chapter Command-Line Options 821 822@cindex options, all versions of @code{@value{AS}} 823This chapter describes command-line options available in @emph{all} 824versions of the @sc{gnu} assembler; @pxref{Machine Dependencies}, for options specific 825@ifclear GENERIC 826to the @value{TARGET}. 827@end ifclear 828@ifset GENERIC 829to particular machine architectures. 830@end ifset 831 832If you are invoking @code{@value{AS}} via the @sc{gnu} C compiler (version 2), you 833can use the @samp{-Wa} option to pass arguments through to the 834assembler. The assembler arguments must be separated from each other 835(and the @samp{-Wa}) by commas. For example: 836 837@smallexample 838gcc -c -g -O -Wa,-alh,-L file.c 839@end smallexample 840 841@noindent 842emits a listing to standard output with high-level 843and assembly source. 844 845Usually you do not need to use this @samp{-Wa} mechanism, since many compiler 846command-line options are automatically passed to the assembler by the compiler. 847(You can call the @sc{gnu} compiler driver with the @samp{-v} option to see 848precisely what options it passes to each compilation pass, including the 849assembler.) 850 851@menu 852* a:: -a[dhlns] enable listings 853* D:: -D for compatibility 854* f:: -f to work faster 855* I:: -I for .include search path 856@ifclear DIFF-TBL-KLUGE 857* K:: -K for compatibility 858@end ifclear 859@ifset DIFF-TBL-KLUGE 860* K:: -K for difference tables 861@end ifset 862 863* L:: -L to retain local labels 864* M:: -M or --mri to assemble in MRI compatibility mode 865* o:: -o to name the object file 866* R:: -R to join data and text sections 867* statistics:: --statistics to see statistics about assembly 868* v:: -v to announce version 869* W:: -W to suppress warnings 870* Z:: -Z to make object file even after errors 871@end menu 872 873@node a 874@section Enable Listings: @code{-a[dhlns]} 875 876@kindex -a 877@kindex -ad 878@kindex -ah 879@kindex -al 880@kindex -an 881@kindex -as 882@cindex listings, enabling 883@cindex assembly listings, enabling 884 885These options enable listing output from the assembler. By itself, 886@samp{-a} requests high-level, assembly, and symbols listing. 887You can use other letters to select specific options for the list: 888@samp{-ah} requests a high-level language listing, 889@samp{-al} requests an output-program assembly listing, and 890@samp{-as} requests a symbol table listing. 891High-level listings require that a compiler debugging option like 892@samp{-g} be used, and that assembly listings (@samp{-al}) be requested 893also. 894 895Use the @samp{-ad} option to omit debugging directives from the 896listing. 897 898Once you have specified one of these options, you can further control 899listing output and its appearance using the directives @code{.list}, 900@code{.nolist}, @code{.psize}, @code{.eject}, @code{.title}, and 901@code{.sbttl}. 902The @samp{-an} option turns off all forms processing. 903If you do not request listing output with one of the @samp{-a} options, the 904listing-control directives have no effect. 905 906The letters after @samp{-a} may be combined into one option, 907@emph{e.g.}, @samp{-aln}. 908 909@node D 910@section @code{-D} 911 912@kindex -D 913This option has no effect whatsoever, but it is accepted to make it more 914likely that scripts written for other assemblers also work with 915@code{@value{AS}}. 916 917@node f 918@section Work Faster: @code{-f} 919 920@kindex -f 921@cindex trusted compiler 922@cindex faster processing (@code{-f}) 923@samp{-f} should only be used when assembling programs written by a 924(trusted) compiler. @samp{-f} stops the assembler from doing whitespace 925and comment preprocessing on 926the input file(s) before assembling them. @xref{Preprocessing, 927,Preprocessing}. 928 929@quotation 930@emph{Warning:} if you use @samp{-f} when the files actually need to be 931preprocessed (if they contain comments, for example), @code{@value{AS}} does 932not work correctly. 933@end quotation 934 935@node I 936@section @code{.include} search path: @code{-I} @var{path} 937 938@kindex -I @var{path} 939@cindex paths for @code{.include} 940@cindex search path for @code{.include} 941@cindex @code{include} directive search path 942Use this option to add a @var{path} to the list of directories 943@code{@value{AS}} searches for files specified in @code{.include} 944directives (@pxref{Include,,@code{.include}}). You may use @code{-I} as 945many times as necessary to include a variety of paths. The current 946working directory is always searched first; after that, @code{@value{AS}} 947searches any @samp{-I} directories in the same order as they were 948specified (left to right) on the command line. 949 950@node K 951@section Difference Tables: @code{-K} 952 953@kindex -K 954@ifclear DIFF-TBL-KLUGE 955On the @value{TARGET} family, this option is allowed, but has no effect. It is 956permitted for compatibility with the @sc{gnu} assembler on other platforms, 957where it can be used to warn when the assembler alters the machine code 958generated for @samp{.word} directives in difference tables. The @value{TARGET} 959family does not have the addressing limitations that sometimes lead to this 960alteration on other platforms. 961@end ifclear 962 963@ifset DIFF-TBL-KLUGE 964@cindex difference tables, warning 965@cindex warning for altered difference tables 966@code{@value{AS}} sometimes alters the code emitted for directives of the form 967@samp{.word @var{sym1}-@var{sym2}}; @pxref{Word,,@code{.word}}. 968You can use the @samp{-K} option if you want a warning issued when this 969is done. 970@end ifset 971 972@node L 973@section Include Local Labels: @code{-L} 974 975@kindex -L 976@cindex local labels, retaining in output 977Labels beginning with @samp{L} (upper case only) are called @dfn{local 978labels}. @xref{Symbol Names}. Normally you do not see such labels when 979debugging, because they are intended for the use of programs (like 980compilers) that compose assembler programs, not for your notice. 981Normally both @code{@value{AS}} and @code{@value{LD}} discard such labels, so you do not 982normally debug with them. 983 984This option tells @code{@value{AS}} to retain those @samp{L@dots{}} symbols 985in the object file. Usually if you do this you also tell the linker 986@code{@value{LD}} to preserve symbols whose names begin with @samp{L}. 987 988By default, a local label is any label beginning with @samp{L}, but each 989target is allowed to redefine the local label prefix. 990@ifset HPPA 991On the HPPA local labels begin with @samp{L$}. 992@end ifset 993 994@node M 995@section Assemble in MRI Compatibility Mode: @code{-M} 996 997@kindex -M 998@cindex MRI compatibility mode 999The @code{-M} or @code{--mri} option selects MRI compatibility mode. This 1000changes the syntax and pseudo-op handling of @code{@value{AS}} to make it 1001compatible with the @code{ASM68K} or the @code{ASM960} (depending upon the 1002configured target) assembler from Microtec Research. The exact nature of the 1003MRI syntax will not be documented here; see the MRI manuals for more 1004information. The purpose of this option is to permit assembling existing MRI 1005assembler code using @code{@value{AS}}. 1006 1007The MRI compatibility is not complete. Certain operations of the MRI assembler 1008depend upon its object file format, and can not be supported using other object 1009file formats. Supporting these would require enhancing each object file format 1010individually. These are: 1011 1012@itemize @bullet 1013@item global symbols in common section 1014 1015The m68k MRI assembler supports common sections which are merged by the linker. 1016Other object file formats do not support this. @code{@value{AS}} handles 1017common sections by treating them as a single common symbol. It permits local 1018symbols to be defined within a common section, but it can not support global 1019symbols, since it has no way to describe them. 1020 1021@item complex relocations 1022 1023The MRI assemblers support relocations against a negated section address, and 1024relocations which combine the start addresses of two or more sections. These 1025are not support by other object file formats. 1026 1027@item @code{END} pseudo-op specifying start address 1028 1029The MRI @code{END} pseudo-op permits the specification of a start address. 1030This is not supported by other object file formats. The start address may 1031instead be specified using the @code{-e} option to the linker, or in a linker 1032script. 1033 1034@item @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops 1035 1036The MRI @code{IDNT}, @code{.ident} and @code{NAME} pseudo-ops assign a module 1037name to the output file. This is not supported by other object file formats. 1038 1039@item @code{ORG} pseudo-op 1040 1041The m68k MRI @code{ORG} pseudo-op begins an absolute section at a given 1042address. This differs from the usual @code{@value{AS}} @code{.org} pseudo-op, 1043which changes the location within the current section. Absolute sections are 1044not supported by other object file formats. The address of a section may be 1045assigned within a linker script. 1046@end itemize 1047 1048There are some other features of the MRI assembler which are not supported by 1049@code{@value{AS}}, typically either because they are difficult or because they 1050seem of little consequence. Some of these may be supported in future releases. 1051 1052@itemize @bullet 1053 1054@item EBCDIC strings 1055 1056EBCDIC strings are not supported. 1057 1058@item packed binary coded decimal 1059 1060Packed binary coded decimal is not supported. This means that the @code{DC.P} 1061and @code{DCB.P} pseudo-ops are not supported. 1062 1063@item @code{FEQU} pseudo-op 1064 1065The m68k @code{FEQU} pseudo-op is not supported. 1066 1067@item @code{NOOBJ} pseudo-op 1068 1069The m68k @code{NOOBJ} pseudo-op is not supported. 1070 1071@item @code{OPT} branch control options 1072 1073The m68k @code{OPT} branch control options---@code{B}, @code{BRS}, @code{BRB}, 1074@code{BRL}, and @code{BRW}---are ignored. @code{@value{AS}} automatically 1075relaxes all branches, whether forward or backward, to an appropriate size, so 1076these options serve no purpose. 1077 1078@item @code{OPT} list control options 1079 1080The following m68k @code{OPT} list control options are ignored: @code{C}, 1081@code{CEX}, @code{CL}, @code{CRE}, @code{E}, @code{G}, @code{I}, @code{M}, 1082@code{MEX}, @code{MC}, @code{MD}, @code{X}. 1083 1084@item other @code{OPT} options 1085 1086The following m68k @code{OPT} options are ignored: @code{NEST}, @code{O}, 1087@code{OLD}, @code{OP}, @code{P}, @code{PCO}, @code{PCR}, @code{PCS}, @code{R}. 1088 1089@item @code{OPT} @code{D} option is default 1090 1091The m68k @code{OPT} @code{D} option is the default, unlike the MRI assembler. 1092@code{OPT NOD} may be used to turn it off. 1093 1094@item @code{XREF} pseudo-op. 1095 1096The m68k @code{XREF} pseudo-op is ignored. 1097 1098@item @code{.debug} pseudo-op 1099 1100The i960 @code{.debug} pseudo-op is not supported. 1101 1102@item @code{.extended} pseudo-op 1103 1104The i960 @code{.extended} pseudo-op is not supported. 1105 1106@item @code{.list} pseudo-op. 1107 1108The various options of the i960 @code{.list} pseudo-op are not supported. 1109 1110@item @code{.optimize} pseudo-op 1111 1112The i960 @code{.optimize} pseudo-op is not supported. 1113 1114@item @code{.output} pseudo-op 1115 1116The i960 @code{.output} pseudo-op is not supported. 1117 1118@item @code{.setreal} pseudo-op 1119 1120The i960 @code{.setreal} pseudo-op is not supported. 1121 1122@end itemize 1123 1124@node o 1125@section Name the Object File: @code{-o} 1126 1127@kindex -o 1128@cindex naming object file 1129@cindex object file name 1130There is always one object file output when you run @code{@value{AS}}. By 1131default it has the name 1132@ifset GENERIC 1133@ifset I960 1134@file{a.out} (or @file{b.out}, for Intel 960 targets only). 1135@end ifset 1136@ifclear I960 1137@file{a.out}. 1138@end ifclear 1139@end ifset 1140@ifclear GENERIC 1141@ifset I960 1142@file{b.out}. 1143@end ifset 1144@ifclear I960 1145@file{a.out}. 1146@end ifclear 1147@end ifclear 1148You use this option (which takes exactly one filename) to give the 1149object file a different name. 1150 1151Whatever the object file is called, @code{@value{AS}} overwrites any 1152existing file of the same name. 1153 1154@node R 1155@section Join Data and Text Sections: @code{-R} 1156 1157@kindex -R 1158@cindex data and text sections, joining 1159@cindex text and data sections, joining 1160@cindex joining text and data sections 1161@cindex merging text and data sections 1162@code{-R} tells @code{@value{AS}} to write the object file as if all 1163data-section data lives in the text section. This is only done at 1164the very last moment: your binary data are the same, but data 1165section parts are relocated differently. The data section part of 1166your object file is zero bytes long because all its bytes are 1167appended to the text section. (@xref{Sections,,Sections and Relocation}.) 1168 1169When you specify @code{-R} it would be possible to generate shorter 1170address displacements (because we do not have to cross between text and 1171data section). We refrain from doing this simply for compatibility with 1172older versions of @code{@value{AS}}. In future, @code{-R} may work this way. 1173 1174@ifset COFF 1175When @code{@value{AS}} is configured for COFF output, 1176this option is only useful if you use sections named @samp{.text} and 1177@samp{.data}. 1178@end ifset 1179 1180@ifset HPPA 1181@code{-R} is not supported for any of the HPPA targets. Using 1182@code{-R} generates a warning from @code{@value{AS}}. 1183@end ifset 1184 1185@node statistics 1186@section Display Assembly Statistics: @code{--statistics} 1187 1188@kindex --statistics 1189@cindex statistics, about assembly 1190@cindex time, total for assembly 1191@cindex space used, maximum for assembly 1192Use @samp{--statistics} to display two statistics about the resources used by 1193@code{@value{AS}}: the maximum amount of space allocated during the assembly 1194(in bytes), and the total execution time taken for the assembly (in @sc{cpu} 1195seconds). 1196 1197@node v 1198@section Announce Version: @code{-v} 1199 1200@kindex -v 1201@kindex -version 1202@cindex @code{@value{AS}} version 1203@cindex version of @code{@value{AS}} 1204You can find out what version of as is running by including the 1205option @samp{-v} (which you can also spell as @samp{-version}) on the 1206command line. 1207 1208@node W 1209@section Suppress Warnings: @code{-W} 1210 1211@kindex -W 1212@cindex suppressing warnings 1213@cindex warnings, suppressing 1214@code{@value{AS}} should never give a warning or error message when 1215assembling compiler output. But programs written by people often 1216cause @code{@value{AS}} to give a warning that a particular assumption was 1217made. All such warnings are directed to the standard error file. 1218If you use this option, no warnings are issued. This option only 1219affects the warning messages: it does not change any particular of how 1220@code{@value{AS}} assembles your file. Errors, which stop the assembly, are 1221still reported. 1222 1223@node Z 1224@section Generate Object File in Spite of Errors: @code{-Z} 1225@cindex object file, after errors 1226@cindex errors, continuing after 1227After an error message, @code{@value{AS}} normally produces no output. If for 1228some reason you are interested in object file output even after 1229@code{@value{AS}} gives an error message on your program, use the @samp{-Z} 1230option. If there are any errors, @code{@value{AS}} continues anyways, and 1231writes an object file after a final warning message of the form @samp{@var{n} 1232errors, @var{m} warnings, generating bad object file.} 1233 1234@node Syntax 1235@chapter Syntax 1236 1237@cindex machine-independent syntax 1238@cindex syntax, machine-independent 1239This chapter describes the machine-independent syntax allowed in a 1240source file. @code{@value{AS}} syntax is similar to what many other 1241assemblers use; it is inspired by the BSD 4.2 1242@ifclear VAX 1243assembler. 1244@end ifclear 1245@ifset VAX 1246assembler, except that @code{@value{AS}} does not assemble Vax bit-fields. 1247@end ifset 1248 1249@menu 1250* Preprocessing:: Preprocessing 1251* Whitespace:: Whitespace 1252* Comments:: Comments 1253* Symbol Intro:: Symbols 1254* Statements:: Statements 1255* Constants:: Constants 1256@end menu 1257 1258@node Preprocessing 1259@section Preprocessing 1260 1261@cindex preprocessing 1262The @code{@value{AS}} internal preprocessor: 1263@itemize @bullet 1264@cindex whitespace, removed by preprocessor 1265@item 1266adjusts and removes extra whitespace. It leaves one space or tab before 1267the keywords on a line, and turns any other whitespace on the line into 1268a single space. 1269 1270@cindex comments, removed by preprocessor 1271@item 1272removes all comments, replacing them with a single space, or an 1273appropriate number of newlines. 1274 1275@cindex constants, converted by preprocessor 1276@item 1277converts character constants into the appropriate numeric values. 1278@end itemize 1279 1280It does not do macro processing, include file handling, or 1281anything else you may get from your C compiler's preprocessor. You can 1282do include file processing with the @code{.include} directive 1283(@pxref{Include,,@code{.include}}). You can use the @sc{gnu} C compiler driver 1284to get other ``CPP'' style preprocessing, by giving the input file a 1285@samp{.S} suffix. @xref{Overall Options,, Options Controlling the Kind of 1286Output, gcc.info, Using GNU CC}. 1287 1288Excess whitespace, comments, and character constants 1289cannot be used in the portions of the input text that are not 1290preprocessed. 1291 1292@cindex turning preprocessing on and off 1293@cindex preprocessing, turning on and off 1294@kindex #NO_APP 1295@kindex #APP 1296If the first line of an input file is @code{#NO_APP} or if you use the 1297@samp{-f} option, whitespace and comments are not removed from the input file. 1298Within an input file, you can ask for whitespace and comment removal in 1299specific portions of the by putting a line that says @code{#APP} before the 1300text that may contain whitespace or comments, and putting a line that says 1301@code{#NO_APP} after this text. This feature is mainly intend to support 1302@code{asm} statements in compilers whose output is otherwise free of comments 1303and whitespace. 1304 1305@node Whitespace 1306@section Whitespace 1307 1308@cindex whitespace 1309@dfn{Whitespace} is one or more blanks or tabs, in any order. 1310Whitespace is used to separate symbols, and to make programs neater for 1311people to read. Unless within character constants 1312(@pxref{Characters,,Character Constants}), any whitespace means the same 1313as exactly one space. 1314 1315@node Comments 1316@section Comments 1317 1318@cindex comments 1319There are two ways of rendering comments to @code{@value{AS}}. In both 1320cases the comment is equivalent to one space. 1321 1322Anything from @samp{/*} through the next @samp{*/} is a comment. 1323This means you may not nest these comments. 1324 1325@smallexample 1326/* 1327 The only way to include a newline ('\n') in a comment 1328 is to use this sort of comment. 1329*/ 1330 1331/* This sort of comment does not nest. */ 1332@end smallexample 1333 1334@cindex line comment character 1335Anything from the @dfn{line comment} character to the next newline 1336is considered a comment and is ignored. The line comment character is 1337@ifset A29K 1338@samp{;} for the AMD 29K family; 1339@end ifset 1340@ifset H8/300 1341@samp{;} for the H8/300 family; 1342@end ifset 1343@ifset H8/500 1344@samp{!} for the H8/500 family; 1345@end ifset 1346@ifset HPPA 1347@samp{;} for the HPPA; 1348@end ifset 1349@ifset I960 1350@samp{#} on the i960; 1351@end ifset 1352@ifset SH 1353@samp{!} for the Hitachi SH; 1354@end ifset 1355@ifset SPARC 1356@samp{!} on the SPARC; 1357@end ifset 1358@ifset M680X0 1359@samp{|} on the 680x0; 1360@end ifset 1361@ifset VAX 1362@samp{#} on the Vax; 1363@end ifset 1364@ifset Z8000 1365@samp{!} for the Z8000; 1366@end ifset 1367see @ref{Machine Dependencies}. @refill 1368@c FIXME What about i386, m88k, i860? 1369 1370@ifset GENERIC 1371On some machines there are two different line comment characters. One 1372character only begins a comment if it is the first non-whitespace character on 1373a line, while the other always begins a comment. 1374@end ifset 1375 1376@kindex # 1377@cindex lines starting with @code{#} 1378@cindex logical line numbers 1379To be compatible with past assemblers, lines that begin with @samp{#} have a 1380special interpretation. Following the @samp{#} should be an absolute 1381expression (@pxref{Expressions}): the logical line number of the @emph{next} 1382line. Then a string (@pxref{Strings,, Strings}) is allowed: if present it is a 1383new logical file name. The rest of the line, if any, should be whitespace. 1384 1385If the first non-whitespace characters on the line are not numeric, 1386the line is ignored. (Just like a comment.) 1387 1388@smallexample 1389 # This is an ordinary comment. 1390# 42-6 "new_file_name" # New logical file name 1391 # This is logical line # 36. 1392@end smallexample 1393This feature is deprecated, and may disappear from future versions 1394of @code{@value{AS}}. 1395 1396@node Symbol Intro 1397@section Symbols 1398 1399@cindex characters used in symbols 1400@ifclear SPECIAL-SYMS 1401A @dfn{symbol} is one or more characters chosen from the set of all 1402letters (both upper and lower case), digits and the three characters 1403@samp{_.$}. 1404@end ifclear 1405@ifset SPECIAL-SYMS 1406@ifclear GENERIC 1407@ifset H8 1408A @dfn{symbol} is one or more characters chosen from the set of all 1409letters (both upper and lower case), digits and the three characters 1410@samp{._$}. (Save that, on the H8/300 only, you may not use @samp{$} in 1411symbol names.) 1412@end ifset 1413@end ifclear 1414@end ifset 1415@ifset GENERIC 1416On most machines, you can also use @code{$} in symbol names; exceptions 1417are noted in @ref{Machine Dependencies}. 1418@end ifset 1419No symbol may begin with a digit. Case is significant. 1420There is no length limit: all characters are significant. Symbols are 1421delimited by characters not in that set, or by the beginning of a file 1422(since the source program must end with a newline, the end of a file is 1423not a possible symbol delimiter). @xref{Symbols}. 1424@cindex length of symbols 1425 1426@node Statements 1427@section Statements 1428 1429@cindex statements, structure of 1430@cindex line separator character 1431@cindex statement separator character 1432@ifclear GENERIC 1433@ifclear abnormal-separator 1434A @dfn{statement} ends at a newline character (@samp{\n}) or at a 1435semicolon (@samp{;}). The newline or semicolon is considered part of 1436the preceding statement. Newlines and semicolons within character 1437constants are an exception: they do not end statements. 1438@end ifclear 1439@ifset abnormal-separator 1440@ifset A29K 1441A @dfn{statement} ends at a newline character (@samp{\n}) or an ``at'' 1442sign (@samp{@@}). The newline or at sign is considered part of the 1443preceding statement. Newlines and at signs within character constants 1444are an exception: they do not end statements. 1445@end ifset 1446@ifset HPPA 1447A @dfn{statement} ends at a newline character (@samp{\n}) or an exclamation 1448point (@samp{!}). The newline or exclamation point is considered part of the 1449preceding statement. Newlines and exclamation points within character 1450constants are an exception: they do not end statements. 1451@end ifset 1452@ifset H8 1453A @dfn{statement} ends at a newline character (@samp{\n}); or (for the 1454H8/300) a dollar sign (@samp{$}); or (for the 1455Hitachi-SH or the 1456H8/500) a semicolon 1457(@samp{;}). The newline or separator character is considered part of 1458the preceding statement. Newlines and separators within character 1459constants are an exception: they do not end statements. 1460@end ifset 1461@end ifset 1462@end ifclear 1463@ifset GENERIC 1464A @dfn{statement} ends at a newline character (@samp{\n}) or line 1465separator character. (The line separator is usually @samp{;}, unless 1466this conflicts with the comment character; @pxref{Machine Dependencies}.) The 1467newline or separator character is considered part of the preceding 1468statement. Newlines and separators within character constants are an 1469exception: they do not end statements. 1470@end ifset 1471 1472@cindex newline, required at file end 1473@cindex EOF, newline must precede 1474It is an error to end any statement with end-of-file: the last 1475character of any input file should be a newline.@refill 1476 1477@cindex continuing statements 1478@cindex multi-line statements 1479@cindex statement on multiple lines 1480You may write a statement on more than one line if you put a 1481backslash (@kbd{\}) immediately in front of any newlines within the 1482statement. When @code{@value{AS}} reads a backslashed newline both 1483characters are ignored. You can even put backslashed newlines in 1484the middle of symbol names without changing the meaning of your 1485source program. 1486 1487An empty statement is allowed, and may include whitespace. It is ignored. 1488 1489@cindex instructions and directives 1490@cindex directives and instructions 1491@c "key symbol" is not used elsewhere in the document; seems pedantic to 1492@c @defn{} it in that case, as was done previously... doc@cygnus.com, 1493@c 13feb91. 1494A statement begins with zero or more labels, optionally followed by a 1495key symbol which determines what kind of statement it is. The key 1496symbol determines the syntax of the rest of the statement. If the 1497symbol begins with a dot @samp{.} then the statement is an assembler 1498directive: typically valid for any computer. If the symbol begins with 1499a letter the statement is an assembly language @dfn{instruction}: it 1500assembles into a machine language instruction. 1501@ifset GENERIC 1502Different versions of @code{@value{AS}} for different computers 1503recognize different instructions. In fact, the same symbol may 1504represent a different instruction in a different computer's assembly 1505language.@refill 1506@end ifset 1507 1508@cindex @code{:} (label) 1509@cindex label (@code{:}) 1510A label is a symbol immediately followed by a colon (@code{:}). 1511Whitespace before a label or after a colon is permitted, but you may not 1512have whitespace between a label's symbol and its colon. @xref{Labels}. 1513 1514@ifset HPPA 1515For HPPA targets, labels need not be immediately followed by a colon, but 1516the definition of a label must begin in column zero. This also implies that 1517only one label may be defined on each line. 1518@end ifset 1519 1520@smallexample 1521label: .directive followed by something 1522another_label: # This is an empty statement. 1523 instruction operand_1, operand_2, @dots{} 1524@end smallexample 1525 1526@node Constants 1527@section Constants 1528 1529@cindex constants 1530A constant is a number, written so that its value is known by 1531inspection, without knowing any context. Like this: 1532@smallexample 1533@group 1534.byte 74, 0112, 092, 0x4A, 0X4a, 'J, '\J # All the same value. 1535.ascii "Ring the bell\7" # A string constant. 1536.octa 0x123456789abcdef0123456789ABCDEF0 # A bignum. 1537.float 0f-314159265358979323846264338327\ 153895028841971.693993751E-40 # - pi, a flonum. 1539@end group 1540@end smallexample 1541 1542@menu 1543* Characters:: Character Constants 1544* Numbers:: Number Constants 1545@end menu 1546 1547@node Characters 1548@subsection Character Constants 1549 1550@cindex character constants 1551@cindex constants, character 1552There are two kinds of character constants. A @dfn{character} stands 1553for one character in one byte and its value may be used in 1554numeric expressions. String constants (properly called string 1555@emph{literals}) are potentially many bytes and their values may not be 1556used in arithmetic expressions. 1557 1558@menu 1559* Strings:: Strings 1560* Chars:: Characters 1561@end menu 1562 1563@node Strings 1564@subsubsection Strings 1565 1566@cindex string constants 1567@cindex constants, string 1568A @dfn{string} is written between double-quotes. It may contain 1569double-quotes or null characters. The way to get special characters 1570into a string is to @dfn{escape} these characters: precede them with 1571a backslash @samp{\} character. For example @samp{\\} represents 1572one backslash: the first @code{\} is an escape which tells 1573@code{@value{AS}} to interpret the second character literally as a backslash 1574(which prevents @code{@value{AS}} from recognizing the second @code{\} as an 1575escape character). The complete list of escapes follows. 1576 1577@cindex escape codes, character 1578@cindex character escape codes 1579@table @kbd 1580@c @item \a 1581@c Mnemonic for ACKnowledge; for ASCII this is octal code 007. 1582@c 1583@cindex @code{\b} (backspace character) 1584@cindex backspace (@code{\b}) 1585@item \b 1586Mnemonic for backspace; for ASCII this is octal code 010. 1587 1588@c @item \e 1589@c Mnemonic for EOText; for ASCII this is octal code 004. 1590@c 1591@cindex @code{\f} (formfeed character) 1592@cindex formfeed (@code{\f}) 1593@item \f 1594Mnemonic for FormFeed; for ASCII this is octal code 014. 1595 1596@cindex @code{\n} (newline character) 1597@cindex newline (@code{\n}) 1598@item \n 1599Mnemonic for newline; for ASCII this is octal code 012. 1600 1601@c @item \p 1602@c Mnemonic for prefix; for ASCII this is octal code 033, usually known as @code{escape}. 1603@c 1604@cindex @code{\r} (carriage return character) 1605@cindex carriage return (@code{\r}) 1606@item \r 1607Mnemonic for carriage-Return; for ASCII this is octal code 015. 1608 1609@c @item \s 1610@c Mnemonic for space; for ASCII this is octal code 040. Included for compliance with 1611@c other assemblers. 1612@c 1613@cindex @code{\t} (tab) 1614@cindex tab (@code{\t}) 1615@item \t 1616Mnemonic for horizontal Tab; for ASCII this is octal code 011. 1617 1618@c @item \v 1619@c Mnemonic for Vertical tab; for ASCII this is octal code 013. 1620@c @item \x @var{digit} @var{digit} @var{digit} 1621@c A hexadecimal character code. The numeric code is 3 hexadecimal digits. 1622@c 1623@cindex @code{\@var{ddd}} (octal character code) 1624@cindex octal character code (@code{\@var{ddd}}) 1625@item \ @var{digit} @var{digit} @var{digit} 1626An octal character code. The numeric code is 3 octal digits. 1627For compatibility with other Unix systems, 8 and 9 are accepted as digits: 1628for example, @code{\008} has the value 010, and @code{\009} the value 011. 1629 1630@cindex @code{\@var{xd...}} (hex character code) 1631@cindex hex character code (@code{\@var{xd...}}) 1632@item \@code{x} @var{hex-digits...} 1633A hex character code. All trailing hex digits are combined. Either upper or 1634lower case @code{x} works. 1635 1636@cindex @code{\\} (@samp{\} character) 1637@cindex backslash (@code{\\}) 1638@item \\ 1639Represents one @samp{\} character. 1640 1641@c @item \' 1642@c Represents one @samp{'} (accent acute) character. 1643@c This is needed in single character literals 1644@c (@xref{Characters,,Character Constants}.) to represent 1645@c a @samp{'}. 1646@c 1647@cindex @code{\"} (doublequote character) 1648@cindex doublequote (@code{\"}) 1649@item \" 1650Represents one @samp{"} character. Needed in strings to represent 1651this character, because an unescaped @samp{"} would end the string. 1652 1653@item \ @var{anything-else} 1654Any other character when escaped by @kbd{\} gives a warning, but 1655assembles as if the @samp{\} was not present. The idea is that if 1656you used an escape sequence you clearly didn't want the literal 1657interpretation of the following character. However @code{@value{AS}} has no 1658other interpretation, so @code{@value{AS}} knows it is giving you the wrong 1659code and warns you of the fact. 1660@end table 1661 1662Which characters are escapable, and what those escapes represent, 1663varies widely among assemblers. The current set is what we think 1664the BSD 4.2 assembler recognizes, and is a subset of what most C 1665compilers recognize. If you are in doubt, do not use an escape 1666sequence. 1667 1668@node Chars 1669@subsubsection Characters 1670 1671@cindex single character constant 1672@cindex character, single 1673@cindex constant, single character 1674A single character may be written as a single quote immediately 1675followed by that character. The same escapes apply to characters as 1676to strings. So if you want to write the character backslash, you 1677must write @kbd{'\\} where the first @code{\} escapes the second 1678@code{\}. As you can see, the quote is an acute accent, not a 1679grave accent. A newline 1680@ifclear GENERIC 1681@ifclear abnormal-separator 1682(or semicolon @samp{;}) 1683@end ifclear 1684@ifset abnormal-separator 1685@ifset A29K 1686(or at sign @samp{@@}) 1687@end ifset 1688@ifset H8 1689(or dollar sign @samp{$}, for the H8/300; or semicolon @samp{;} for the 1690Hitachi SH or 1691H8/500) 1692@end ifset 1693@end ifset 1694@end ifclear 1695immediately following an acute accent is taken as a literal character 1696and does not count as the end of a statement. The value of a character 1697constant in a numeric expression is the machine's byte-wide code for 1698that character. @code{@value{AS}} assumes your character code is ASCII: 1699@kbd{'A} means 65, @kbd{'B} means 66, and so on. @refill 1700 1701@node Numbers 1702@subsection Number Constants 1703 1704@cindex constants, number 1705@cindex number constants 1706@code{@value{AS}} distinguishes three kinds of numbers according to how they 1707are stored in the target machine. @emph{Integers} are numbers that 1708would fit into an @code{int} in the C language. @emph{Bignums} are 1709integers, but they are stored in more than 32 bits. @emph{Flonums} 1710are floating point numbers, described below. 1711 1712@menu 1713* Integers:: Integers 1714* Bignums:: Bignums 1715* Flonums:: Flonums 1716@ifclear GENERIC 1717@ifset I960 1718* Bit Fields:: Bit Fields 1719@end ifset 1720@end ifclear 1721@end menu 1722 1723@node Integers 1724@subsubsection Integers 1725@cindex integers 1726@cindex constants, integer 1727 1728@cindex binary integers 1729@cindex integers, binary 1730A binary integer is @samp{0b} or @samp{0B} followed by zero or more of 1731the binary digits @samp{01}. 1732 1733@cindex octal integers 1734@cindex integers, octal 1735An octal integer is @samp{0} followed by zero or more of the octal 1736digits (@samp{01234567}). 1737 1738@cindex decimal integers 1739@cindex integers, decimal 1740A decimal integer starts with a non-zero digit followed by zero or 1741more digits (@samp{0123456789}). 1742 1743@cindex hexadecimal integers 1744@cindex integers, hexadecimal 1745A hexadecimal integer is @samp{0x} or @samp{0X} followed by one or 1746more hexadecimal digits chosen from @samp{0123456789abcdefABCDEF}. 1747 1748Integers have the usual values. To denote a negative integer, use 1749the prefix operator @samp{-} discussed under expressions 1750(@pxref{Prefix Ops,,Prefix Operators}). 1751 1752@node Bignums 1753@subsubsection Bignums 1754 1755@cindex bignums 1756@cindex constants, bignum 1757A @dfn{bignum} has the same syntax and semantics as an integer 1758except that the number (or its negative) takes more than 32 bits to 1759represent in binary. The distinction is made because in some places 1760integers are permitted while bignums are not. 1761 1762@node Flonums 1763@subsubsection Flonums 1764@cindex flonums 1765@cindex floating point numbers 1766@cindex constants, floating point 1767 1768@cindex precision, floating point 1769A @dfn{flonum} represents a floating point number. The translation is 1770indirect: a decimal floating point number from the text is converted by 1771@code{@value{AS}} to a generic binary floating point number of more than 1772sufficient precision. This generic floating point number is converted 1773to a particular computer's floating point format (or formats) by a 1774portion of @code{@value{AS}} specialized to that computer. 1775 1776A flonum is written by writing (in order) 1777@itemize @bullet 1778@item 1779The digit @samp{0}. 1780@ifset HPPA 1781(@samp{0} is optional on the HPPA.) 1782@end ifset 1783 1784@item 1785A letter, to tell @code{@value{AS}} the rest of the number is a flonum. 1786@ifset GENERIC 1787@kbd{e} is recommended. Case is not important. 1788@ignore 1789@c FIXME: verify if flonum syntax really this vague for most cases 1790(Any otherwise illegal letter works here, but that might be changed. Vax BSD 17914.2 assembler seems to allow any of @samp{defghDEFGH}.) 1792@end ignore 1793 1794On the H8/300, H8/500, 1795Hitachi SH, 1796and AMD 29K architectures, the letter must be 1797one of the letters @samp{DFPRSX} (in upper or lower case). 1798 1799 1800On the Intel 960 architecture, the letter must be 1801one of the letters @samp{DFT} (in upper or lower case). 1802 1803On the HPPA architecture, the letter must be @samp{E} (upper case only). 1804@end ifset 1805@ifclear GENERIC 1806@ifset A29K 1807One of the letters @samp{DFPRSX} (in upper or lower case). 1808@end ifset 1809@ifset H8 1810One of the letters @samp{DFPRSX} (in upper or lower case). 1811@end ifset 1812@ifset HPPA 1813The letter @samp{E} (upper case only). 1814@end ifset 1815@ifset I960 1816One of the letters @samp{DFT} (in upper or lower case). 1817@end ifset 1818@end ifclear 1819 1820@item 1821An optional sign: either @samp{+} or @samp{-}. 1822 1823@item 1824An optional @dfn{integer part}: zero or more decimal digits. 1825 1826@item 1827An optional @dfn{fractional part}: @samp{.} followed by zero 1828or more decimal digits. 1829 1830@item 1831An optional exponent, consisting of: 1832 1833@itemize @bullet 1834@item 1835An @samp{E} or @samp{e}. 1836@c I can't find a config where "EXP_CHARS" is other than 'eE', but in 1837@c principle this can perfectly well be different on different targets. 1838@item 1839Optional sign: either @samp{+} or @samp{-}. 1840@item 1841One or more decimal digits. 1842@end itemize 1843 1844@end itemize 1845 1846At least one of the integer part or the fractional part must be 1847present. The floating point number has the usual base-10 value. 1848 1849@code{@value{AS}} does all processing using integers. Flonums are computed 1850independently of any floating point hardware in the computer running 1851@code{@value{AS}}. 1852 1853@ifclear GENERIC 1854@ifset I960 1855@c Bit fields are written as a general facility but are also controlled 1856@c by a conditional-compilation flag---which is as of now (21mar91) 1857@c turned on only by the i960 config of GAS. 1858@node Bit Fields 1859@subsubsection Bit Fields 1860 1861@cindex bit fields 1862@cindex constants, bit field 1863You can also define numeric constants as @dfn{bit fields}. 1864specify two numbers separated by a colon--- 1865@example 1866@var{mask}:@var{value} 1867@end example 1868@noindent 1869@code{@value{AS}} applies a bitwise @sc{and} between @var{mask} and 1870@var{value}. 1871 1872The resulting number is then packed 1873@ifset GENERIC 1874@c this conditional paren in case bit fields turned on elsewhere than 960 1875(in host-dependent byte order) 1876@end ifset 1877into a field whose width depends on which assembler directive has the 1878bit-field as its argument. Overflow (a result from the bitwise and 1879requiring more binary digits to represent) is not an error; instead, 1880more constants are generated, of the specified width, beginning with the 1881least significant digits.@refill 1882 1883The directives @code{.byte}, @code{.hword}, @code{.int}, @code{.long}, 1884@code{.short}, and @code{.word} accept bit-field arguments. 1885@end ifset 1886@end ifclear 1887 1888@node Sections 1889@chapter Sections and Relocation 1890@cindex sections 1891@cindex relocation 1892 1893@menu 1894* Secs Background:: Background 1895* Ld Sections:: @value{LD} Sections 1896* As Sections:: @value{AS} Internal Sections 1897* Sub-Sections:: Sub-Sections 1898* bss:: bss Section 1899@end menu 1900 1901@node Secs Background 1902@section Background 1903 1904Roughly, a section is a range of addresses, with no gaps; all data 1905``in'' those addresses is treated the same for some particular purpose. 1906For example there may be a ``read only'' section. 1907 1908@cindex linker, and assembler 1909@cindex assembler, and linker 1910The linker @code{@value{LD}} reads many object files (partial programs) and 1911combines their contents to form a runnable program. When @code{@value{AS}} 1912emits an object file, the partial program is assumed to start at address 0. 1913@code{@value{LD}} assigns the final addresses for the partial program, so that 1914different partial programs do not overlap. This is actually an 1915oversimplification, but it suffices to explain how @code{@value{AS}} uses 1916sections. 1917 1918@code{@value{LD}} moves blocks of bytes of your program to their run-time 1919addresses. These blocks slide to their run-time addresses as rigid 1920units; their length does not change and neither does the order of bytes 1921within them. Such a rigid unit is called a @emph{section}. Assigning 1922run-time addresses to sections is called @dfn{relocation}. It includes 1923the task of adjusting mentions of object-file addresses so they refer to 1924the proper run-time addresses. 1925@ifset H8 1926For the H8/300 and H8/500, 1927and for the Hitachi SH, 1928@code{@value{AS}} pads sections if needed to 1929ensure they end on a word (sixteen bit) boundary. 1930@end ifset 1931 1932@cindex standard @code{@value{AS}} sections 1933An object file written by @code{@value{AS}} has at least three sections, any 1934of which may be empty. These are named @dfn{text}, @dfn{data} and 1935@dfn{bss} sections. 1936 1937@ifset COFF 1938@ifset GENERIC 1939When it generates COFF output, 1940@end ifset 1941@code{@value{AS}} can also generate whatever other named sections you specify 1942using the @samp{.section} directive (@pxref{Section,,@code{.section}}). 1943If you do not use any directives that place output in the @samp{.text} 1944or @samp{.data} sections, these sections still exist, but are empty. 1945@end ifset 1946 1947@ifset HPPA 1948@ifset GENERIC 1949When @code{@value{AS}} generates SOM or ELF output for the HPPA, 1950@end ifset 1951@code{@value{AS}} can also generate whatever other named sections you 1952specify using the @samp{.space} and @samp{.subspace} directives. See 1953@cite{HP9000 Series 800 Assembly Language Reference Manual} 1954(HP 92432-90001) for details on the @samp{.space} and @samp{.subspace} 1955assembler directives. 1956 1957@ifset SOM 1958Additionally, @code{@value{AS}} uses different names for the standard 1959text, data, and bss sections when generating SOM output. Program text 1960is placed into the @samp{$CODE$} section, data into @samp{$DATA$}, and 1961BSS into @samp{$BSS$}. 1962@end ifset 1963@end ifset 1964 1965Within the object file, the text section starts at address @code{0}, the 1966data section follows, and the bss section follows the data section. 1967 1968@ifset HPPA 1969When generating either SOM or ELF output files on the HPPA, the text 1970section starts at address @code{0}, the data section at address 1971@code{0x4000000}, and the bss section follows the data section. 1972@end ifset 1973 1974To let @code{@value{LD}} know which data changes when the sections are 1975relocated, and how to change that data, @code{@value{AS}} also writes to the 1976object file details of the relocation needed. To perform relocation 1977@code{@value{LD}} must know, each time an address in the object 1978file is mentioned: 1979@itemize @bullet 1980@item 1981Where in the object file is the beginning of this reference to 1982an address? 1983@item 1984How long (in bytes) is this reference? 1985@item 1986Which section does the address refer to? What is the numeric value of 1987@display 1988(@var{address}) @minus{} (@var{start-address of section})? 1989@end display 1990@item 1991Is the reference to an address ``Program-Counter relative''? 1992@end itemize 1993 1994@cindex addresses, format of 1995@cindex section-relative addressing 1996In fact, every address @code{@value{AS}} ever uses is expressed as 1997@display 1998(@var{section}) + (@var{offset into section}) 1999@end display 2000@noindent 2001Further, most expressions @code{@value{AS}} computes have this section-relative 2002nature. 2003@ifset SOM 2004(For some object formats, such as SOM for the HPPA, some expressions are 2005symbol-relative instead.) 2006@end ifset 2007 2008In this manual we use the notation @{@var{secname} @var{N}@} to mean ``offset 2009@var{N} into section @var{secname}.'' 2010 2011Apart from text, data and bss sections you need to know about the 2012@dfn{absolute} section. When @code{@value{LD}} mixes partial programs, 2013addresses in the absolute section remain unchanged. For example, address 2014@code{@{absolute 0@}} is ``relocated'' to run-time address 0 by 2015@code{@value{LD}}. Although the linker never arranges two partial programs' 2016data sections with overlapping addresses after linking, @emph{by definition} 2017their absolute sections must overlap. Address @code{@{absolute@ 239@}} in one 2018part of a program is always the same address when the program is running as 2019address @code{@{absolute@ 239@}} in any other part of the program. 2020 2021The idea of sections is extended to the @dfn{undefined} section. Any 2022address whose section is unknown at assembly time is by definition 2023rendered @{undefined @var{U}@}---where @var{U} is filled in later. 2024Since numbers are always defined, the only way to generate an undefined 2025address is to mention an undefined symbol. A reference to a named 2026common block would be such a symbol: its value is unknown at assembly 2027time so it has section @emph{undefined}. 2028 2029By analogy the word @emph{section} is used to describe groups of sections in 2030the linked program. @code{@value{LD}} puts all partial programs' text 2031sections in contiguous addresses in the linked program. It is 2032customary to refer to the @emph{text section} of a program, meaning all 2033the addresses of all partial programs' text sections. Likewise for 2034data and bss sections. 2035 2036Some sections are manipulated by @code{@value{LD}}; others are invented for 2037use of @code{@value{AS}} and have no meaning except during assembly. 2038 2039@node Ld Sections 2040@section @value{LD} Sections 2041@code{@value{LD}} deals with just four kinds of sections, summarized below. 2042 2043@table @strong 2044 2045@ifset COFF 2046@cindex named sections 2047@cindex sections, named 2048@item named sections 2049@end ifset 2050@ifset aout-bout 2051@cindex text section 2052@cindex data section 2053@itemx text section 2054@itemx data section 2055@end ifset 2056These sections hold your program. @code{@value{AS}} and @code{@value{LD}} treat them as 2057separate but equal sections. Anything you can say of one section is 2058true another. 2059@ifset aout-bout 2060When the program is running, however, it is 2061customary for the text section to be unalterable. The 2062text section is often shared among processes: it contains 2063instructions, constants and the like. The data section of a running 2064program is usually alterable: for example, C variables would be stored 2065in the data section. 2066@end ifset 2067 2068@cindex bss section 2069@item bss section 2070This section contains zeroed bytes when your program begins running. It 2071is used to hold unitialized variables or common storage. The length of 2072each partial program's bss section is important, but because it starts 2073out containing zeroed bytes there is no need to store explicit zero 2074bytes in the object file. The bss section was invented to eliminate 2075those explicit zeros from object files. 2076 2077@cindex absolute section 2078@item absolute section 2079Address 0 of this section is always ``relocated'' to runtime address 0. 2080This is useful if you want to refer to an address that @code{@value{LD}} must 2081not change when relocating. In this sense we speak of absolute 2082addresses being ``unrelocatable'': they do not change during relocation. 2083 2084@cindex undefined section 2085@item undefined section 2086This ``section'' is a catch-all for address references to objects not in 2087the preceding sections. 2088@c FIXME: ref to some other doc on obj-file formats could go here. 2089@end table 2090 2091@cindex relocation example 2092An idealized example of three relocatable sections follows. 2093@ifset COFF 2094The example uses the traditional section names @samp{.text} and @samp{.data}. 2095@end ifset 2096Memory addresses are on the horizontal axis. 2097 2098@c TEXI2ROFF-KILL 2099@ifinfo 2100@c END TEXI2ROFF-KILL 2101@smallexample 2102 +-----+----+--+ 2103partial program # 1: |ttttt|dddd|00| 2104 +-----+----+--+ 2105 2106 text data bss 2107 seg. seg. seg. 2108 2109 +---+---+---+ 2110partial program # 2: |TTT|DDD|000| 2111 +---+---+---+ 2112 2113 +--+---+-----+--+----+---+-----+~~ 2114linked program: | |TTT|ttttt| |dddd|DDD|00000| 2115 +--+---+-----+--+----+---+-----+~~ 2116 2117 addresses: 0 @dots{} 2118@end smallexample 2119@c TEXI2ROFF-KILL 2120@end ifinfo 2121@need 5000 2122@tex 2123 2124\line{\it Partial program \#1: \hfil} 2125\line{\ibox{2.5cm}{\tt text}\ibox{2cm}{\tt data}\ibox{1cm}{\tt bss}\hfil} 2126\line{\boxit{2.5cm}{\tt ttttt}\boxit{2cm}{\tt dddd}\boxit{1cm}{\tt 00}\hfil} 2127 2128\line{\it Partial program \#2: \hfil} 2129\line{\ibox{1cm}{\tt text}\ibox{1.5cm}{\tt data}\ibox{1cm}{\tt bss}\hfil} 2130\line{\boxit{1cm}{\tt TTT}\boxit{1.5cm}{\tt DDDD}\boxit{1cm}{\tt 000}\hfil} 2131 2132\line{\it linked program: \hfil} 2133\line{\ibox{.5cm}{}\ibox{1cm}{\tt text}\ibox{2.5cm}{}\ibox{.75cm}{}\ibox{2cm}{\tt data}\ibox{1.5cm}{}\ibox{2cm}{\tt bss}\hfil} 2134\line{\boxit{.5cm}{}\boxit{1cm}{\tt TTT}\boxit{2.5cm}{\tt 2135ttttt}\boxit{.75cm}{}\boxit{2cm}{\tt dddd}\boxit{1.5cm}{\tt 2136DDDD}\boxit{2cm}{\tt 00000}\ \dots\hfil} 2137 2138\line{\it addresses: \hfil} 2139\line{0\dots\hfil} 2140 2141@end tex 2142@c END TEXI2ROFF-KILL 2143 2144@node As Sections 2145@section @value{AS} Internal Sections 2146 2147@cindex internal @code{@value{AS}} sections 2148@cindex sections in messages, internal 2149These sections are meant only for the internal use of @code{@value{AS}}. They 2150have no meaning at run-time. You do not really need to know about these 2151sections for most purposes; but they can be mentioned in @code{@value{AS}} 2152warning messages, so it might be helpful to have an idea of their 2153meanings to @code{@value{AS}}. These sections are used to permit the 2154value of every expression in your assembly language program to be a 2155section-relative address. 2156 2157@table @b 2158@cindex assembler internal logic error 2159@item ASSEMBLER-INTERNAL-LOGIC-ERROR! 2160An internal assembler logic error has been found. This means there is a 2161bug in the assembler. 2162 2163@cindex expr (internal section) 2164@item expr section 2165The assembler stores complex expression internally as combinations of 2166symbols. When it needs to represent an expression as a symbol, it puts 2167it in the expr section. 2168@c FIXME item debug 2169@c FIXME item transfer[t] vector preload 2170@c FIXME item transfer[t] vector postload 2171@c FIXME item register 2172@end table 2173 2174@node Sub-Sections 2175@section Sub-Sections 2176 2177@cindex numbered subsections 2178@cindex grouping data 2179@ifset aout-bout 2180Assembled bytes 2181@ifset COFF 2182conventionally 2183@end ifset 2184fall into two sections: text and data. 2185@end ifset 2186You may have separate groups of 2187@ifset GENERIC 2188data in named sections 2189@end ifset 2190@ifclear GENERIC 2191@ifclear aout-bout 2192data in named sections 2193@end ifclear 2194@ifset aout-bout 2195text or data 2196@end ifset 2197@end ifclear 2198that you want to end up near to each other in the object file, even though they 2199are not contiguous in the assembler source. @code{@value{AS}} allows you to 2200use @dfn{subsections} for this purpose. Within each section, there can be 2201numbered subsections with values from 0 to 8192. Objects assembled into the 2202same subsection go into the object file together with other objects in the same 2203subsection. For example, a compiler might want to store constants in the text 2204section, but might not want to have them interspersed with the program being 2205assembled. In this case, the compiler could issue a @samp{.text 0} before each 2206section of code being output, and a @samp{.text 1} before each group of 2207constants being output. 2208 2209Subsections are optional. If you do not use subsections, everything 2210goes in subsection number zero. 2211 2212@ifset GENERIC 2213Each subsection is zero-padded up to a multiple of four bytes. 2214(Subsections may be padded a different amount on different flavors 2215of @code{@value{AS}}.) 2216@end ifset 2217@ifclear GENERIC 2218@ifset H8 2219On the H8/300 and H8/500 platforms, each subsection is zero-padded to a word 2220boundary (two bytes). 2221The same is true on the Hitachi SH. 2222@end ifset 2223@ifset I960 2224@c FIXME section padding (alignment)? 2225@c Rich Pixley says padding here depends on target obj code format; that 2226@c doesn't seem particularly useful to say without further elaboration, 2227@c so for now I say nothing about it. If this is a generic BFD issue, 2228@c these paragraphs might need to vanish from this manual, and be 2229@c discussed in BFD chapter of binutils (or some such). 2230@end ifset 2231@ifset A29K 2232On the AMD 29K family, no particular padding is added to section or 2233subsection sizes; @value{AS} forces no alignment on this platform. 2234@end ifset 2235@end ifclear 2236 2237Subsections appear in your object file in numeric order, lowest numbered 2238to highest. (All this to be compatible with other people's assemblers.) 2239The object file contains no representation of subsections; @code{@value{LD}} and 2240other programs that manipulate object files see no trace of them. 2241They just see all your text subsections as a text section, and all your 2242data subsections as a data section. 2243 2244To specify which subsection you want subsequent statements assembled 2245into, use a numeric argument to specify it, in a @samp{.text 2246@var{expression}} or a @samp{.data @var{expression}} statement. 2247@ifset COFF 2248@ifset GENERIC 2249When generating COFF output, you 2250@end ifset 2251@ifclear GENERIC 2252You 2253@end ifclear 2254can also use an extra subsection 2255argument with arbitrary named sections: @samp{.section @var{name}, 2256@var{expression}}. 2257@end ifset 2258@var{Expression} should be an absolute expression. 2259(@xref{Expressions}.) If you just say @samp{.text} then @samp{.text 0} 2260is assumed. Likewise @samp{.data} means @samp{.data 0}. Assembly 2261begins in @code{text 0}. For instance: 2262@smallexample 2263.text 0 # The default subsection is text 0 anyway. 2264.ascii "This lives in the first text subsection. *" 2265.text 1 2266.ascii "But this lives in the second text subsection." 2267.data 0 2268.ascii "This lives in the data section," 2269.ascii "in the first data subsection." 2270.text 0 2271.ascii "This lives in the first text section," 2272.ascii "immediately following the asterisk (*)." 2273@end smallexample 2274 2275Each section has a @dfn{location counter} incremented by one for every byte 2276assembled into that section. Because subsections are merely a convenience 2277restricted to @code{@value{AS}} there is no concept of a subsection location 2278counter. There is no way to directly manipulate a location counter---but the 2279@code{.align} directive changes it, and any label definition captures its 2280current value. The location counter of the section where statements are being 2281assembled is said to be the @dfn{active} location counter. 2282 2283@node bss 2284@section bss Section 2285 2286@cindex bss section 2287@cindex common variable storage 2288The bss section is used for local common variable storage. 2289You may allocate address space in the bss section, but you may 2290not dictate data to load into it before your program executes. When 2291your program starts running, all the contents of the bss 2292section are zeroed bytes. 2293 2294Addresses in the bss section are allocated with special directives; you 2295may not assemble anything directly into the bss section. Hence there 2296are no bss subsections. @xref{Comm,,@code{.comm}}, 2297@pxref{Lcomm,,@code{.lcomm}}. 2298 2299@node Symbols 2300@chapter Symbols 2301 2302@cindex symbols 2303Symbols are a central concept: the programmer uses symbols to name 2304things, the linker uses symbols to link, and the debugger uses symbols 2305to debug. 2306 2307@quotation 2308@cindex debuggers, and symbol order 2309@emph{Warning:} @code{@value{AS}} does not place symbols in the object file in 2310the same order they were declared. This may break some debuggers. 2311@end quotation 2312 2313@menu 2314* Labels:: Labels 2315* Setting Symbols:: Giving Symbols Other Values 2316* Symbol Names:: Symbol Names 2317* Dot:: The Special Dot Symbol 2318* Symbol Attributes:: Symbol Attributes 2319@end menu 2320 2321@node Labels 2322@section Labels 2323 2324@cindex labels 2325A @dfn{label} is written as a symbol immediately followed by a colon 2326@samp{:}. The symbol then represents the current value of the 2327active location counter, and is, for example, a suitable instruction 2328operand. You are warned if you use the same symbol to represent two 2329different locations: the first definition overrides any other 2330definitions. 2331 2332@ifset HPPA 2333On the HPPA, the usual form for a label need not be immediately followed by a 2334colon, but instead must start in column zero. Only one label may be defined on 2335a single line. To work around this, the HPPA version of @code{@value{AS}} also 2336provides a special directive @code{.label} for defining labels more flexibly. 2337@end ifset 2338 2339@node Setting Symbols 2340@section Giving Symbols Other Values 2341 2342@cindex assigning values to symbols 2343@cindex symbol values, assigning 2344A symbol can be given an arbitrary value by writing a symbol, followed 2345by an equals sign @samp{=}, followed by an expression 2346(@pxref{Expressions}). This is equivalent to using the @code{.set} 2347directive. @xref{Set,,@code{.set}}. 2348 2349@node Symbol Names 2350@section Symbol Names 2351 2352@cindex symbol names 2353@cindex names, symbol 2354@ifclear SPECIAL-SYMS 2355Symbol names begin with a letter or with one of @samp{._}. On most 2356machines, you can also use @code{$} in symbol names; exceptions are 2357noted in @ref{Machine Dependencies}. That character may be followed by any 2358string of digits, letters, dollar signs (unless otherwise noted in 2359@ref{Machine Dependencies}), and underscores. 2360@end ifclear 2361@ifset A29K 2362For the AMD 29K family, @samp{?} is also allowed in the 2363body of a symbol name, though not at its beginning. 2364@end ifset 2365 2366@ifset SPECIAL-SYMS 2367@ifset H8 2368Symbol names begin with a letter or with one of @samp{._}. On the 2369Hitachi SH or the 2370H8/500, you can also use @code{$} in symbol names. That character may 2371be followed by any string of digits, letters, dollar signs (save on the 2372H8/300), and underscores. 2373@end ifset 2374@end ifset 2375 2376Case of letters is significant: @code{foo} is a different symbol name 2377than @code{Foo}. 2378 2379Each symbol has exactly one name. Each name in an assembly language program 2380refers to exactly one symbol. You may use that symbol name any number of times 2381in a program. 2382 2383@subheading Local Symbol Names 2384 2385@cindex local symbol names 2386@cindex symbol names, local 2387@cindex temporary symbol names 2388@cindex symbol names, temporary 2389Local symbols help compilers and programmers use names temporarily. 2390There are ten local symbol names, which are re-used throughout the 2391program. You may refer to them using the names @samp{0} @samp{1} 2392@dots{} @samp{9}. To define a local symbol, write a label of the form 2393@samp{@b{N}:} (where @b{N} represents any digit). To refer to the most 2394recent previous definition of that symbol write @samp{@b{N}b}, using the 2395same digit as when you defined the label. To refer to the next 2396definition of a local label, write @samp{@b{N}f}---where @b{N} gives you 2397a choice of 10 forward references. The @samp{b} stands for 2398``backwards'' and the @samp{f} stands for ``forwards''. 2399 2400Local symbols are not emitted by the current @sc{gnu} C compiler. 2401 2402There is no restriction on how you can use these labels, but 2403remember that at any point in the assembly you can refer to at most 240410 prior local labels and to at most 10 forward local labels. 2405 2406Local symbol names are only a notation device. They are immediately 2407transformed into more conventional symbol names before the assembler 2408uses them. The symbol names stored in the symbol table, appearing in 2409error messages and optionally emitted to the object file have these 2410parts: 2411 2412@table @code 2413@item L 2414All local labels begin with @samp{L}. Normally both @code{@value{AS}} and 2415@code{@value{LD}} forget symbols that start with @samp{L}. These labels are 2416used for symbols you are never intended to see. If you use the 2417@samp{-L} option then @code{@value{AS}} retains these symbols in the 2418object file. If you also instruct @code{@value{LD}} to retain these symbols, 2419you may use them in debugging. 2420 2421@item @var{digit} 2422If the label is written @samp{0:} then the digit is @samp{0}. 2423If the label is written @samp{1:} then the digit is @samp{1}. 2424And so on up through @samp{9:}. 2425 2426@item @ctrl{A} 2427This unusual character is included so you do not accidentally invent 2428a symbol of the same name. The character has ASCII value 2429@samp{\001}. 2430 2431@item @emph{ordinal number} 2432This is a serial number to keep the labels distinct. The first 2433@samp{0:} gets the number @samp{1}; The 15th @samp{0:} gets the 2434number @samp{15}; @emph{etc.}. Likewise for the other labels @samp{1:} 2435through @samp{9:}. 2436@end table 2437 2438For instance, the first @code{1:} is named @code{L1@ctrl{A}1}, the 44th 2439@code{3:} is named @code{L3@ctrl{A}44}. 2440 2441@node Dot 2442@section The Special Dot Symbol 2443 2444@cindex dot (symbol) 2445@cindex @code{.} (symbol) 2446@cindex current address 2447@cindex location counter 2448The special symbol @samp{.} refers to the current address that 2449@code{@value{AS}} is assembling into. Thus, the expression @samp{melvin: 2450.long .} defines @code{melvin} to contain its own address. 2451Assigning a value to @code{.} is treated the same as a @code{.org} 2452directive. Thus, the expression @samp{.=.+4} is the same as saying 2453@ifclear no-space-dir 2454@samp{.space 4}. 2455@end ifclear 2456@ifset no-space-dir 2457@ifset A29K 2458@samp{.block 4}. 2459@end ifset 2460@end ifset 2461 2462@node Symbol Attributes 2463@section Symbol Attributes 2464 2465@cindex symbol attributes 2466@cindex attributes, symbol 2467Every symbol has, as well as its name, the attributes ``Value'' and 2468``Type''. Depending on output format, symbols can also have auxiliary 2469attributes. 2470@ifset INTERNALS 2471The detailed definitions are in @file{a.out.h}. 2472@end ifset 2473 2474If you use a symbol without defining it, @code{@value{AS}} assumes zero for 2475all these attributes, and probably won't warn you. This makes the 2476symbol an externally defined symbol, which is generally what you 2477would want. 2478 2479@menu 2480* Symbol Value:: Value 2481* Symbol Type:: Type 2482@ifset aout-bout 2483@ifset GENERIC 2484* a.out Symbols:: Symbol Attributes: @code{a.out} 2485@end ifset 2486@ifclear GENERIC 2487@ifclear BOUT 2488* a.out Symbols:: Symbol Attributes: @code{a.out} 2489@end ifclear 2490@ifset BOUT 2491* a.out Symbols:: Symbol Attributes: @code{a.out}, @code{b.out} 2492@end ifset 2493@end ifclear 2494@end ifset 2495@ifset COFF 2496* COFF Symbols:: Symbol Attributes for COFF 2497@end ifset 2498@ifset SOM 2499* SOM Symbols:: Symbol Attributes for SOM 2500@end ifset 2501@end menu 2502 2503@node Symbol Value 2504@subsection Value 2505 2506@cindex value of a symbol 2507@cindex symbol value 2508The value of a symbol is (usually) 32 bits. For a symbol which labels a 2509location in the text, data, bss or absolute sections the value is the 2510number of addresses from the start of that section to the label. 2511Naturally for text, data and bss sections the value of a symbol changes 2512as @code{@value{LD}} changes section base addresses during linking. Absolute 2513symbols' values do not change during linking: that is why they are 2514called absolute. 2515 2516The value of an undefined symbol is treated in a special way. If it is 25170 then the symbol is not defined in this assembler source file, and 2518@code{@value{LD}} tries to determine its value from other files linked into the 2519same program. You make this kind of symbol simply by mentioning a symbol 2520name without defining it. A non-zero value represents a @code{.comm} 2521common declaration. The value is how much common storage to reserve, in 2522bytes (addresses). The symbol refers to the first address of the 2523allocated storage. 2524 2525@node Symbol Type 2526@subsection Type 2527 2528@cindex type of a symbol 2529@cindex symbol type 2530The type attribute of a symbol contains relocation (section) 2531information, any flag settings indicating that a symbol is external, and 2532(optionally), other information for linkers and debuggers. The exact 2533format depends on the object-code output format in use. 2534 2535@ifset aout-bout 2536@ifclear GENERIC 2537@ifset BOUT 2538@c The following avoids a "widow" subsection title. @group would be 2539@c better if it were available outside examples. 2540@need 1000 2541@node a.out Symbols 2542@subsection Symbol Attributes: @code{a.out}, @code{b.out} 2543 2544@cindex @code{b.out} symbol attributes 2545@cindex symbol attributes, @code{b.out} 2546These symbol attributes appear only when @code{@value{AS}} is configured for 2547one of the Berkeley-descended object output formats---@code{a.out} or 2548@code{b.out}. 2549 2550@end ifset 2551@ifclear BOUT 2552@node a.out Symbols 2553@subsection Symbol Attributes: @code{a.out} 2554 2555@cindex @code{a.out} symbol attributes 2556@cindex symbol attributes, @code{a.out} 2557 2558@end ifclear 2559@end ifclear 2560@ifset GENERIC 2561@node a.out Symbols 2562@subsection Symbol Attributes: @code{a.out} 2563 2564@cindex @code{a.out} symbol attributes 2565@cindex symbol attributes, @code{a.out} 2566 2567@end ifset 2568@menu 2569* Symbol Desc:: Descriptor 2570* Symbol Other:: Other 2571@end menu 2572 2573@node Symbol Desc 2574@subsubsection Descriptor 2575 2576@cindex descriptor, of @code{a.out} symbol 2577This is an arbitrary 16-bit value. You may establish a symbol's 2578descriptor value by using a @code{.desc} statement 2579(@pxref{Desc,,@code{.desc}}). A descriptor value means nothing to 2580@code{@value{AS}}. 2581 2582@node Symbol Other 2583@subsubsection Other 2584 2585@cindex other attribute, of @code{a.out} symbol 2586This is an arbitrary 8-bit value. It means nothing to @code{@value{AS}}. 2587@end ifset 2588 2589@ifset COFF 2590@node COFF Symbols 2591@subsection Symbol Attributes for COFF 2592 2593@cindex COFF symbol attributes 2594@cindex symbol attributes, COFF 2595 2596The COFF format supports a multitude of auxiliary symbol attributes; 2597like the primary symbol attributes, they are set between @code{.def} and 2598@code{.endef} directives. 2599 2600@subsubsection Primary Attributes 2601 2602@cindex primary attributes, COFF symbols 2603The symbol name is set with @code{.def}; the value and type, 2604respectively, with @code{.val} and @code{.type}. 2605 2606@subsubsection Auxiliary Attributes 2607 2608@cindex auxiliary attributes, COFF symbols 2609The @code{@value{AS}} directives @code{.dim}, @code{.line}, @code{.scl}, 2610@code{.size}, and @code{.tag} can generate auxiliary symbol table 2611information for COFF. 2612@end ifset 2613 2614@ifset SOM 2615@node SOM Symbols 2616@subsection Symbol Attributes for SOM 2617 2618@cindex SOM symbol attributes 2619@cindex symbol attributes, SOM 2620 2621The SOM format for the HPPA supports a multitude of symbol attributes set with 2622the @code{.EXPORT} and @code{.IMPORT} directives. 2623 2624The attributes are described in @cite{HP9000 Series 800 Assembly 2625Language Reference Manual} (HP 92432-90001) under the @code{IMPORT} and 2626@code{EXPORT} assembler directive documentation. 2627@end ifset 2628 2629@node Expressions 2630@chapter Expressions 2631 2632@cindex expressions 2633@cindex addresses 2634@cindex numeric values 2635An @dfn{expression} specifies an address or numeric value. 2636Whitespace may precede and/or follow an expression. 2637 2638The result of an expression must be an absolute number, or else an offset into 2639a particular section. If an expression is not absolute, and there is not 2640enough information when @code{@value{AS}} sees the expression to know its 2641section, a second pass over the source program might be necessary to interpret 2642the expression---but the second pass is currently not implemented. 2643@code{@value{AS}} aborts with an error message in this situation. 2644 2645@menu 2646* Empty Exprs:: Empty Expressions 2647* Integer Exprs:: Integer Expressions 2648@end menu 2649 2650@node Empty Exprs 2651@section Empty Expressions 2652 2653@cindex empty expressions 2654@cindex expressions, empty 2655An empty expression has no value: it is just whitespace or null. 2656Wherever an absolute expression is required, you may omit the 2657expression, and @code{@value{AS}} assumes a value of (absolute) 0. This 2658is compatible with other assemblers. 2659 2660@node Integer Exprs 2661@section Integer Expressions 2662 2663@cindex integer expressions 2664@cindex expressions, integer 2665An @dfn{integer expression} is one or more @emph{arguments} delimited 2666by @emph{operators}. 2667 2668@menu 2669* Arguments:: Arguments 2670* Operators:: Operators 2671* Prefix Ops:: Prefix Operators 2672* Infix Ops:: Infix Operators 2673@end menu 2674 2675@node Arguments 2676@subsection Arguments 2677 2678@cindex expression arguments 2679@cindex arguments in expressions 2680@cindex operands in expressions 2681@cindex arithmetic operands 2682@dfn{Arguments} are symbols, numbers or subexpressions. In other 2683contexts arguments are sometimes called ``arithmetic operands''. In 2684this manual, to avoid confusing them with the ``instruction operands'' of 2685the machine language, we use the term ``argument'' to refer to parts of 2686expressions only, reserving the word ``operand'' to refer only to machine 2687instruction operands. 2688 2689Symbols are evaluated to yield @{@var{section} @var{NNN}@} where 2690@var{section} is one of text, data, bss, absolute, 2691or undefined. @var{NNN} is a signed, 2's complement 32 bit 2692integer. 2693 2694Numbers are usually integers. 2695 2696A number can be a flonum or bignum. In this case, you are warned 2697that only the low order 32 bits are used, and @code{@value{AS}} pretends 2698these 32 bits are an integer. You may write integer-manipulating 2699instructions that act on exotic constants, compatible with other 2700assemblers. 2701 2702@cindex subexpressions 2703Subexpressions are a left parenthesis @samp{(} followed by an integer 2704expression, followed by a right parenthesis @samp{)}; or a prefix 2705operator followed by an argument. 2706 2707@node Operators 2708@subsection Operators 2709 2710@cindex operators, in expressions 2711@cindex arithmetic functions 2712@cindex functions, in expressions 2713@dfn{Operators} are arithmetic functions, like @code{+} or @code{%}. Prefix 2714operators are followed by an argument. Infix operators appear 2715between their arguments. Operators may be preceded and/or followed by 2716whitespace. 2717 2718@node Prefix Ops 2719@subsection Prefix Operator 2720 2721@cindex prefix operators 2722@code{@value{AS}} has the following @dfn{prefix operators}. They each take 2723one argument, which must be absolute. 2724 2725@c the tex/end tex stuff surrounding this small table is meant to make 2726@c it align, on the printed page, with the similar table in the next 2727@c section (which is inside an enumerate). 2728@tex 2729\global\advance\leftskip by \itemindent 2730@end tex 2731 2732@table @code 2733@item - 2734@dfn{Negation}. Two's complement negation. 2735@item ~ 2736@dfn{Complementation}. Bitwise not. 2737@end table 2738 2739@tex 2740\global\advance\leftskip by -\itemindent 2741@end tex 2742 2743@node Infix Ops 2744@subsection Infix Operators 2745 2746@cindex infix operators 2747@cindex operators, permitted arguments 2748@dfn{Infix operators} take two arguments, one on either side. Operators 2749have precedence, but operations with equal precedence are performed left 2750to right. Apart from @code{+} or @code{-}, both arguments must be 2751absolute, and the result is absolute. 2752 2753@enumerate 2754@cindex operator precedence 2755@cindex precedence of operators 2756 2757@item 2758Highest Precedence 2759 2760@table @code 2761@item * 2762@dfn{Multiplication}. 2763 2764@item / 2765@dfn{Division}. Truncation is the same as the C operator @samp{/} 2766 2767@item % 2768@dfn{Remainder}. 2769 2770@item < 2771@itemx << 2772@dfn{Shift Left}. Same as the C operator @samp{<<}. 2773 2774@item > 2775@itemx >> 2776@dfn{Shift Right}. Same as the C operator @samp{>>}. 2777@end table 2778 2779@item 2780Intermediate precedence 2781 2782@table @code 2783@item | 2784 2785@dfn{Bitwise Inclusive Or}. 2786 2787@item & 2788@dfn{Bitwise And}. 2789 2790@item ^ 2791@dfn{Bitwise Exclusive Or}. 2792 2793@item ! 2794@dfn{Bitwise Or Not}. 2795@end table 2796 2797@item 2798Lowest Precedence 2799 2800@table @code 2801@cindex addition, permitted arguments 2802@cindex plus, permitted arguments 2803@cindex arguments for addition 2804@item + 2805@dfn{Addition}. If either argument is absolute, the result has the section of 2806the other argument. You may not add together arguments from different 2807sections. 2808 2809@cindex subtraction, permitted arguments 2810@cindex minus, permitted arguments 2811@cindex arguments for subtraction 2812@item - 2813@dfn{Subtraction}. If the right argument is absolute, the 2814result has the section of the left argument. 2815If both arguments are in the same section, the result is absolute. 2816You may not subtract arguments from different sections. 2817@c FIXME is there still something useful to say about undefined - undefined ? 2818@end table 2819@end enumerate 2820 2821In short, it's only meaningful to add or subtract the @emph{offsets} in an 2822address; you can only have a defined section in one of the two arguments. 2823 2824@node Pseudo Ops 2825@chapter Assembler Directives 2826 2827@cindex directives, machine independent 2828@cindex pseudo-ops, machine independent 2829@cindex machine independent directives 2830All assembler directives have names that begin with a period (@samp{.}). 2831The rest of the name is letters, usually in lower case. 2832 2833This chapter discusses directives that are available regardless of the 2834target machine configuration for the @sc{gnu} assembler. 2835@ifset GENERIC 2836Some machine configurations provide additional directives. 2837@xref{Machine Dependencies}. 2838@end ifset 2839@ifclear GENERIC 2840@ifset machine-directives 2841@xref{Machine Dependencies} for additional directives. 2842@end ifset 2843@end ifclear 2844 2845@menu 2846* Abort:: @code{.abort} 2847@ifset COFF 2848* ABORT:: @code{.ABORT} 2849@end ifset 2850 2851* Align:: @code{.align @var{abs-expr} , @var{abs-expr}} 2852* App-File:: @code{.app-file @var{string}} 2853* Ascii:: @code{.ascii "@var{string}"}@dots{} 2854* Asciz:: @code{.asciz "@var{string}"}@dots{} 2855* Balign:: @code{.balign @var{abs-expr} , @var{abs-expr}} 2856* Byte:: @code{.byte @var{expressions}} 2857* Comm:: @code{.comm @var{symbol} , @var{length} } 2858* Data:: @code{.data @var{subsection}} 2859@ifset COFF 2860* Def:: @code{.def @var{name}} 2861@end ifset 2862@ifset aout-bout 2863* Desc:: @code{.desc @var{symbol}, @var{abs-expression}} 2864@end ifset 2865@ifset COFF 2866* Dim:: @code{.dim} 2867@end ifset 2868 2869* Double:: @code{.double @var{flonums}} 2870* Eject:: @code{.eject} 2871* Else:: @code{.else} 2872@ifset COFF 2873* Endef:: @code{.endef} 2874@end ifset 2875 2876* Endif:: @code{.endif} 2877* Equ:: @code{.equ @var{symbol}, @var{expression}} 2878* Extern:: @code{.extern} 2879@ifclear no-file-dir 2880* File:: @code{.file @var{string}} 2881@end ifclear 2882 2883* Fill:: @code{.fill @var{repeat} , @var{size} , @var{value}} 2884* Float:: @code{.float @var{flonums}} 2885* Global:: @code{.global @var{symbol}}, @code{.globl @var{symbol}} 2886* hword:: @code{.hword @var{expressions}} 2887* Ident:: @code{.ident} 2888* If:: @code{.if @var{absolute expression}} 2889* Include:: @code{.include "@var{file}"} 2890* Int:: @code{.int @var{expressions}} 2891* Irp:: @code{.irp @var{symbol},@var{values}}@dots{} 2892* Irpc:: @code{.irpc @var{symbol},@var{values}}@dots{} 2893* Lcomm:: @code{.lcomm @var{symbol} , @var{length}} 2894* Lflags:: @code{.lflags} 2895@ifclear no-line-dir 2896* Line:: @code{.line @var{line-number}} 2897@end ifclear 2898 2899* Ln:: @code{.ln @var{line-number}} 2900* Linkonce:: @code{.linkonce [@var{type}]} 2901* List:: @code{.list} 2902* Long:: @code{.long @var{expressions}} 2903@ignore 2904* Lsym:: @code{.lsym @var{symbol}, @var{expression}} 2905@end ignore 2906 2907* Macro:: @code{.macro @var{name} @var{args}}@dots{} 2908* MRI:: @code{.mri @var{val}} 2909 2910* Nolist:: @code{.nolist} 2911* Octa:: @code{.octa @var{bignums}} 2912* Org:: @code{.org @var{new-lc} , @var{fill}} 2913* P2align:: @code{.p2align @var{abs-expr} , @var{abs-expr}} 2914* Psize:: @code{.psize @var{lines}, @var{columns}} 2915* Quad:: @code{.quad @var{bignums}} 2916* Rept:: @code{.rept @var{count}} 2917* Sbttl:: @code{.sbttl "@var{subheading}"} 2918@ifset COFF 2919* Scl:: @code{.scl @var{class}} 2920@end ifset 2921@ifset COFF 2922* Section:: @code{.section @var{name}, @var{subsection}} 2923@end ifset 2924 2925* Set:: @code{.set @var{symbol}, @var{expression}} 2926* Short:: @code{.short @var{expressions}} 2927* Single:: @code{.single @var{flonums}} 2928@ifset COFF 2929* Size:: @code{.size} 2930@end ifset 2931 2932* Skip:: @code{.skip @var{size} , @var{fill}} 2933* Space:: @code{.space @var{size} , @var{fill}} 2934@ifset have-stabs 2935* Stab:: @code{.stabd, .stabn, .stabs} 2936@end ifset 2937 2938* String:: @code{.string "@var{str}"} 2939@ifset COFF 2940* Tag:: @code{.tag @var{structname}} 2941@end ifset 2942 2943* Text:: @code{.text @var{subsection}} 2944* Title:: @code{.title "@var{heading}"} 2945@ifset COFF 2946* Type:: @code{.type @var{int}} 2947* Val:: @code{.val @var{addr}} 2948@end ifset 2949 2950* Word:: @code{.word @var{expressions}} 2951* Deprecated:: Deprecated Directives 2952@end menu 2953 2954@node Abort 2955@section @code{.abort} 2956 2957@cindex @code{abort} directive 2958@cindex stopping the assembly 2959This directive stops the assembly immediately. It is for 2960compatibility with other assemblers. The original idea was that the 2961assembly language source would be piped into the assembler. If the sender 2962of the source quit, it could use this directive tells @code{@value{AS}} to 2963quit also. One day @code{.abort} will not be supported. 2964 2965@ifset COFF 2966@node ABORT 2967@section @code{.ABORT} 2968 2969@cindex @code{ABORT} directive 2970When producing COFF output, @code{@value{AS}} accepts this directive as a 2971synonym for @samp{.abort}. 2972 2973@ifset BOUT 2974When producing @code{b.out} output, @code{@value{AS}} accepts this directive, 2975but ignores it. 2976@end ifset 2977@end ifset 2978 2979@node Align 2980@section @code{.align @var{abs-expr} , @var{abs-expr}} 2981 2982@cindex padding the location counter 2983@cindex @code{align} directive 2984Pad the location counter (in the current subsection) to a particular 2985storage boundary. The first expression (which must be absolute) is the 2986alignment required, as described below. 2987The second expression (also absolute) gives the value to be stored in 2988the padding bytes. It (and the comma) may be omitted. If it is 2989omitted, the padding bytes are zero. 2990For the alpha, if the section is marked as containing code and the 2991padding expression is omitted, then the space is filled with no-ops. 2992 2993The way the required alignment is specified varies from system to system. 2994For the a29k, hppa, m68k, m88k, w65, sparc, and Hitachi SH, and i386 using ELF 2995format, 2996the first expression is the 2997alignment request in bytes. For example @samp{.align 8} advances 2998the location counter until it is a multiple of 8. If the location counter 2999is already a multiple of 8, no change is needed. 3000 3001For other systems, including the i386 using a.out format, it is the 3002number of low-order zero bits the location counter must have after 3003advancement. For example @samp{.align 3} advances the location 3004counter until it a multiple of 8. If the location counter is already a 3005multiple of 8, no change is needed. 3006 3007This inconsistency is due to the different behaviors of the various 3008native assemblers for these systems which GAS must emulate. 3009GAS also provides @code{.balign} and @code{.p2align} directives, 3010described later, which have a consistent behavior across all 3011architectures (but are specific to GAS). 3012 3013@node App-File 3014@section @code{.app-file @var{string}} 3015 3016@cindex logical file name 3017@cindex file name, logical 3018@cindex @code{app-file} directive 3019@code{.app-file} 3020@ifclear no-file-dir 3021(which may also be spelled @samp{.file}) 3022@end ifclear 3023tells @code{@value{AS}} that we are about to start a new 3024logical file. @var{string} is the new file name. In general, the 3025filename is recognized whether or not it is surrounded by quotes @samp{"}; 3026but if you wish to specify an empty file name is permitted, 3027you must give the quotes--@code{""}. This statement may go away in 3028future: it is only recognized to be compatible with old @code{@value{AS}} 3029programs.@refill 3030 3031@node Ascii 3032@section @code{.ascii "@var{string}"}@dots{} 3033 3034@cindex @code{ascii} directive 3035@cindex string literals 3036@code{.ascii} expects zero or more string literals (@pxref{Strings}) 3037separated by commas. It assembles each string (with no automatic 3038trailing zero byte) into consecutive addresses. 3039 3040@node Asciz 3041@section @code{.asciz "@var{string}"}@dots{} 3042 3043@cindex @code{asciz} directive 3044@cindex zero-terminated strings 3045@cindex null-terminated strings 3046@code{.asciz} is just like @code{.ascii}, but each string is followed by 3047a zero byte. The ``z'' in @samp{.asciz} stands for ``zero''. 3048 3049@node Balign 3050@section @code{.balign[wl] @var{abs-expr} , @var{abs-expr}} 3051 3052@cindex padding the location counter given number of bytes 3053@cindex @code{balign} directive 3054Pad the location counter (in the current subsection) to a particular 3055storage boundary. The first expression (which must be absolute) is the 3056alignment request in bytes. For example @samp{.balign 8} advances 3057the location counter until it is a multiple of 8. If the location counter 3058is already a multiple of 8, no change is needed. 3059 3060The second expression (also absolute) gives the value to be stored in 3061the padding bytes. It (and the comma) may be omitted. If it is 3062omitted, the padding bytes are zero. 3063 3064@cindex @code{balignw} directive 3065@cindex @code{balignl} directive 3066The @code{.balignw} and @code{.balignl} directives are variants of the 3067@code{.balign} directive. The @code{.balignw} directive treats the fill 3068pattern as a two byte word value. The @code{.balignl} directives treats the 3069fill pattern as a four byte longword value. For example, @code{.balignw 30704,0x368d} will align to a multiple of 4. If it skips two bytes, they will be 3071filled in with the value 0x368d (the exact placement of the bytes depends upon 3072the endianness of the processor). If it skips 1 or 3 bytes, the fill value is 3073undefined. 3074 3075@node Byte 3076@section @code{.byte @var{expressions}} 3077 3078@cindex @code{byte} directive 3079@cindex integers, one byte 3080@code{.byte} expects zero or more expressions, separated by commas. 3081Each expression is assembled into the next byte. 3082 3083@node Comm 3084@section @code{.comm @var{symbol} , @var{length} } 3085 3086@cindex @code{comm} directive 3087@cindex symbol, common 3088@code{.comm} declares a named common area in the bss section. Normally 3089@code{@value{LD}} reserves memory addresses for it during linking, so no partial 3090program defines the location of the symbol. Use @code{.comm} to tell 3091@code{@value{LD}} that it must be at least @var{length} bytes long. @code{@value{LD}} 3092allocates space for each @code{.comm} symbol that is at least as 3093long as the longest @code{.comm} request in any of the partial programs 3094linked. @var{length} is an absolute expression. 3095 3096@ifset HPPA 3097The syntax for @code{.comm} differs slightly on the HPPA. The syntax is 3098@samp{@var{symbol} .comm, @var{length}}; @var{symbol} is optional. 3099@end ifset 3100 3101@node Data 3102@section @code{.data @var{subsection}} 3103 3104@cindex @code{data} directive 3105@code{.data} tells @code{@value{AS}} to assemble the following statements onto the 3106end of the data subsection numbered @var{subsection} (which is an 3107absolute expression). If @var{subsection} is omitted, it defaults 3108to zero. 3109 3110@ifset COFF 3111@node Def 3112@section @code{.def @var{name}} 3113 3114@cindex @code{def} directive 3115@cindex COFF symbols, debugging 3116@cindex debugging COFF symbols 3117Begin defining debugging information for a symbol @var{name}; the 3118definition extends until the @code{.endef} directive is encountered. 3119@ifset BOUT 3120 3121This directive is only observed when @code{@value{AS}} is configured for COFF 3122format output; when producing @code{b.out}, @samp{.def} is recognized, 3123but ignored. 3124@end ifset 3125@end ifset 3126 3127@ifset aout-bout 3128@node Desc 3129@section @code{.desc @var{symbol}, @var{abs-expression}} 3130 3131@cindex @code{desc} directive 3132@cindex COFF symbol descriptor 3133@cindex symbol descriptor, COFF 3134This directive sets the descriptor of the symbol (@pxref{Symbol Attributes}) 3135to the low 16 bits of an absolute expression. 3136 3137@ifset COFF 3138The @samp{.desc} directive is not available when @code{@value{AS}} is 3139configured for COFF output; it is only for @code{a.out} or @code{b.out} 3140object format. For the sake of compatibility, @code{@value{AS}} accepts 3141it, but produces no output, when configured for COFF. 3142@end ifset 3143@end ifset 3144 3145@ifset COFF 3146@node Dim 3147@section @code{.dim} 3148 3149@cindex @code{dim} directive 3150@cindex COFF auxiliary symbol information 3151@cindex auxiliary symbol information, COFF 3152This directive is generated by compilers to include auxiliary debugging 3153information in the symbol table. It is only permitted inside 3154@code{.def}/@code{.endef} pairs. 3155@ifset BOUT 3156 3157@samp{.dim} is only meaningful when generating COFF format output; when 3158@code{@value{AS}} is generating @code{b.out}, it accepts this directive but 3159ignores it. 3160@end ifset 3161@end ifset 3162 3163@node Double 3164@section @code{.double @var{flonums}} 3165 3166@cindex @code{double} directive 3167@cindex floating point numbers (double) 3168@code{.double} expects zero or more flonums, separated by commas. It 3169assembles floating point numbers. 3170@ifset GENERIC 3171The exact kind of floating point numbers emitted depends on how 3172@code{@value{AS}} is configured. @xref{Machine Dependencies}. 3173@end ifset 3174@ifclear GENERIC 3175@ifset IEEEFLOAT 3176On the @value{TARGET} family @samp{.double} emits 64-bit floating-point numbers 3177in @sc{ieee} format. 3178@end ifset 3179@end ifclear 3180 3181@node Eject 3182@section @code{.eject} 3183 3184@cindex @code{eject} directive 3185@cindex new page, in listings 3186@cindex page, in listings 3187@cindex listing control: new page 3188Force a page break at this point, when generating assembly listings. 3189 3190@node Else 3191@section @code{.else} 3192 3193@cindex @code{else} directive 3194@code{.else} is part of the @code{@value{AS}} support for conditional 3195assembly; @pxref{If,,@code{.if}}. It marks the beginning of a section 3196of code to be assembled if the condition for the preceding @code{.if} 3197was false. 3198 3199@ignore 3200@node End, Endef, Else, Pseudo Ops 3201@section @code{.end} 3202 3203@cindex @code{end} directive 3204This doesn't do anything---but isn't an s_ignore, so I suspect it's 3205meant to do something eventually (which is why it isn't documented here 3206as "for compatibility with blah"). 3207@end ignore 3208 3209@ifset COFF 3210@node Endef 3211@section @code{.endef} 3212 3213@cindex @code{endef} directive 3214This directive flags the end of a symbol definition begun with 3215@code{.def}. 3216@ifset BOUT 3217 3218@samp{.endef} is only meaningful when generating COFF format output; if 3219@code{@value{AS}} is configured to generate @code{b.out}, it accepts this 3220directive but ignores it. 3221@end ifset 3222@end ifset 3223 3224@node Endif 3225@section @code{.endif} 3226 3227@cindex @code{endif} directive 3228@code{.endif} is part of the @code{@value{AS}} support for conditional assembly; 3229it marks the end of a block of code that is only assembled 3230conditionally. @xref{If,,@code{.if}}. 3231 3232@node Equ 3233@section @code{.equ @var{symbol}, @var{expression}} 3234 3235@cindex @code{equ} directive 3236@cindex assigning values to symbols 3237@cindex symbols, assigning values to 3238This directive sets the value of @var{symbol} to @var{expression}. 3239It is synonymous with @samp{.set}; @pxref{Set,,@code{.set}}. 3240 3241@ifset HPPA 3242The syntax for @code{equ} on the HPPA is 3243@samp{@var{symbol} .equ @var{expression}}. 3244@end ifset 3245 3246@node Extern 3247@section @code{.extern} 3248 3249@cindex @code{extern} directive 3250@code{.extern} is accepted in the source program---for compatibility 3251with other assemblers---but it is ignored. @code{@value{AS}} treats 3252all undefined symbols as external. 3253 3254@ifclear no-file-dir 3255@node File 3256@section @code{.file @var{string}} 3257 3258@cindex @code{file} directive 3259@cindex logical file name 3260@cindex file name, logical 3261@code{.file} (which may also be spelled @samp{.app-file}) tells 3262@code{@value{AS}} that we are about to start a new logical file. 3263@var{string} is the new file name. In general, the filename is 3264recognized whether or not it is surrounded by quotes @samp{"}; but if 3265you wish to specify an empty file name, you must give the 3266quotes--@code{""}. This statement may go away in future: it is only 3267recognized to be compatible with old @code{@value{AS}} programs. 3268@ifset A29K 3269In some configurations of @code{@value{AS}}, @code{.file} has already been 3270removed to avoid conflicts with other assemblers. @xref{Machine Dependencies}. 3271@end ifset 3272@end ifclear 3273 3274@node Fill 3275@section @code{.fill @var{repeat} , @var{size} , @var{value}} 3276 3277@cindex @code{fill} directive 3278@cindex writing patterns in memory 3279@cindex patterns, writing in memory 3280@var{result}, @var{size} and @var{value} are absolute expressions. 3281This emits @var{repeat} copies of @var{size} bytes. @var{Repeat} 3282may be zero or more. @var{Size} may be zero or more, but if it is 3283more than 8, then it is deemed to have the value 8, compatible with 3284other people's assemblers. The contents of each @var{repeat} bytes 3285is taken from an 8-byte number. The highest order 4 bytes are 3286zero. The lowest order 4 bytes are @var{value} rendered in the 3287byte-order of an integer on the computer @code{@value{AS}} is assembling for. 3288Each @var{size} bytes in a repetition is taken from the lowest order 3289@var{size} bytes of this number. Again, this bizarre behavior is 3290compatible with other people's assemblers. 3291 3292@var{size} and @var{value} are optional. 3293If the second comma and @var{value} are absent, @var{value} is 3294assumed zero. If the first comma and following tokens are absent, 3295@var{size} is assumed to be 1. 3296 3297@node Float 3298@section @code{.float @var{flonums}} 3299 3300@cindex floating point numbers (single) 3301@cindex @code{float} directive 3302This directive assembles zero or more flonums, separated by commas. It 3303has the same effect as @code{.single}. 3304@ifset GENERIC 3305The exact kind of floating point numbers emitted depends on how 3306@code{@value{AS}} is configured. 3307@xref{Machine Dependencies}. 3308@end ifset 3309@ifclear GENERIC 3310@ifset IEEEFLOAT 3311On the @value{TARGET} family, @code{.float} emits 32-bit floating point numbers 3312in @sc{ieee} format. 3313@end ifset 3314@end ifclear 3315 3316@node Global 3317@section @code{.global @var{symbol}}, @code{.globl @var{symbol}} 3318 3319@cindex @code{global} directive 3320@cindex symbol, making visible to linker 3321@code{.global} makes the symbol visible to @code{@value{LD}}. If you define 3322@var{symbol} in your partial program, its value is made available to 3323other partial programs that are linked with it. Otherwise, 3324@var{symbol} takes its attributes from a symbol of the same name 3325from another file linked into the same program. 3326 3327Both spellings (@samp{.globl} and @samp{.global}) are accepted, for 3328compatibility with other assemblers. 3329 3330@ifset HPPA 3331On the HPPA, @code{.global} is not always enough to make it accessible to other 3332partial programs. You may need the HPPA-only @code{.EXPORT} directive as well. 3333@xref{HPPA Directives,, HPPA Assembler Directives}. 3334@end ifset 3335 3336@node hword 3337@section @code{.hword @var{expressions}} 3338 3339@cindex @code{hword} directive 3340@cindex integers, 16-bit 3341@cindex numbers, 16-bit 3342@cindex sixteen bit integers 3343This expects zero or more @var{expressions}, and emits 3344a 16 bit number for each. 3345 3346@ifset GENERIC 3347This directive is a synonym for @samp{.short}; depending on the target 3348architecture, it may also be a synonym for @samp{.word}. 3349@end ifset 3350@ifclear GENERIC 3351@ifset W32 3352This directive is a synonym for @samp{.short}. 3353@end ifset 3354@ifset W16 3355This directive is a synonym for both @samp{.short} and @samp{.word}. 3356@end ifset 3357@end ifclear 3358 3359@node Ident 3360@section @code{.ident} 3361 3362@cindex @code{ident} directive 3363This directive is used by some assemblers to place tags in object files. 3364@code{@value{AS}} simply accepts the directive for source-file 3365compatibility with such assemblers, but does not actually emit anything 3366for it. 3367 3368@node If 3369@section @code{.if @var{absolute expression}} 3370 3371@cindex conditional assembly 3372@cindex @code{if} directive 3373@code{.if} marks the beginning of a section of code which is only 3374considered part of the source program being assembled if the argument 3375(which must be an @var{absolute expression}) is non-zero. The end of 3376the conditional section of code must be marked by @code{.endif} 3377(@pxref{Endif,,@code{.endif}}); optionally, you may include code for the 3378alternative condition, flagged by @code{.else} (@pxref{Else,,@code{.else}}). 3379 3380The following variants of @code{.if} are also supported: 3381@table @code 3382@cindex @code{ifdef} directive 3383@item .ifdef @var{symbol} 3384Assembles the following section of code if the specified @var{symbol} 3385has been defined. 3386 3387@ignore 3388@cindex @code{ifeqs} directive 3389@item .ifeqs 3390Not yet implemented. 3391@end ignore 3392 3393@cindex @code{ifndef} directive 3394@cindex @code{ifnotdef} directive 3395@item .ifndef @var{symbol} 3396@itemx .ifnotdef @var{symbol} 3397Assembles the following section of code if the specified @var{symbol} 3398has not been defined. Both spelling variants are equivalent. 3399 3400@ignore 3401@item ifnes 3402Not yet implemented. 3403@end ignore 3404@end table 3405 3406@node Include 3407@section @code{.include "@var{file}"} 3408 3409@cindex @code{include} directive 3410@cindex supporting files, including 3411@cindex files, including 3412This directive provides a way to include supporting files at specified 3413points in your source program. The code from @var{file} is assembled as 3414if it followed the point of the @code{.include}; when the end of the 3415included file is reached, assembly of the original file continues. You 3416can control the search paths used with the @samp{-I} command-line option 3417(@pxref{Invoking,,Command-Line Options}). Quotation marks are required 3418around @var{file}. 3419 3420@node Int 3421@section @code{.int @var{expressions}} 3422 3423@cindex @code{int} directive 3424@cindex integers, 32-bit 3425Expect zero or more @var{expressions}, of any section, separated by commas. 3426For each expression, emit a number that, at run time, is the value of that 3427expression. The byte order and bit size of the number depends on what kind 3428of target the assembly is for. 3429 3430@ifclear GENERIC 3431@ifset H8 3432On the H8/500 and most forms of the H8/300, @code{.int} emits 16-bit 3433integers. On the H8/300H and the Hitachi SH, however, @code{.int} emits 343432-bit integers. 3435@end ifset 3436@end ifclear 3437 3438@node Irp 3439@section @code{.irp @var{symbol},@var{values}}@dots{} 3440 3441@cindex @code{irp} directive 3442Evaluate a sequence of statements assigning different values to @var{symbol}. 3443The sequence of statements starts at the @code{.irp} directive, and is 3444terminated by an @code{.endr} directive. For each @var{value}, @var{symbol} is 3445set to @var{value}, and the sequence of statements is assembled. If no 3446@var{value} is listed, the sequence of statements is assembled once, with 3447@var{symbol} set to the null string. To refer to @var{symbol} within the 3448sequence of statements, use @var{\symbol}. 3449 3450For example, assembling 3451 3452@example 3453 .irp param,1,2,3 3454 move d\param,sp@@- 3455 .endr 3456@end example 3457 3458is equivalent to assembling 3459 3460@example 3461 move d1,sp@@- 3462 move d2,sp@@- 3463 move d3,sp@@- 3464@end example 3465 3466@node Irpc 3467@section @code{.irpc @var{symbol},@var{values}}@dots{} 3468 3469@cindex @code{irpc} directive 3470Evaluate a sequence of statements assigning different values to @var{symbol}. 3471The sequence of statements starts at the @code{.irpc} directive, and is 3472terminated by an @code{.endr} directive. For each character in @var{value}, 3473@var{symbol} is set to the character, and the sequence of statements is 3474assembled. If no @var{value} is listed, the sequence of statements is 3475assembled once, with @var{symbol} set to the null string. To refer to 3476@var{symbol} within the sequence of statements, use @var{\symbol}. 3477 3478For example, assembling 3479 3480@example 3481 .irpc param,123 3482 move d\param,sp@@- 3483 .endr 3484@end example 3485 3486is equivalent to assembling 3487 3488@example 3489 move d1,sp@@- 3490 move d2,sp@@- 3491 move d3,sp@@- 3492@end example 3493 3494@node Lcomm 3495@section @code{.lcomm @var{symbol} , @var{length}} 3496 3497@cindex @code{lcomm} directive 3498@cindex local common symbols 3499@cindex symbols, local common 3500Reserve @var{length} (an absolute expression) bytes for a local common 3501denoted by @var{symbol}. The section and value of @var{symbol} are 3502those of the new local common. The addresses are allocated in the bss 3503section, so that at run-time the bytes start off zeroed. @var{Symbol} 3504is not declared global (@pxref{Global,,@code{.global}}), so is normally 3505not visible to @code{@value{LD}}. 3506 3507@ifset HPPA 3508The syntax for @code{.lcomm} differs slightly on the HPPA. The syntax is 3509@samp{@var{symbol} .lcomm, @var{length}}; @var{symbol} is optional. 3510@end ifset 3511 3512@node Lflags 3513@section @code{.lflags} 3514 3515@cindex @code{lflags} directive (ignored) 3516@code{@value{AS}} accepts this directive, for compatibility with other 3517assemblers, but ignores it. 3518 3519@ifclear no-line-dir 3520@node Line 3521@section @code{.line @var{line-number}} 3522 3523@cindex @code{line} directive 3524@end ifclear 3525@ifset no-line-dir 3526@node Ln 3527@section @code{.ln @var{line-number}} 3528 3529@cindex @code{ln} directive 3530@end ifset 3531@cindex logical line number 3532@ifset aout-bout 3533Change the logical line number. @var{line-number} must be an absolute 3534expression. The next line has that logical line number. Therefore any other 3535statements on the current line (after a statement separator character) are 3536reported as on logical line number @var{line-number} @minus{} 1. One day 3537@code{@value{AS}} will no longer support this directive: it is recognized only 3538for compatibility with existing assembler programs. 3539 3540@ifset GENERIC 3541@ifset A29K 3542@emph{Warning:} In the AMD29K configuration of @value{AS}, this command is 3543not available; use the synonym @code{.ln} in that context. 3544@end ifset 3545@end ifset 3546@end ifset 3547 3548@ifclear no-line-dir 3549Even though this is a directive associated with the @code{a.out} or 3550@code{b.out} object-code formats, @code{@value{AS}} still recognizes it 3551when producing COFF output, and treats @samp{.line} as though it 3552were the COFF @samp{.ln} @emph{if} it is found outside a 3553@code{.def}/@code{.endef} pair. 3554 3555Inside a @code{.def}, @samp{.line} is, instead, one of the directives 3556used by compilers to generate auxiliary symbol information for 3557debugging. 3558@end ifclear 3559 3560@node Linkonce 3561@section @code{.linkonce [@var{type}]} 3562@cindex COMDAT 3563@cindex @code{linkonce} directive 3564@cindex common sections 3565Mark the current section so that the linker only includes a single copy of it. 3566This may be used to include the same section in several different object files, 3567but ensure that the linker will only include it once in the final output file. 3568The @code{.linkonce} pseudo-op must be used for each instance of the section. 3569Duplicate sections are detected based on the section name, so it should be 3570unique. 3571 3572This directive is only supported by a few object file formats; as of this 3573writing, the only object file format which supports it is the Portable 3574Executable format used on Windows NT. 3575 3576The @var{type} argument is optional. If specified, it must be one of the 3577following strings. For example: 3578@smallexample 3579.linkonce same_size 3580@end smallexample 3581Not all types may be supported on all object file formats. 3582 3583@table @code 3584@item discard 3585Silently discard duplicate sections. This is the default. 3586 3587@item one_only 3588Warn if there are duplicate sections, but still keep only one copy. 3589 3590@item same_size 3591Warn if any of the duplicates have different sizes. 3592 3593@item same_contents 3594Warn if any of the duplicates do not have exactly the same contents. 3595@end table 3596 3597@node Ln 3598@section @code{.ln @var{line-number}} 3599 3600@cindex @code{ln} directive 3601@ifclear no-line-dir 3602@samp{.ln} is a synonym for @samp{.line}. 3603@end ifclear 3604@ifset no-line-dir 3605Tell @code{@value{AS}} to change the logical line number. @var{line-number} 3606must be an absolute expression. The next line has that logical 3607line number, so any other statements on the current line (after a 3608statement separator character @code{;}) are reported as on logical 3609line number @var{line-number} @minus{} 1. 3610@ifset BOUT 3611 3612This directive is accepted, but ignored, when @code{@value{AS}} is 3613configured for @code{b.out}; its effect is only associated with COFF 3614output format. 3615@end ifset 3616@end ifset 3617 3618@node MRI 3619@section @code{.mri @var{val}} 3620 3621@cindex @code{mri} directive 3622@cindex MRI mode, temporarily 3623If @var{val} is non-zero, this tells @code{@value{AS}} to enter MRI mode. If 3624@var{val} is zero, this tells @code{@value{AS}} to exit MRI mode. This change 3625affects code assembled until the next @code{.mri} directive, or until the end 3626of the file. @xref{M, MRI mode, MRI mode}. 3627 3628@node List 3629@section @code{.list} 3630 3631@cindex @code{list} directive 3632@cindex listing control, turning on 3633Control (in conjunction with the @code{.nolist} directive) whether or 3634not assembly listings are generated. These two directives maintain an 3635internal counter (which is zero initially). @code{.list} increments the 3636counter, and @code{.nolist} decrements it. Assembly listings are 3637generated whenever the counter is greater than zero. 3638 3639By default, listings are disabled. When you enable them (with the 3640@samp{-a} command line option; @pxref{Invoking,,Command-Line Options}), 3641the initial value of the listing counter is one. 3642 3643@node Long 3644@section @code{.long @var{expressions}} 3645 3646@cindex @code{long} directive 3647@code{.long} is the same as @samp{.int}, @pxref{Int,,@code{.int}}. 3648 3649@ignore 3650@c no one seems to know what this is for or whether this description is 3651@c what it really ought to do 3652@node Lsym 3653@section @code{.lsym @var{symbol}, @var{expression}} 3654 3655@cindex @code{lsym} directive 3656@cindex symbol, not referenced in assembly 3657@code{.lsym} creates a new symbol named @var{symbol}, but does not put it in 3658the hash table, ensuring it cannot be referenced by name during the 3659rest of the assembly. This sets the attributes of the symbol to be 3660the same as the expression value: 3661@smallexample 3662@var{other} = @var{descriptor} = 0 3663@var{type} = @r{(section of @var{expression})} 3664@var{value} = @var{expression} 3665@end smallexample 3666@noindent 3667The new symbol is not flagged as external. 3668@end ignore 3669 3670@node Macro 3671@section @code{.macro} 3672 3673@cindex macros 3674The commands @code{.macro} and @code{.endm} allow you to define macros that 3675generate assembly output. For example, this definition specifies a macro 3676@code{sum} that puts a sequence of numbers into memory: 3677 3678@example 3679 .macro sum from=0, to=5 3680 .long \from 3681 .if \to-\from 3682 sum "(\from+1)",\to 3683 .endif 3684 .endm 3685@end example 3686 3687@noindent 3688With that definition, @samp{SUM 0,5} is equivalent to this assembly input: 3689 3690@example 3691 .long 0 3692 .long 1 3693 .long 2 3694 .long 3 3695 .long 4 3696 .long 5 3697@end example 3698 3699@ftable @code 3700@item .macro @var{macname} 3701@itemx .macro @var{macname} @var{macargs} @dots{} 3702@cindex @code{macro} directive 3703Begin the definition of a macro called @var{macname}. If your macro 3704definition requires arguments, specify their names after the macro name, 3705separated by commas or spaces. You can supply a default value for any 3706macro argument by following the name with @samp{=@var{deflt}}. For 3707example, these are all valid @code{.macro} statements: 3708 3709@table @code 3710@item .macro comm 3711Begin the definition of a macro called @code{comm}, which takes no 3712arguments. 3713 3714@item .macro plus1 p, p1 3715@itemx .macro plus1 p p1 3716Either statement begins the definition of a macro called @code{plus1}, 3717which takes two arguments; within the macro definition, write 3718@samp{\p} or @samp{\p1} to evaluate the arguments. 3719 3720@item .macro reserve_str p1=0 p2 3721Begin the definition of a macro called @code{reserve_str}, with two 3722arguments. The first argument has a default value, but not the second. 3723After the definition is complete, you can call the macro either as 3724@samp{reserve_str @var{a},@var{b}} (with @samp{\p1} evaluating to 3725@var{a} and @samp{\p2} evaluating to @var{b}), or as @samp{reserve_str 3726,@var{b}} (with @samp{\p1} evaluating as the default, in this case 3727@samp{0}, and @samp{\p2} evaluating to @var{b}). 3728@end table 3729 3730When you call a macro, you can specify the argument values either by 3731position, or by keyword. For example, @samp{sum 9,17} is equivalent to 3732@samp{sum to=17, from=9}. 3733 3734@item .endm 3735@cindex @code{endm} directive 3736Mark the end of a macro definition. 3737 3738@item .exitm 3739@cindex @code{exitm} directive 3740Exit early from the current macro definition. 3741 3742@cindex number of macros executed 3743@cindex macros, count executed 3744@item \@@ 3745@code{@value{AS}} maintains a counter of how many macros it has 3746executed in this pseudo-variable; you can copy that number to your 3747output with @samp{\@@}, but @emph{only within a macro definition}. 3748 3749@ignore 3750@item LOCAL @var{name} [ , @dots{} ] 3751@emph{Warning: @code{LOCAL} is only available if you select ``alternate 3752macro syntax'' with @samp{-a} or @samp{--alternate}.} @xref{Alternate,, 3753Alternate macro syntax}. 3754 3755Generate a string replacement for each of the @var{name} arguments, and 3756replace any instances of @var{name} in each macro expansion. The 3757replacement string is unique in the assembly, and different for each 3758separate macro expansion. @code{LOCAL} allows you to write macros that 3759define symbols, without fear of conflict between separate macro expansions. 3760@end ignore 3761@end ftable 3762 3763@node Nolist 3764@section @code{.nolist} 3765 3766@cindex @code{nolist} directive 3767@cindex listing control, turning off 3768Control (in conjunction with the @code{.list} directive) whether or 3769not assembly listings are generated. These two directives maintain an 3770internal counter (which is zero initially). @code{.list} increments the 3771counter, and @code{.nolist} decrements it. Assembly listings are 3772generated whenever the counter is greater than zero. 3773 3774@node Octa 3775@section @code{.octa @var{bignums}} 3776 3777@c FIXME: double size emitted for "octa" on i960, others? Or warn? 3778@cindex @code{octa} directive 3779@cindex integer, 16-byte 3780@cindex sixteen byte integer 3781This directive expects zero or more bignums, separated by commas. For each 3782bignum, it emits a 16-byte integer. 3783 3784The term ``octa'' comes from contexts in which a ``word'' is two bytes; 3785hence @emph{octa}-word for 16 bytes. 3786 3787@node Org 3788@section @code{.org @var{new-lc} , @var{fill}} 3789 3790@cindex @code{org} directive 3791@cindex location counter, advancing 3792@cindex advancing location counter 3793@cindex current address, advancing 3794Advance the location counter of the current section to 3795@var{new-lc}. @var{new-lc} is either an absolute expression or an 3796expression with the same section as the current subsection. That is, 3797you can't use @code{.org} to cross sections: if @var{new-lc} has the 3798wrong section, the @code{.org} directive is ignored. To be compatible 3799with former assemblers, if the section of @var{new-lc} is absolute, 3800@code{@value{AS}} issues a warning, then pretends the section of @var{new-lc} 3801is the same as the current subsection. 3802 3803@code{.org} may only increase the location counter, or leave it 3804unchanged; you cannot use @code{.org} to move the location counter 3805backwards. 3806 3807@c double negative used below "not undefined" because this is a specific 3808@c reference to "undefined" (as SEG_UNKNOWN is called in this manual) 3809@c section. doc@cygnus.com 18feb91 3810Because @code{@value{AS}} tries to assemble programs in one pass, @var{new-lc} 3811may not be undefined. If you really detest this restriction we eagerly await 3812a chance to share your improved assembler. 3813 3814Beware that the origin is relative to the start of the section, not 3815to the start of the subsection. This is compatible with other 3816people's assemblers. 3817 3818When the location counter (of the current subsection) is advanced, the 3819intervening bytes are filled with @var{fill} which should be an 3820absolute expression. If the comma and @var{fill} are omitted, 3821@var{fill} defaults to zero. 3822 3823@node P2align 3824@section @code{.p2align[wl] @var{abs-expr} , @var{abs-expr}} 3825 3826@cindex padding the location counter given a power of two 3827@cindex @code{p2align} directive 3828Pad the location counter (in the current subsection) to a particular 3829storage boundary. The first expression (which must be absolute) is the 3830number of low-order zero bits the location counter must have after 3831advancement. For example @samp{.p2align 3} advances the location 3832counter until it a multiple of 8. If the location counter is already a 3833multiple of 8, no change is needed. 3834 3835The second expression (also absolute) gives the value to be stored in 3836the padding bytes. It (and the comma) may be omitted. If it is 3837omitted, the padding bytes are zero. 3838 3839@cindex @code{p2alignw} directive 3840@cindex @code{p2alignl} directive 3841The @code{.p2alignw} and @code{.p2alignl} directives are variants of the 3842@code{.p2align} directive. The @code{.p2alignw} directive treats the fill 3843pattern as a two byte word value. The @code{.p2alignl} directives treats the 3844fill pattern as a four byte longword value. For example, @code{.p2alignw 38452,0x368d} will align to a multiple of 4. If it skips two bytes, they will be 3846filled in with the value 0x368d (the exact placement of the bytes depends upon 3847the endianness of the processor). If it skips 1 or 3 bytes, the fill value is 3848undefined. 3849 3850@node Psize 3851@section @code{.psize @var{lines} , @var{columns}} 3852 3853@cindex @code{psize} directive 3854@cindex listing control: paper size 3855@cindex paper size, for listings 3856Use this directive to declare the number of lines---and, optionally, the 3857number of columns---to use for each page, when generating listings. 3858 3859If you do not use @code{.psize}, listings use a default line-count 3860of 60. You may omit the comma and @var{columns} specification; the 3861default width is 200 columns. 3862 3863@code{@value{AS}} generates formfeeds whenever the specified number of 3864lines is exceeded (or whenever you explicitly request one, using 3865@code{.eject}). 3866 3867If you specify @var{lines} as @code{0}, no formfeeds are generated save 3868those explicitly specified with @code{.eject}. 3869 3870@node Quad 3871@section @code{.quad @var{bignums}} 3872 3873@cindex @code{quad} directive 3874@code{.quad} expects zero or more bignums, separated by commas. For 3875each bignum, it emits 3876@ifclear bignum-16 3877an 8-byte integer. If the bignum won't fit in 8 bytes, it prints a 3878warning message; and just takes the lowest order 8 bytes of the bignum. 3879@cindex eight-byte integer 3880@cindex integer, 8-byte 3881 3882The term ``quad'' comes from contexts in which a ``word'' is two bytes; 3883hence @emph{quad}-word for 8 bytes. 3884@end ifclear 3885@ifset bignum-16 3886a 16-byte integer. If the bignum won't fit in 16 bytes, it prints a 3887warning message; and just takes the lowest order 16 bytes of the bignum. 3888@cindex sixteen-byte integer 3889@cindex integer, 16-byte 3890@end ifset 3891 3892@node Rept 3893@section @code{.rept @var{count}} 3894 3895@cindex @code{rept} directive 3896Repeat the sequence of lines between the @code{.rept} directive and the next 3897@code{.endr} directive @var{count} times. 3898 3899For example, assembling 3900 3901@example 3902 .rept 3 3903 .long 0 3904 .endr 3905@end example 3906 3907is equivalent to assembling 3908 3909@example 3910 .long 0 3911 .long 0 3912 .long 0 3913@end example 3914 3915@node Sbttl 3916@section @code{.sbttl "@var{subheading}"} 3917 3918@cindex @code{sbttl} directive 3919@cindex subtitles for listings 3920@cindex listing control: subtitle 3921Use @var{subheading} as the title (third line, immediately after the 3922title line) when generating assembly listings. 3923 3924This directive affects subsequent pages, as well as the current page if 3925it appears within ten lines of the top of a page. 3926 3927@ifset COFF 3928@node Scl 3929@section @code{.scl @var{class}} 3930 3931@cindex @code{scl} directive 3932@cindex symbol storage class (COFF) 3933@cindex COFF symbol storage class 3934Set the storage-class value for a symbol. This directive may only be 3935used inside a @code{.def}/@code{.endef} pair. Storage class may flag 3936whether a symbol is static or external, or it may record further 3937symbolic debugging information. 3938@ifset BOUT 3939 3940The @samp{.scl} directive is primarily associated with COFF output; when 3941configured to generate @code{b.out} output format, @code{@value{AS}} 3942accepts this directive but ignores it. 3943@end ifset 3944@end ifset 3945 3946@ifset COFF 3947@node Section 3948@section @code{.section @var{name}, @var{subsection}} 3949 3950@cindex @code{section} directive 3951@cindex named section (COFF) 3952@cindex COFF named section 3953Assemble the following code into end of subsection numbered 3954@var{subsection} in the COFF named section @var{name}. If you omit 3955@var{subsection}, @code{@value{AS}} uses subsection number zero. 3956@samp{.section .text} is equivalent to the @code{.text} directive; 3957@samp{.section .data} is equivalent to the @code{.data} directive. 3958@ifset GENERIC 3959This directive is only supported for targets that actually support arbitrarily 3960named sections; on @code{a.out} targets, for example, it is not accepted, even 3961with a standard @code{a.out} section name as its parameter. 3962@end ifset 3963@end ifset 3964 3965@node Set 3966@section @code{.set @var{symbol}, @var{expression}} 3967 3968@cindex @code{set} directive 3969@cindex symbol value, setting 3970Set the value of @var{symbol} to @var{expression}. This 3971changes @var{symbol}'s value and type to conform to 3972@var{expression}. If @var{symbol} was flagged as external, it remains 3973flagged. (@xref{Symbol Attributes}.) 3974 3975You may @code{.set} a symbol many times in the same assembly. 3976 3977If you @code{.set} a global symbol, the value stored in the object 3978file is the last value stored into it. 3979 3980@ifset HPPA 3981The syntax for @code{set} on the HPPA is 3982@samp{@var{symbol} .set @var{expression}}. 3983@end ifset 3984 3985@node Short 3986@section @code{.short @var{expressions}} 3987 3988@cindex @code{short} directive 3989@ifset GENERIC 3990@code{.short} is normally the same as @samp{.word}. 3991@xref{Word,,@code{.word}}. 3992 3993In some configurations, however, @code{.short} and @code{.word} generate 3994numbers of different lengths; @pxref{Machine Dependencies}. 3995@end ifset 3996@ifclear GENERIC 3997@ifset W16 3998@code{.short} is the same as @samp{.word}. @xref{Word,,@code{.word}}. 3999@end ifset 4000@ifset W32 4001This expects zero or more @var{expressions}, and emits 4002a 16 bit number for each. 4003@end ifset 4004@end ifclear 4005 4006@node Single 4007@section @code{.single @var{flonums}} 4008 4009@cindex @code{single} directive 4010@cindex floating point numbers (single) 4011This directive assembles zero or more flonums, separated by commas. It 4012has the same effect as @code{.float}. 4013@ifset GENERIC 4014The exact kind of floating point numbers emitted depends on how 4015@code{@value{AS}} is configured. @xref{Machine Dependencies}. 4016@end ifset 4017@ifclear GENERIC 4018@ifset IEEEFLOAT 4019On the @value{TARGET} family, @code{.single} emits 32-bit floating point 4020numbers in @sc{ieee} format. 4021@end ifset 4022@end ifclear 4023 4024@ifset COFF 4025@node Size 4026@section @code{.size} 4027 4028@cindex @code{size} directive 4029This directive is generated by compilers to include auxiliary debugging 4030information in the symbol table. It is only permitted inside 4031@code{.def}/@code{.endef} pairs. 4032@ifset BOUT 4033 4034@samp{.size} is only meaningful when generating COFF format output; when 4035@code{@value{AS}} is generating @code{b.out}, it accepts this directive but 4036ignores it. 4037@end ifset 4038@end ifset 4039 4040@ifclear no-space-dir 4041@node Skip 4042@section @code{.skip @var{size} , @var{fill}} 4043 4044@cindex @code{skip} directive 4045@cindex filling memory 4046This directive emits @var{size} bytes, each of value @var{fill}. Both 4047@var{size} and @var{fill} are absolute expressions. If the comma and 4048@var{fill} are omitted, @var{fill} is assumed to be zero. This is the same as 4049@samp{.space}. 4050 4051@node Space 4052@section @code{.space @var{size} , @var{fill}} 4053 4054@cindex @code{space} directive 4055@cindex filling memory 4056This directive emits @var{size} bytes, each of value @var{fill}. Both 4057@var{size} and @var{fill} are absolute expressions. If the comma 4058and @var{fill} are omitted, @var{fill} is assumed to be zero. This is the same 4059as @samp{.skip}. 4060 4061@ifset HPPA 4062@quotation 4063@emph{Warning:} @code{.space} has a completely different meaning for HPPA 4064targets; use @code{.block} as a substitute. See @cite{HP9000 Series 800 4065Assembly Language Reference Manual} (HP 92432-90001) for the meaning of the 4066@code{.space} directive. @xref{HPPA Directives,,HPPA Assembler Directives}, 4067for a summary. 4068@end quotation 4069@end ifset 4070@end ifclear 4071 4072@ifset A29K 4073@ifclear GENERIC 4074@node Space 4075@section @code{.space} 4076@cindex @code{space} directive 4077@end ifclear 4078On the AMD 29K, this directive is ignored; it is accepted for 4079compatibility with other AMD 29K assemblers. 4080 4081@quotation 4082@emph{Warning:} In most versions of the @sc{gnu} assembler, the directive 4083@code{.space} has the effect of @code{.block} @xref{Machine Dependencies}. 4084@end quotation 4085@end ifset 4086 4087@ifset have-stabs 4088@node Stab 4089@section @code{.stabd, .stabn, .stabs} 4090 4091@cindex symbolic debuggers, information for 4092@cindex @code{stab@var{x}} directives 4093There are three directives that begin @samp{.stab}. 4094All emit symbols (@pxref{Symbols}), for use by symbolic debuggers. 4095The symbols are not entered in the @code{@value{AS}} hash table: they 4096cannot be referenced elsewhere in the source file. 4097Up to five fields are required: 4098 4099@table @var 4100@item string 4101This is the symbol's name. It may contain any character except 4102@samp{\000}, so is more general than ordinary symbol names. Some 4103debuggers used to code arbitrarily complex structures into symbol names 4104using this field. 4105 4106@item type 4107An absolute expression. The symbol's type is set to the low 8 bits of 4108this expression. Any bit pattern is permitted, but @code{@value{LD}} 4109and debuggers choke on silly bit patterns. 4110 4111@item other 4112An absolute expression. The symbol's ``other'' attribute is set to the 4113low 8 bits of this expression. 4114 4115@item desc 4116An absolute expression. The symbol's descriptor is set to the low 16 4117bits of this expression. 4118 4119@item value 4120An absolute expression which becomes the symbol's value. 4121@end table 4122 4123If a warning is detected while reading a @code{.stabd}, @code{.stabn}, 4124or @code{.stabs} statement, the symbol has probably already been created; 4125you get a half-formed symbol in your object file. This is 4126compatible with earlier assemblers! 4127 4128@table @code 4129@cindex @code{stabd} directive 4130@item .stabd @var{type} , @var{other} , @var{desc} 4131 4132The ``name'' of the symbol generated is not even an empty string. 4133It is a null pointer, for compatibility. Older assemblers used a 4134null pointer so they didn't waste space in object files with empty 4135strings. 4136 4137The symbol's value is set to the location counter, 4138relocatably. When your program is linked, the value of this symbol 4139is the address of the location counter when the @code{.stabd} was 4140assembled. 4141 4142@cindex @code{stabn} directive 4143@item .stabn @var{type} , @var{other} , @var{desc} , @var{value} 4144The name of the symbol is set to the empty string @code{""}. 4145 4146@cindex @code{stabs} directive 4147@item .stabs @var{string} , @var{type} , @var{other} , @var{desc} , @var{value} 4148All five fields are specified. 4149@end table 4150@end ifset 4151@c end have-stabs 4152 4153@node String 4154@section @code{.string} "@var{str}" 4155 4156@cindex string, copying to object file 4157@cindex @code{string} directive 4158 4159Copy the characters in @var{str} to the object file. You may specify more than 4160one string to copy, separated by commas. Unless otherwise specified for a 4161particular machine, the assembler marks the end of each string with a 0 byte. 4162You can use any of the escape sequences described in @ref{Strings,,Strings}. 4163 4164@ifset COFF 4165@node Tag 4166@section @code{.tag @var{structname}} 4167 4168@cindex COFF structure debugging 4169@cindex structure debugging, COFF 4170@cindex @code{tag} directive 4171This directive is generated by compilers to include auxiliary debugging 4172information in the symbol table. It is only permitted inside 4173@code{.def}/@code{.endef} pairs. Tags are used to link structure 4174definitions in the symbol table with instances of those structures. 4175@ifset BOUT 4176 4177@samp{.tag} is only used when generating COFF format output; when 4178@code{@value{AS}} is generating @code{b.out}, it accepts this directive but 4179ignores it. 4180@end ifset 4181@end ifset 4182 4183@node Text 4184@section @code{.text @var{subsection}} 4185 4186@cindex @code{text} directive 4187Tells @code{@value{AS}} to assemble the following statements onto the end of 4188the text subsection numbered @var{subsection}, which is an absolute 4189expression. If @var{subsection} is omitted, subsection number zero 4190is used. 4191 4192@node Title 4193@section @code{.title "@var{heading}"} 4194 4195@cindex @code{title} directive 4196@cindex listing control: title line 4197Use @var{heading} as the title (second line, immediately after the 4198source file name and pagenumber) when generating assembly listings. 4199 4200This directive affects subsequent pages, as well as the current page if 4201it appears within ten lines of the top of a page. 4202 4203@ifset COFF 4204@node Type 4205@section @code{.type @var{int}} 4206 4207@cindex COFF symbol type 4208@cindex symbol type, COFF 4209@cindex @code{type} directive 4210This directive, permitted only within @code{.def}/@code{.endef} pairs, 4211records the integer @var{int} as the type attribute of a symbol table entry. 4212@ifset BOUT 4213 4214@samp{.type} is associated only with COFF format output; when 4215@code{@value{AS}} is configured for @code{b.out} output, it accepts this 4216directive but ignores it. 4217@end ifset 4218@end ifset 4219 4220@ifset COFF 4221@node Val 4222@section @code{.val @var{addr}} 4223 4224@cindex @code{val} directive 4225@cindex COFF value attribute 4226@cindex value attribute, COFF 4227This directive, permitted only within @code{.def}/@code{.endef} pairs, 4228records the address @var{addr} as the value attribute of a symbol table 4229entry. 4230@ifset BOUT 4231 4232@samp{.val} is used only for COFF output; when @code{@value{AS}} is 4233configured for @code{b.out}, it accepts this directive but ignores it. 4234@end ifset 4235@end ifset 4236 4237@node Word 4238@section @code{.word @var{expressions}} 4239 4240@cindex @code{word} directive 4241This directive expects zero or more @var{expressions}, of any section, 4242separated by commas. 4243@ifclear GENERIC 4244@ifset W32 4245For each expression, @code{@value{AS}} emits a 32-bit number. 4246@end ifset 4247@ifset W16 4248For each expression, @code{@value{AS}} emits a 16-bit number. 4249@end ifset 4250@end ifclear 4251@ifset GENERIC 4252 4253The size of the number emitted, and its byte order, 4254depend on what target computer the assembly is for. 4255@end ifset 4256 4257@c on amd29k, i960, sparc the "special treatment to support compilers" doesn't 4258@c happen---32-bit addressability, period; no long/short jumps. 4259@ifset DIFF-TBL-KLUGE 4260@cindex difference tables altered 4261@cindex altered difference tables 4262@quotation 4263@emph{Warning: Special Treatment to support Compilers} 4264@end quotation 4265 4266@ifset GENERIC 4267Machines with a 32-bit address space, but that do less than 32-bit 4268addressing, require the following special treatment. If the machine of 4269interest to you does 32-bit addressing (or doesn't require it; 4270@pxref{Machine Dependencies}), you can ignore this issue. 4271 4272@end ifset 4273In order to assemble compiler output into something that works, 4274@code{@value{AS}} occasionlly does strange things to @samp{.word} directives. 4275Directives of the form @samp{.word sym1-sym2} are often emitted by 4276compilers as part of jump tables. Therefore, when @code{@value{AS}} assembles a 4277directive of the form @samp{.word sym1-sym2}, and the difference between 4278@code{sym1} and @code{sym2} does not fit in 16 bits, @code{@value{AS}} 4279creates a @dfn{secondary jump table}, immediately before the next label. 4280This secondary jump table is preceded by a short-jump to the 4281first byte after the secondary table. This short-jump prevents the flow 4282of control from accidentally falling into the new table. Inside the 4283table is a long-jump to @code{sym2}. The original @samp{.word} 4284contains @code{sym1} minus the address of the long-jump to 4285@code{sym2}. 4286 4287If there were several occurrences of @samp{.word sym1-sym2} before the 4288secondary jump table, all of them are adjusted. If there was a 4289@samp{.word sym3-sym4}, that also did not fit in sixteen bits, a 4290long-jump to @code{sym4} is included in the secondary jump table, 4291and the @code{.word} directives are adjusted to contain @code{sym3} 4292minus the address of the long-jump to @code{sym4}; and so on, for as many 4293entries in the original jump table as necessary. 4294 4295@ifset INTERNALS 4296@emph{This feature may be disabled by compiling @code{@value{AS}} with the 4297@samp{-DWORKING_DOT_WORD} option.} This feature is likely to confuse 4298assembly language programmers. 4299@end ifset 4300@end ifset 4301@c end DIFF-TBL-KLUGE 4302 4303@node Deprecated 4304@section Deprecated Directives 4305 4306@cindex deprecated directives 4307@cindex obsolescent directives 4308One day these directives won't work. 4309They are included for compatibility with older assemblers. 4310@table @t 4311@item .abort 4312@item .app-file 4313@item .line 4314@end table 4315 4316@ifset GENERIC 4317@node Machine Dependencies 4318@chapter Machine Dependent Features 4319 4320@cindex machine dependencies 4321The machine instruction sets are (almost by definition) different on 4322each machine where @code{@value{AS}} runs. Floating point representations 4323vary as well, and @code{@value{AS}} often supports a few additional 4324directives or command-line options for compatibility with other 4325assemblers on a particular platform. Finally, some versions of 4326@code{@value{AS}} support special pseudo-instructions for branch 4327optimization. 4328 4329This chapter discusses most of these differences, though it does not 4330include details on any machine's instruction set. For details on that 4331subject, see the hardware manufacturer's manual. 4332 4333@menu 4334@ifset A29K 4335* AMD29K-Dependent:: AMD 29K Dependent Features 4336@end ifset 4337@ifset H8/300 4338* H8/300-Dependent:: Hitachi H8/300 Dependent Features 4339@end ifset 4340@ifset H8/500 4341* H8/500-Dependent:: Hitachi H8/500 Dependent Features 4342@end ifset 4343@ifset HPPA 4344* HPPA-Dependent:: HPPA Dependent Features 4345@end ifset 4346@ifset I80386 4347* i386-Dependent:: Intel 80386 Dependent Features 4348@end ifset 4349@ifset I960 4350* i960-Dependent:: Intel 80960 Dependent Features 4351@end ifset 4352@ifset M680X0 4353* M68K-Dependent:: M680x0 Dependent Features 4354@end ifset 4355@ifset MIPS 4356* MIPS-Dependent:: MIPS Dependent Features 4357@end ifset 4358@ifset SH 4359* SH-Dependent:: Hitachi SH Dependent Features 4360@end ifset 4361@ifset SPARC 4362* Sparc-Dependent:: SPARC Dependent Features 4363@end ifset 4364@ifset Z8000 4365* Z8000-Dependent:: Z8000 Dependent Features 4366@end ifset 4367@ifset VAX 4368* Vax-Dependent:: VAX Dependent Features 4369@end ifset 4370@end menu 4371 4372@lowersections 4373@end ifset 4374 4375@c The following major nodes are *sections* in the GENERIC version, *chapters* 4376@c in single-cpu versions. This is mainly achieved by @lowersections. There is a 4377@c peculiarity: to preserve cross-references, there must be a node called 4378@c "Machine Dependencies". Hence the conditional nodenames in each 4379@c major node below. Node defaulting in makeinfo requires adjacency of 4380@c node and sectioning commands; hence the repetition of @chapter BLAH 4381@c in both conditional blocks. 4382 4383 4384@ifset A29K 4385@include c-a29k.texi 4386@end ifset 4387 4388@ifset Hitachi-all 4389@ifclear GENERIC 4390@node Machine Dependencies 4391@chapter Machine Dependent Features 4392 4393The machine instruction sets are different on each Hitachi chip family, 4394and there are also some syntax differences among the families. This 4395chapter describes the specific @code{@value{AS}} features for each 4396family. 4397 4398@menu 4399* H8/300-Dependent:: Hitachi H8/300 Dependent Features 4400* H8/500-Dependent:: Hitachi H8/500 Dependent Features 4401* SH-Dependent:: Hitachi SH Dependent Features 4402@end menu 4403@lowersections 4404@end ifclear 4405@end ifset 4406 4407 4408@ifset H8/300 4409@include c-h8300.texi 4410@end ifset 4411 4412@ifset H8/500 4413@include c-h8500.texi 4414@end ifset 4415 4416@ifset HPPA 4417@include c-hppa.texi 4418@end ifset 4419 4420@ifset I80386 4421@include c-i386.texi 4422@end ifset 4423 4424@ifset I960 4425@include c-i960.texi 4426@end ifset 4427 4428@ifset M680X0 4429@include c-m68k.texi 4430@end ifset 4431 4432@ifset MIPS 4433@include c-mips.texi 4434@end ifset 4435 4436@ifset NS32K 4437@include c-ns32k.texi 4438@end ifset 4439 4440@ifset SH 4441@include c-sh.texi 4442@end ifset 4443 4444@ifset SPARC 4445@include c-sparc.texi 4446@end ifset 4447 4448@ifset Z8000 4449@include c-z8k.texi 4450@end ifset 4451 4452@ifset VAX 4453@include c-vax.texi 4454@end ifset 4455 4456@ifset GENERIC 4457@c reverse effect of @down at top of generic Machine-Dep chapter 4458@raisesections 4459@end ifset 4460 4461@node Reporting Bugs 4462@chapter Reporting Bugs 4463@cindex bugs in @code{@value{AS}} 4464@cindex reporting bugs in @code{@value{AS}} 4465 4466Your bug reports play an essential role in making @code{@value{AS}} reliable. 4467 4468Reporting a bug may help you by bringing a solution to your problem, or it may 4469not. But in any case the principal function of a bug report is to help the 4470entire community by making the next version of @code{@value{AS}} work better. 4471Bug reports are your contribution to the maintenance of @code{@value{AS}}. 4472 4473In order for a bug report to serve its purpose, you must include the 4474information that enables us to fix the bug. 4475 4476@menu 4477* Bug Criteria:: Have you found a bug? 4478* Bug Reporting:: How to report bugs 4479@end menu 4480 4481@node Bug Criteria 4482@section Have you found a bug? 4483@cindex bug criteria 4484 4485If you are not sure whether you have found a bug, here are some guidelines: 4486 4487@itemize @bullet 4488@cindex fatal signal 4489@cindex assembler crash 4490@cindex crash of assembler 4491@item 4492If the assembler gets a fatal signal, for any input whatever, that is a 4493@code{@value{AS}} bug. Reliable assemblers never crash. 4494 4495@cindex error on valid input 4496@item 4497If @code{@value{AS}} produces an error message for valid input, that is a bug. 4498 4499@cindex invalid input 4500@item 4501If @code{@value{AS}} does not produce an error message for invalid input, that 4502is a bug. However, you should note that your idea of ``invalid input'' might 4503be our idea of ``an extension'' or ``support for traditional practice''. 4504 4505@item 4506If you are an experienced user of assemblers, your suggestions for improvement 4507of @code{@value{AS}} are welcome in any case. 4508@end itemize 4509 4510@node Bug Reporting 4511@section How to report bugs 4512@cindex bug reports 4513@cindex @code{@value{AS}} bugs, reporting 4514 4515A number of companies and individuals offer support for @sc{gnu} products. If 4516you obtained @code{@value{AS}} from a support organization, we recommend you 4517contact that organization first. 4518 4519You can find contact information for many support companies and 4520individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs 4521distribution. 4522 4523In any event, we also recommend that you send bug reports for @code{@value{AS}} 4524to @samp{bug-gnu-utils@@prep.ai.mit.edu}. 4525 4526The fundamental principle of reporting bugs usefully is this: 4527@strong{report all the facts}. If you are not sure whether to state a 4528fact or leave it out, state it! 4529 4530Often people omit facts because they think they know what causes the problem 4531and assume that some details do not matter. Thus, you might assume that the 4532name of a symbol you use in an example does not matter. Well, probably it does 4533not, but one cannot be sure. Perhaps the bug is a stray memory reference which 4534happens to fetch from the location where that name is stored in memory; 4535perhaps, if the name were different, the contents of that location would fool 4536the assembler into doing the right thing despite the bug. Play it safe and 4537give a specific, complete example. That is the easiest thing for you to do, 4538and the most helpful. 4539 4540Keep in mind that the purpose of a bug report is to enable us to fix the bug if 4541it is new to us. Therefore, always write your bug reports on the assumption 4542that the bug has not been reported previously. 4543 4544Sometimes people give a few sketchy facts and ask, ``Does this ring a 4545bell?'' Those bug reports are useless, and we urge everyone to 4546@emph{refuse to respond to them} except to chide the sender to report 4547bugs properly. 4548 4549To enable us to fix the bug, you should include all these things: 4550 4551@itemize @bullet 4552@item 4553The version of @code{@value{AS}}. @code{@value{AS}} announces it if you start 4554it with the @samp{--version} argument. 4555 4556Without this, we will not know whether there is any point in looking for 4557the bug in the current version of @code{@value{AS}}. 4558 4559@item 4560Any patches you may have applied to the @code{@value{AS}} source. 4561 4562@item 4563The type of machine you are using, and the operating system name and 4564version number. 4565 4566@item 4567What compiler (and its version) was used to compile @code{@value{AS}}---e.g. 4568``@code{gcc-2.7}''. 4569 4570@item 4571The command arguments you gave the assembler to assemble your example and 4572observe the bug. To guarantee you will not omit something important, list them 4573all. A copy of the Makefile (or the output from make) is sufficient. 4574 4575If we were to try to guess the arguments, we would probably guess wrong 4576and then we might not encounter the bug. 4577 4578@item 4579A complete input file that will reproduce the bug. If the bug is observed when 4580the assembler is invoked via a compiler, send the assembler source, not the 4581high level language source. Most compilers will produce the assembler source 4582when run with the @samp{-S} option. If you are using @code{@value{GCC}}, use 4583the options @samp{-v --save-temps}; this will save the assembler source in a 4584file with an extension of @file{.s}, and also show you exactly how 4585@code{@value{AS}} is being run. 4586 4587@item 4588A description of what behavior you observe that you believe is 4589incorrect. For example, ``It gets a fatal signal.'' 4590 4591Of course, if the bug is that @code{@value{AS}} gets a fatal signal, then we 4592will certainly notice it. But if the bug is incorrect output, we might not 4593notice unless it is glaringly wrong. You might as well not give us a chance to 4594make a mistake. 4595 4596Even if the problem you experience is a fatal signal, you should still say so 4597explicitly. Suppose something strange is going on, such as, your copy of 4598@code{@value{AS}} is out of synch, or you have encountered a bug in the C 4599library on your system. (This has happened!) Your copy might crash and ours 4600would not. If you told us to expect a crash, then when ours fails to crash, we 4601would know that the bug was not happening for us. If you had not told us to 4602expect a crash, then we would not be able to draw any conclusion from our 4603observations. 4604 4605@item 4606If you wish to suggest changes to the @code{@value{AS}} source, send us context 4607diffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or @samp{-p} 4608option. Always send diffs from the old file to the new file. If you even 4609discuss something in the @code{@value{AS}} source, refer to it by context, not 4610by line number. 4611 4612The line numbers in our development sources will not match those in your 4613sources. Your line numbers would convey no useful information to us. 4614@end itemize 4615 4616Here are some things that are not necessary: 4617 4618@itemize @bullet 4619@item 4620A description of the envelope of the bug. 4621 4622Often people who encounter a bug spend a lot of time investigating 4623which changes to the input file will make the bug go away and which 4624changes will not affect it. 4625 4626This is often time consuming and not very useful, because the way we 4627will find the bug is by running a single example under the debugger 4628with breakpoints, not by pure deduction from a series of examples. 4629We recommend that you save your time for something else. 4630 4631Of course, if you can find a simpler example to report @emph{instead} 4632of the original one, that is a convenience for us. Errors in the 4633output will be easier to spot, running under the debugger will take 4634less time, and so on. 4635 4636However, simplification is not vital; if you do not want to do this, 4637report the bug anyway and send us the entire test case you used. 4638 4639@item 4640A patch for the bug. 4641 4642A patch for the bug does help us if it is a good one. But do not omit 4643the necessary information, such as the test case, on the assumption that 4644a patch is all we need. We might see problems with your patch and decide 4645to fix the problem another way, or we might not understand it at all. 4646 4647Sometimes with a program as complicated as @code{@value{AS}} it is very hard to 4648construct an example that will make the program follow a certain path through 4649the code. If you do not send us the example, we will not be able to construct 4650one, so we will not be able to verify that the bug is fixed. 4651 4652And if we cannot understand what bug you are trying to fix, or why your 4653patch should be an improvement, we will not install it. A test case will 4654help us to understand. 4655 4656@item 4657A guess about what the bug is or what it depends on. 4658 4659Such guesses are usually wrong. Even we cannot guess right about such 4660things without first using the debugger to find the facts. 4661@end itemize 4662 4663@node Acknowledgements 4664@chapter Acknowledgements 4665 4666If you have contributed to @code{@value{AS}} and your name isn't listed here, 4667it is not meant as a slight. We just don't know about it. Send mail to the 4668maintainer, and we'll correct the situation. Currently 4669@c (January 1994), 4670the maintainer is Ken Raeburn (email address @code{raeburn@@cygnus.com}). 4671 4672Dean Elsner wrote the original @sc{gnu} assembler for the VAX.@footnote{Any 4673more details?} 4674 4675Jay Fenlason maintained GAS for a while, adding support for GDB-specific debug 4676information and the 68k series machines, most of the preprocessing pass, and 4677extensive changes in @file{messages.c}, @file{input-file.c}, @file{write.c}. 4678 4679K. Richard Pixley maintained GAS for a while, adding various enhancements and 4680many bug fixes, including merging support for several processors, breaking GAS 4681up to handle multiple object file format back ends (including heavy rewrite, 4682testing, an integration of the coff and b.out back ends), adding configuration 4683including heavy testing and verification of cross assemblers and file splits 4684and renaming, converted GAS to strictly ANSI C including full prototypes, added 4685support for m680[34]0 and cpu32, did considerable work on i960 including a COFF 4686port (including considerable amounts of reverse engineering), a SPARC opcode 4687file rewrite, DECstation, rs6000, and hp300hpux host ports, updated ``know'' 4688assertions and made them work, much other reorganization, cleanup, and lint. 4689 4690Ken Raeburn wrote the high-level BFD interface code to replace most of the code 4691in format-specific I/O modules. 4692 4693The original VMS support was contributed by David L. Kashtan. Eric Youngdale 4694has done much work with it since. 4695 4696The Intel 80386 machine description was written by Eliot Dresselhaus. 4697 4698Minh Tran-Le at IntelliCorp contributed some AIX 386 support. 4699 4700The Motorola 88k machine description was contributed by Devon Bowen of Buffalo 4701University and Torbjorn Granlund of the Swedish Institute of Computer Science. 4702 4703Keith Knowles at the Open Software Foundation wrote the original MIPS back end 4704(@file{tc-mips.c}, @file{tc-mips.h}), and contributed Rose format support 4705(which hasn't been merged in yet). Ralph Campbell worked with the MIPS code to 4706support a.out format. 4707 4708Support for the Zilog Z8k and Hitachi H8/300 and H8/500 processors (tc-z8k, 4709tc-h8300, tc-h8500), and IEEE 695 object file format (obj-ieee), was written by 4710Steve Chamberlain of Cygnus Support. Steve also modified the COFF back end to 4711use BFD for some low-level operations, for use with the H8/300 and AMD 29k 4712targets. 4713 4714John Gilmore built the AMD 29000 support, added @code{.include} support, and 4715simplified the configuration of which versions accept which directives. He 4716updated the 68k machine description so that Motorola's opcodes always produced 4717fixed-size instructions (e.g. @code{jsr}), while synthetic instructions 4718remained shrinkable (@code{jbsr}). John fixed many bugs, including true tested 4719cross-compilation support, and one bug in relaxation that took a week and 4720required the proverbial one-bit fix. 4721 4722Ian Lance Taylor of Cygnus Support merged the Motorola and MIT syntax for the 472368k, completed support for some COFF targets (68k, i386 SVR3, and SCO Unix), 4724added support for MIPS ECOFF and ELF targets, wrote the initial RS/6000 and 4725PowerPC assembler, and made a few other minor patches. 4726 4727Steve Chamberlain made @code{@value{AS}} able to generate listings. 4728 4729Hewlett-Packard contributed support for the HP9000/300. 4730 4731Jeff Law wrote GAS and BFD support for the native HPPA object format (SOM) 4732along with a fairly extensive HPPA testsuite (for both SOM and ELF object 4733formats). This work was supported by both the Center for Software Science at 4734the University of Utah and Cygnus Support. 4735 4736Support for ELF format files has been worked on by Mark Eichin of Cygnus 4737Support (original, incomplete implementation for SPARC), Pete Hoogenboom and 4738Jeff Law at the University of Utah (HPPA mainly), Michael Meissner of the Open 4739Software Foundation (i386 mainly), and Ken Raeburn of Cygnus Support (sparc, 4740and some initial 64-bit support). 4741 4742Richard Henderson rewrote the Alpha assembler. 4743 4744Several engineers at Cygnus Support have also provided many small bug fixes and 4745configuration enhancements. 4746 4747Many others have contributed large or small bugfixes and enhancements. If 4748you have contributed significant work and are not mentioned on this list, and 4749want to be, let us know. Some of the history has been lost; we are not 4750intentionally leaving anyone out. 4751 4752@node Index 4753@unnumbered Index 4754 4755@printindex cp 4756 4757@contents 4758@bye 4759@c Local Variables: 4760@c fill-column: 79 4761@c End: 4762