nasm.1

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