MAN page from Trustix nasm-0.98.34-5tr.i586.rpm
Section: User Commands (1)
Updated: The Netwide Assembler ProjectIndex
nasm - the Netwide Assembler - portable 80x86 assembler
...] infilenasm -hnasm -r
command assembles the fileinfile
and directs output to the fileoutfile
if specified. Ifoutfile
is not specified,nasm
will 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
or one could use the alternative single-operand forms
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:
loads AX with the address of the variable `wordvar', whereas
all refer to thecontentsof memory locations. The syntaxes
es mov ax,wordvar
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'.
to direct all following code to the named section. Section namesvary with output file format, although most formats support thenames.text
.(The exception is theobj
format, 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.
FORMAT-SPECIFIC DIRECTIVESORG address
is used by thebin
flat-form binary output format, and specifies the address at whichthe output code will eventually be loaded.
GROUP grpname seg1 seg2...is 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%define
commands, 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.%define
defines macros whose names match case-sensitively, whereas%idefine
defines 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:
<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. Allotherknown
bugs 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.
- FORMAT-SPECIFIC DIRECTIVES
- MACRO PREPROCESSOR
- SEE ALSO
This document was created byman2html,using the manual pages.