MAN page from Trustix nasm-0.98.34-5tr.i586.rpm


Section: User Commands (1)
Updated: The Netwide Assembler Project


nasm - the Netwide Assembler - portable 80x86 assembler 


nasm[-fformat] [-ooutfile] [options...] infile
nasm -h
nasm -r 


Thenasmcommand assembles the fileinfileand directs output to the fileoutfileif specified. Ifoutfileis not specified,nasmwill derive a default output file name from the name of its inputfile, usually by appending `.o' or `.obj', or by removing allextensions for a raw binary file. Failing that, the output file namewill be `nasm.out'. 


Causesnasmto exit immediately, after giving a summary of its invocationoptions, and listing all its supported output file formats.
Causesnasmto assemble the given input file without first applying the macropreprocessor.
Causesnasmto preprocess the given input file, and write the output tostdout(or the specified output file name), and not actually assembleanything.
Causesnasmto output Makefile-style dependencies to stdout; normal output issuppressed.
-E filename
Causesnasmto redirect error messages tofilename.This option exists to support operating systems on which stderr is noteasily redirected.
Causesnasmto exit immediately, after displaying its version number.(obsolete)
Causesnasmto exit immediately, after displaying its version number.
-f format
Specifies the output file format. Formats includebin,to produce flat-form binary files, andaoutandelfto produce Linux a.out and ELF object files, respectively.
-o outfile
Specifies a precise name for the output file, overridingnasm'sdefault means of determining it.
-l listfile
Causes an assembly listing to be directed to the given file, inwhich the original source is displayed on the right hand side (plusthe source for included files and the expansions of multi-linemacros) and the generated code is shown in hex on the left.
Causesnasmto send its error messages and/or help text tostdoutinstead ofstderr.
Causesnasmto enable or disable certain classes of warning messages, forexample-w+orphan-labelsor-w-macro-paramsto, respectively, enable warnings about labels alone on lines ordisable warnings about incorrect numbers of parameters in macrocalls.
-I directory
Adds a directory to the search path for include files. The directoryspecification must include the trailing slash, as it will bedirectly prepended to the name of the include file.
-i directory
Same as the-Ioption.
-P file
Specifies a file to be pre-included, before the main source filestarts to be processed.
-p file
Same as the-Poption.
-D macro[=value]
Pre-defines a single-line macro.
-d macro[=value]
Same as the-Doption.
-U macro
Undefines a single-line macro.
-u macro
Same as the-Uoption.



This man page does not fully describe the syntax ofnasm'sassembly language, but does give a summary of the differences fromother assemblers.

Registershave no leading `%' sign, unlikegas,and floating-point stack registers are referred to asst0,st1,and so on.

Floating-point instructionsmay use either the single-operand form or the double. ATOkeyword is provided; thus, one could either write

               fadd st0,st1

               fadd st1,st0

or one could use the alternative single-operand forms

               fadd st1

               fadd to st1

Uninitialised storageis reserved using theRESB,RESW,RESD,RESQandRESTpseudo-opcodes, each taking one parameter which gives the number ofbytes, words, doublewords, quadwords or ten-byte words to reserve.

Repetitionof data items is not done by theDUPkeyword as seen in DOS assemblers, but by the use of theTIMESprefix, like this:

      message: times 3 db 'abc'

               times 64-$+message db 0

which defines the string `abcabcabc', followed by the right numberof zero bytes to make the total length up to 64 bytes.

Symbol referencesare always understood to be immediate (i.e. the address of thesymbol), unless square brackets are used, in which case the contentsof the memory location are used. Thus:

               mov ax,wordvar

loads AX with the address of the variable `wordvar', whereas

               mov ax,[wordvar]

               mov ax,[wordvar+1]

               mov ax,[es:wordvar+bx]

all refer to thecontentsof memory locations. The syntaxes

               mov ax,es:wordvar[bx]

               es mov ax,wordvar[1]

are not legal at all, although the use of a segment register name asan instruction prefix is valid, and can be used with instructionssuch asLODSBwhich can't be overridden any other way.

Constantsmay be expressed numerically in most formats: a trailing H, Q or Bdenotes hex, octal or binary respectively, and a leading `0x' or `$'denotes hex as well. Leading zeros are not treated specially at all.Character constants may be enclosed in single or double quotes;there is no escape character. The ordering is little-endian(reversed), so that the character constant'abcd'denotes 0x64636261 and not 0x61626364.

Local labelsbegin with a period, and their `locality' is granted by theassembler prepending the name of the previous non-local symbol. Thusdeclaring a label `.loop' after a label `label' has actually defineda symbol called `label.loop'. 


SECTION nameorSEGMENT namecausesnasmto direct all following code to the named section. Section namesvary with output file format, although most formats support thenames.text,.dataand.bss.(The exception is theobjformat, in which all segments are user-definable.)

ABSOLUTE addresscausesnasmto position its notional assembly point at an absolute address: sono code or data may be generated, but you can useRESB,RESWandRESDto move the assembly point further on, and you can define labels. Sothis directive may be used to define data structures. When you havefinished doing absolute assembly, you must issue anotherSECTIONdirective to return to normal assembly.

BITS 16orBITS 32switches the default processor mode for whichnasmis generating code: it is equivalent toUSE16orUSE32in DOS assemblers.

EXTERN symbolandGLOBAL symbolimport and export symbol definitions, respectively, from and toother modules. Note that theGLOBALdirective must appear before the definition of the symbol it refersto.

STRUC strucnameandENDSTRUC,when used to bracket a number ofRESB,RESWor similar instructions, define a data structure. In addition todefining the offsets of the structure members, the construct alsodefines a symbol for the size of the structure, which is simply thestructure name with_sizetacked on to the end. 


ORG addressis used by thebinflat-form binary output format, and specifies the address at whichthe output code will eventually be loaded.

GROUP grpname seg1 used by theobj(Microsoft 16-bit) output format, and defines segment groups. Thisformat also usesUPPERCASE,which directs that all segment, group and symbol names output to theobject file should be in uppercase. Note that the actual assembly isstill case sensitive.

LIBRARY libnameis used by therdfoutput format, and causes a dependency record to be written to theoutput file which indicates that the program requires a certainlibrary in order to run. 


Single-line macros are defined using the%defineor%idefinecommands, in a similar fashion to the C preprocessor. They can beoverloaded with respect to number of parameters, although defining amacro with no parameters prevents the definition of any macro withthe same name taking parameters, and vice versa.%definedefines macros whose names match case-sensitively, whereas%idefinedefines case-insensitive macros.

Multi-line macros are defined using%macroand%imacro(the distinction is the same as that between%defineand%idefine),whose syntax is as follows:

      %macronameminprm[-maxprm][+][.nolist] [defaults]

               <some lines of macro expansion text>


Again, these macros may be overloaded. The trailing plus signindicates that any parameters after the last one get subsumed, withtheir separating commas, into the last parameter. Thedefaultspart can be used to specify defaults for unspecified macroparameters afterminparam.%endmis a valid synonym for%endmacro.

To refer to the macro parameters within a macro expansion, you use%1,%2and so on. You can also enforce that a macro parameter shouldcontain a condition code by using%+1,and you can invert the condition code by using%-1.You can also define a label specific to a macro invocation byprefixing it with a double % sign.

Files can be included using the%includedirective, which works like C.

The preprocessor has a `context stack', which may be used by onemacro to store information that a later one will retrieve. You canpush a context on the stack using%push,remove one using%pop,and change the name of the top context (without disturbing anyassociated definitions) using%repl.Labels and%definemacros specific to the top context may be defined by prefixing theirnames with %$, and things specific to the next context down with%$$, and so on.

Conditional assembly is done by means of%ifdef,%ifndef,%elseand%endifas in C. (Except that%ifdefcan accept several putative macro names, and will evaluate TRUE ifany of them is defined.) In addition, the directives%ifctxand%ifnctxcan be used to condition on the name of the top context on thecontext stack. The obvious set of `else-if' directives,%elifdef,%elifndef,%elifctxand%elifnctxare also supported. 


There is a reported seg-fault on some (Linux) systems with somelarge source files. This appears to be very hard to reproduce. Allotherknownbugs have been fixed... 


There is no support for listing files, symbol maps, or debuggingobject-file records. The advanced features of the ELF and Win32object file formats are not supported, and there is no means forwarning the programmer against using an instruction beyond thecapability of the target processor. 






This document was created byman2html,using the manual pages.