.TH NASM 1 "The Netwide Assembler Project".SH NAMEnasm \- the Netwide Assembler \- portable 80x86 assembler.SH SYNOPSIS.B nasm[.B \-fformat] [.B \-ooutfile] [.IR options ...] infile.br.B nasm \-h.br.B nasm \-r.SH DESCRIPTIONThe.B nasmcommand assembles the file.I infileand directs output to the file.I outfileif specified. If.I outfileis not specified,.B 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'..SS OPTIONS.TP.B \-hCauses.B nasmto exit immediately, after giving a summary of its invocationoptions, and listing all its supported output file formats..TP.B \-aCauses.B nasmto assemble the given input file without first applying the macropreprocessor..TP.B \-eCauses.B nasmto preprocess the given input file, and write the output to.I stdout(or the specified output file name), and not actually assembleanything..TP.B \-MCauses.B nasmto output Makefile-style dependencies to stdout; normal output issuppressed..TP.BI \-E " filename"Causes.B nasmto redirect error messages to.IR filename .This option exists to support operating systems on which stderr is noteasily redirected..TP.BI \-rCauses.B nasmto exit immediately, after displaying its version number..I (obsolete).TP.BI \-vCauses.B nasmto exit immediately, after displaying its version number..TP.BI \-f " format"Specifies the output file format. Formats include.IR bin ,to produce flat-form binary files, and.I aoutand.I elfto produce Linux a.out and ELF object files, respectively..TP.BI \-o " outfile"Specifies a precise name for the output file, overriding.BR nasm 'sdefault means of determining it..TP.BI \-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..TP.B \-sCauses.B nasmto send its error messages and/or help text to.I stdoutinstead of.IR stderr ..TP.BI \-w [+-]fooCauses.B nasmto enable or disable certain classes of warning messages, forexample.B \-w+orphan-labelsor.B \-w-macro-paramsto, respectively, enable warnings about labels alone on lines ordisable warnings about incorrect numbers of parameters in macrocalls..TP.BI \-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..TP.BI \-i " directory"Same as the.B \-Ioption..TP.BI \-P " file"Specifies a file to be pre-included, before the main source filestarts to be processed..TP.BI \-p " file"Same as the.B \-Poption..TP.BI \-D " macro[=value]"Pre-defines a single-line macro..TP.BI \-d " macro[=value]"Same as the.B \-Doption..TP.BI \-U " macro"Undefines a single-line macro..TP.BI \-u " macro"Same as the.B \-Uoption..PP.RE.SS SYNTAXThis man page does not fully describe the syntax of.BR nasm 'sassembly language, but does give a summary of the differences fromother assemblers..PP.I Registershave no leading `%' sign, unlike.BR gas ,and floating-point stack registers are referred to as.IR st0 ,.IR st1 ,and so on..PP.I Floating-point instructionsmay use either the single-operand form or the double. A.I TOkeyword is provided; thus, one could either write.PP.ti +15nfadd st0,st1.br.ti +15nfadd st1,st0.PPor one could use the alternative single-operand forms.PP.ti +15nfadd st1.br.ti +15nfadd to st1.PP.I Uninitialised storageis reserved using the.IR RESB ,.IR RESW ,.IR RESD ,.I RESQand.I RESTpseudo-opcodes, each taking one parameter which gives the number ofbytes, words, doublewords, quadwords or ten-byte words to reserve..PP.I Repetitionof data items is not done by the.I DUPkeyword as seen in DOS assemblers, but by the use of the.I TIMESprefix, like this:.PP.ti +6n.ta 9nmessage:	times 3 db 'abc'.br.ti +15ntimes 64-$+message db 0.PPwhich defines the string `abcabcabc', followed by the right numberof zero bytes to make the total length up to 64 bytes..PP.I 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:.PP.ti +15nmov ax,wordvar.PPloads AX with the address of the variable `wordvar', whereas.PP.ti +15nmov ax,[wordvar].br.ti +15nmov ax,[wordvar+1].br.ti +15nmov ax,[es:wordvar+bx].PPall refer to the.I contentsof memory locations. The syntaxes.PP.ti +15nmov ax,es:wordvar[bx].br.ti +15nes mov ax,wordvar[1].PPare not legal at all, although the use of a segment register name asan instruction prefix is valid, and can be used with instructionssuch as.I LODSBwhich can't be overridden any other way..PP.I 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.I 'abcd'denotes 0x64636261 and not 0x61626364..PP.I 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'..SS DIRECTIVES.I SECTION nameor.I SEGMENT namecauses.B nasmto direct all following code to the named section. Section namesvary with output file format, although most formats support thenames.IR .text ,.I .dataand.IR .bss .(The exception is the.I objformat, in which all segments are user-definable.).PP.I ABSOLUTE addresscauses.B nasmto position its notional assembly point at an absolute address: sono code or data may be generated, but you can use.IR RESB ,.I RESWand.I RESDto 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 another.I SECTIONdirective to return to normal assembly..PP.I BITS 16or.I BITS 32switches the default processor mode for which.B nasmis generating code: it is equivalent to.I USE16or.I USE32in DOS assemblers..PP.I EXTERN symboland.I GLOBAL symbolimport and export symbol definitions, respectively, from and toother modules. Note that the.I GLOBALdirective must appear before the definition of the symbol it refersto..PP.I STRUC strucnameand.IR ENDSTRUC ,when used to bracket a number of.IR RESB ,.I 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.I _sizetacked on to the end..SS FORMAT-SPECIFIC DIRECTIVES.I ORG addressis used by the.I binflat-form binary output format, and specifies the address at whichthe output code will eventually be loaded..PP.I GROUP grpname seg1 seg2...is used by the.I obj(Microsoft 16-bit) output format, and defines segment groups. Thisformat also uses.IR UPPERCASE ,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..PP.I LIBRARY libnameis used by the.I rdfoutput format, and causes a dependency record to be written to theoutput file which indicates that the program requires a certainlibrary in order to run..SS MACRO PREPROCESSORSingle-line macros are defined using the.I %defineor.I %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..I %definedefines macros whose names match case-sensitively, whereas.I %idefinedefines case-insensitive macros..PPMulti-line macros are defined using.I %macroand.I %imacro(the distinction is the same as that between.I %defineand.IR %idefine ),whose syntax is as follows:.PP.ti +6n%macro.I name.IR minprm [- maxprm "][+][.nolist] [" defaults ].br.ti +15n<some lines of macro expansion text>.br.ti +6n%endmacro.PPAgain, 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. The.I defaultspart can be used to specify defaults for unspecified macroparameters after.IR minparam ..I %endmis a valid synonym for.IR %endmacro ..PPTo refer to the macro parameters within a macro expansion, you use.IR %1 ,.I %2and so on. You can also enforce that a macro parameter shouldcontain a condition code by using.IR %+1 ,and you can invert the condition code by using.IR %-1 .You can also define a label specific to a macro invocation byprefixing it with a double % sign..PPFiles can be included using the.I %includedirective, which works like C..PPThe 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.IR %push ,remove one using.IR %pop ,and change the name of the top context (without disturbing anyassociated definitions) using.IR %repl .Labels and.I %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..PPConditional assembly is done by means of.IR %ifdef ,.IR %ifndef ,.I %elseand.I %endifas in C. (Except that.I %ifdefcan accept several putative macro names, and will evaluate TRUE ifany of them is defined.) In addition, the directives.I %ifctxand.I %ifnctxcan be used to condition on the name of the top context on thecontext stack. The obvious set of `else-if' directives,.IR %elifdef ,.IR %elifndef ,.IR %elifctxand.IR %elifnctxare also supported..SH BUGSThere is a reported seg-fault on some (Linux) systems with somelarge source files. This appears to be very hard to reproduce. Allother.I knownbugs have been fixed....SH RESTRICTIONSThere 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..SH SEE ALSO.BR as "(" 1 "),".BR ld "(" 1 ")."