nasm.1

   1 .TH NASM 1 "The Netwide Assembler Project"
   2 .SH NAME
   3 nasm \- the Netwide Assembler \- portable 80x86 assembler
   4 .SH SYNOPSIS
   5 .B nasm
   6 [
   7 .B \-f
   8 format
   9 ] [
  10 .B \-o
  11 outfile
  12 ] [
  13 .IR options ...
  14 ] infile
  15 .br
  16 .B nasm \-h
  17 .br
  18 .B nasm \-r
  19 .SH DESCRIPTION
  20 The
  21 .B nasm
  22 command assembles the file
  23 .I infile
  24 and directs output to the file
  25 .I outfile
  26 if specified. If
  27 .I outfile
  28 is not specified,
  29 .B nasm
  30 will derive a default output file name from the name of its input
  31 file, usually by appending `.o' or `.obj', or by removing all
  32 extensions for a raw binary file. Failing that, the output file name
  33 will be `nasm.out'.
  34 .SS OPTIONS
  35 .TP
  36 .B \-h
  37 Causes
  38 .B nasm
  39 to exit immediately, after giving a summary of its invocation
  40 options, and listing all its supported output file formats.
  41 .TP
  42 .B \-a
  43 Causes
  44 .B nasm
  45 to assemble the given input file without first applying the macro
  46 preprocessor.
  47 .TP
  48 .B \-e
  49 Causes
  50 .B nasm
  51 to preprocess the given input file, and write the output to
  52 .I stdout
  53 (or the specified output file name), and not actually assemble
  54 anything.
  55 .TP
  56 .BI \-r
  57 Causes
  58 .B nasm
  59 to exit immediately, after displaying its version number.
  60 .TP
  61 .BI \-f " format"
  62 Specifies the output file format. Formats include
  63 .IR bin ,
  64 to produce flat-form binary files, and
  65 .I aout
  66 and
  67 .I elf
  68 to produce Linux a.out and ELF object files, respectively.
  69 .TP
  70 .BI \-o " outfile"
  71 Specifies a precise name for the output file, overriding
  72 .BR nasm 's
  73 default means of determining it.
  74 .TP
  75 .BI \-l " listfile"
  76 Causes an assembly listing to be directed to the given file, in
  77 which the original source is displayed on the right hand side (plus
  78 the source for included files and the expansions of multi-line
  79 macros) and the generated code is shown in hex on the left.
  80 .TP
  81 .B \-s
  82 Causes
  83 .B nasm
  84 to send its error messages and/or help text to
  85 .I stdout
  86 instead of
  87 .IR stderr .
  88 .TP
  89 .BI \-w [+-]foo
  90 Causes
  91 .B nasm
  92 to enable or disable certain classes of warning messages, for
  93 example
  94 .B \-w+orphan-labels
  95 or
  96 .B \-w-macro-params
  97 to, respectively, enable warnings about labels alone on lines or
  98 disable warnings about incorrect numbers of parameters in macro
  99 calls.
 100 .TP
 101 .BI \-i " directory"
 102 Adds a directory to the search path for include files. The directory
 103 specification must include the trailing slash, as it will be
 104 directly prepended to the name of the include file.
 105 .TP
 106 .BI \-p " file"
 107 Specifies a file to be pre-included, before the main source file
 108 starts to be processed.
 109 .TP
 110 .BI \-d " macro[=value]"
 111 Pre-defines a single-line macro.
 112 .PP
 113 .RE
 114 .SS SYNTAX
 115 This man page does not fully describe the syntax of
 116 .BR nasm 's
 117 assembly language, but does give a summary of the differences from
 118 other assemblers.
 119 .PP
 120 .I Registers
 121 have no leading `%' sign, unlike
 122 .BR gas ,
 123 and floating-point stack registers are referred to as
 124 .IR st0 ,
 125 .IR st1 ,
 126 and so on.
 127 .PP
 128 .I Floating-point instructions
 129 may use either the single-operand form or the double. A
 130 .I TO
 131 keyword is provided; thus, one could either write
 132 .PP
 133 .ti +15n
 134 fadd st0,st1
 135 .br
 136 .ti +15n
 137 fadd st1,st0
 138 .PP
 139 or one could use the alternative single-operand forms
 140 .PP
 141 .ti +15n
 142 fadd st1
 143 .br
 144 .ti +15n
 145 fadd to st1
 146 .PP
 147 .I Uninitialised storage
 148 is reserved using the
 149 .IR RESB ,
 150 .IR RESW ,
 151 .IR RESD ,
 152 .I RESQ
 153 and
 154 .I REST
 155 pseudo-opcodes, each taking one parameter which gives the number of
 156 bytes, words, doublewords, quadwords or ten-byte words to reserve.
 157 .PP
 158 .I Repetition
 159 of data items is not done by the
 160 .I DUP
 161 keyword as seen in DOS assemblers, but by the use of the
 162 .I TIMES
 163 prefix, like this:
 164 .PP
 165 .ti +6n
 166 .ta 9n
 167 message:        times 3 db 'abc'
 168 .br
 169 .ti +15n
 170 times 64-$+message db 0
 171 .PP
 172 which defines the string `abcabcabc', followed by the right number
 173 of zero bytes to make the total length up to 64 bytes.
 174 .PP
 175 .I Symbol references
 176 are always understood to be immediate (i.e. the address of the
 177 symbol), unless square brackets are used, in which case the contents
 178 of the memory location are used. Thus:
 179 .PP
 180 .ti +15n
 181 mov ax,wordvar
 182 .PP
 183 loads AX with the address of the variable `wordvar', whereas
 184 .PP
 185 .ti +15n
 186 mov ax,[wordvar]
 187 .br
 188 .ti +15n
 189 mov ax,[wordvar+1]
 190 .br
 191 .ti +15n
 192 mov ax,[es:wordvar+bx]
 193 .PP
 194 all refer to the
 195 .I contents
 196 of memory locations. The syntaxes
 197 .PP
 198 .ti +15n
 199 mov ax,es:wordvar[bx]
 200 .br
 201 .ti +15n
 202 es mov ax,wordvar[1]
 203 .PP
 204 are not legal at all, although the use of a segment register name as
 205 an instruction prefix is valid, and can be used with instructions
 206 such as
 207 .I LODSB
 208 which can't be overridden any other way.
 209 .PP
 210 .I Constants
 211 may be expressed numerically in most formats: a trailing H, Q or B
 212 denotes hex, octal or binary respectively, and a leading `0x' or `$'
 213 denotes hex as well. Leading zeros are not treated specially at all.
 214 Character constants may be enclosed in single or double quotes;
 215 there is no escape character. The ordering is little-endian
 216 (reversed), so that the character constant
 217 .I 'abcd'
 218 denotes 0x64636261 and not 0x61626364.
 219 .PP
 220 .I Local labels
 221 begin with a period, and their `locality' is granted by the
 222 assembler prepending the name of the previous non-local symbol. Thus
 223 declaring a label `.loop' after a label `label' has actually defined
 224 a symbol called `label.loop'.
 225 .SS DIRECTIVES
 226 .I SECTION name
 227 or
 228 .I SEGMENT name
 229 causes
 230 .B nasm
 231 to direct all following code to the named section. Section names
 232 vary with output file format, although most formats support the
 233 names
 234 .IR .text ,
 235 .I .data
 236 and
 237 .IR .bss .
 238 (The exception is the
 239 .I obj
 240 format, in which all segments are user-definable.)
 241 .PP
 242 .I ABSOLUTE address
 243 causes
 244 .B nasm
 245 to position its notional assembly point at an absolute address: so
 246 no code or data may be generated, but you can use
 247 .IR RESB ,
 248 .I RESW
 249 and
 250 .I RESD
 251 to move the assembly point further on, and you can define labels. So
 252 this directive may be used to define data structures. When you have
 253 finished doing absolute assembly, you must issue another
 254 .I SECTION
 255 directive to return to normal assembly.
 256 .PP
 257 .I BITS 16
 258 or
 259 .I BITS 32
 260 switches the default processor mode for which
 261 .B nasm
 262 is generating code: it is equivalent to
 263 .I USE16
 264 or
 265 .I USE32
 266 in DOS assemblers.
 267 .PP
 268 .I EXTERN symbol
 269 and
 270 .I GLOBAL symbol
 271 import and export symbol definitions, respectively, from and to
 272 other modules. Note that the
 273 .I GLOBAL
 274 directive must appear before the definition of the symbol it refers
 275 to.
 276 .PP
 277 .I STRUC strucname
 278 and
 279 .IR ENDSTRUC ,
 280 when used to bracket a number of
 281 .IR RESB ,
 282 .I RESW
 283 or similar instructions, define a data structure. In addition to
 284 defining the offsets of the structure members, the construct also
 285 defines a symbol for the size of the structure, which is simply the
 286 structure name with
 287 .I _size
 288 tacked on to the end.
 289 .SS FORMAT-SPECIFIC DIRECTIVES
 290 .I ORG address
 291 is used by the
 292 .I bin
 293 flat-form binary output format, and specifies the address at which
 294 the output code will eventually be loaded.
 295 .PP
 296 .I GROUP grpname seg1 seg2...
 297 is used by the
 298 .I obj
 299 (Microsoft 16-bit) output format, and defines segment groups. This
 300 format also uses
 301 .IR UPPERCASE ,
 302 which directs that all segment, group and symbol names output to the
 303 object file should be in uppercase. Note that the actual assembly is
 304 still case sensitive.
 305 .PP
 306 .I LIBRARY libname
 307 is used by the
 308 .I rdf
 309 output format, and causes a dependency record to be written to the
 310 output file which indicates that the program requires a certain
 311 library in order to run.
 312 .SS MACRO PREPROCESSOR
 313 Single-line macros are defined using the
 314 .I %define
 315 or
 316 .I %idefine
 317 commands, in a similar fashion to the C preprocessor. They can be
 318 overloaded with respect to number of parameters, although defining a
 319 macro with no parameters prevents the definition of any macro with
 320 the same name taking parameters, and vice versa.
 321 .I %define
 322 defines macros whose names match case-sensitively, whereas
 323 .I %idefine
 324 defines case-insensitive macros.
 325 .PP
 326 Multi-line macros are defined using
 327 .I %macro
 328 and
 329 .I %imacro
 330 (the distinction is the same as that between
 331 .I %define
 332 and
 333 .IR %idefine ),
 334 whose syntax is as follows:
 335 .PP
 336 .ti +6n
 337 %macro
 338 .I name
 339 .IR minprm [- maxprm "][+][.nolist] [" defaults ]
 340 .br
 341 .ti +15n
 342 <some lines of macro expansion text>
 343 .br
 344 .ti +6n
 345 %endmacro
 346 .PP
 347 Again, these macros may be overloaded. The trailing plus sign
 348 indicates that any parameters after the last one get subsumed, with
 349 their separating commas, into the last parameter. The
 350 .I defaults
 351 part can be used to specify defaults for unspecified macro
 352 parameters after
 353 .IR minparam .
 354 .I %endm
 355 is a valid synonym for
 356 .IR %endmacro .
 357 .PP
 358 To refer to the macro parameters within a macro expansion, you use
 359 .IR %1 ,
 360 .I %2
 361 and so on. You can also enforce that a macro parameter should
 362 contain a condition code by using
 363 .IR %+1 ,
 364 and you can invert the condition code by using
 365 .IR %-1 .
 366 You can also define a label specific to a macro invocation by
 367 prefixing it with a double % sign.
 368 .PP
 369 Files can be included using the
 370 .I %include
 371 directive, which works like C.
 372 .PP
 373 The preprocessor has a `context stack', which may be used by one
 374 macro to store information that a later one will retrieve. You can
 375 push a context on the stack using
 376 .IR %push ,
 377 remove one using
 378 .IR %pop ,
 379 and change the name of the top context (without disturbing any
 380 associated definitions) using
 381 .IR %repl .
 382 Labels and
 383 .I %define
 384 macros specific to the top context may be defined by prefixing their
 385 names with %$, and things specific to the next context down with
 386 %$$, and so on.
 387 .PP
 388 Conditional assembly is done by means of
 389 .IR %ifdef ,
 390 .IR %ifndef ,
 391 .I %else
 392 and
 393 .I %endif
 394 as in C. (Except that
 395 .I %ifdef
 396 can accept several putative macro names, and will evaluate TRUE if
 397 any of them is defined.) In addition, the directives
 398 .I %ifctx
 399 and
 400 .I %ifnctx
 401 can be used to condition on the name of the top context on the
 402 context stack. The obvious set of `else-if' directives,
 403 .IR %elifdef ,
 404 .IR %elifndef ,
 405 .IR %elifctx
 406 and
 407 .IR %elifnctx
 408 are also supported.
 409 .SH BUGS
 410 There is a reported seg-fault on some (Linux) systems with some
 411 large source files. This appears to be very hard to reproduce. All
 412 other
 413 .I known
 414 bugs have been fixed...
 415 .SH RESTRICTIONS
 416 There is no support for listing files, symbol maps, or debugging
 417 object-file records. The advanced features of the ELF and Win32
 418 object file formats are not supported, and there is no means for
 419 warning the programmer against using an instruction beyond the
 420 capability of the target processor.
 421 .SH SEE ALSO
 422 .BR as "(" 1 "),"
 423 .BR ld "(" 1 ")."