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 .I RESQ
 196 and
 197 .I REST
 198 pseudo-opcodes, each taking one parameter which gives the number of
 199 bytes, words, doublewords, quadwords or ten-byte words to reserve.
 200 .PP
 201 .I Repetition
 202 of data items is not done by the
 203 .I DUP
 204 keyword as seen in DOS assemblers, but by the use of the
 205 .I TIMES
 206 prefix, like this:
 207 .PP
 208 .ti +6n
 209 .ta 9n
 210 message:        times 3 db 'abc'
 211 .br
 212 .ti +15n
 213 times 64-$+message db 0
 214 .PP
 215 which defines the string `abcabcabc', followed by the right number
 216 of zero bytes to make the total length up to 64 bytes.
 217 .PP
 218 .I Symbol references
 219 are always understood to be immediate (i.e. the address of the
 220 symbol), unless square brackets are used, in which case the contents
 221 of the memory location are used. Thus:
 222 .PP
 223 .ti +15n
 224 mov ax,wordvar
 225 .PP
 226 loads AX with the address of the variable `wordvar', whereas
 227 .PP
 228 .ti +15n
 229 mov ax,[wordvar]
 230 .br
 231 .ti +15n
 232 mov ax,[wordvar+1]
 233 .br
 234 .ti +15n
 235 mov ax,[es:wordvar+bx]
 236 .PP
 237 all refer to the
 238 .I contents
 239 of memory locations. The syntaxes
 240 .PP
 241 .ti +15n
 242 mov ax,es:wordvar[bx]
 243 .br
 244 .ti +15n
 245 es mov ax,wordvar[1]
 246 .PP
 247 are not legal at all, although the use of a segment register name as
 248 an instruction prefix is valid, and can be used with instructions
 249 such as
 250 .I LODSB
 251 which can't be overridden any other way.
 252 .PP
 253 .I Constants
 254 may be expressed numerically in most formats: a trailing H, Q or B
 255 denotes hex, octal or binary respectively, and a leading `0x' or `$'
 256 denotes hex as well. Leading zeros are not treated specially at all.
 257 Character constants may be enclosed in single or double quotes;
 258 there is no escape character. The ordering is little-endian
 259 (reversed), so that the character constant
 260 .I 'abcd'
 261 denotes 0x64636261 and not 0x61626364.
 262 .PP
 263 .I Local labels
 264 begin with a period, and their `locality' is granted by the
 265 assembler prepending the name of the previous non-local symbol. Thus
 266 declaring a label `.loop' after a label `label' has actually defined
 267 a symbol called `label.loop'.
 268 .SS DIRECTIVES
 269 .I SECTION name
 270 or
 271 .I SEGMENT name
 272 causes
 273 .B nasm
 274 to direct all following code to the named section. Section names
 275 vary with output file format, although most formats support the
 276 names
 277 .IR .text ,
 278 .I .data
 279 and
 280 .IR .bss .
 281 (The exception is the
 282 .I obj
 283 format, in which all segments are user-definable.)
 284 .PP
 285 .I ABSOLUTE address
 286 causes
 287 .B nasm
 288 to position its notional assembly point at an absolute address: so
 289 no code or data may be generated, but you can use
 290 .IR RESB ,
 291 .I RESW
 292 and
 293 .I RESD
 294 to move the assembly point further on, and you can define labels. So
 295 this directive may be used to define data structures. When you have
 296 finished doing absolute assembly, you must issue another
 297 .I SECTION
 298 directive to return to normal assembly.
 299 .PP
 300 .I BITS 16
 301 or
 302 .I BITS 32
 303 switches the default processor mode for which
 304 .B nasm
 305 is generating code: it is equivalent to
 306 .I USE16
 307 or
 308 .I USE32
 309 in DOS assemblers.
 310 .PP
 311 .I EXTERN symbol
 312 and
 313 .I GLOBAL symbol
 314 import and export symbol definitions, respectively, from and to
 315 other modules. Note that the
 316 .I GLOBAL
 317 directive must appear before the definition of the symbol it refers
 318 to.
 319 .PP
 320 .I STRUC strucname
 321 and
 322 .IR ENDSTRUC ,
 323 when used to bracket a number of
 324 .IR RESB ,
 325 .I RESW
 326 or similar instructions, define a data structure. In addition to
 327 defining the offsets of the structure members, the construct also
 328 defines a symbol for the size of the structure, which is simply the
 329 structure name with
 330 .I _size
 331 tacked on to the end.
 332 .SS FORMAT-SPECIFIC DIRECTIVES
 333 .I ORG address
 334 is used by the
 335 .I bin
 336 flat-form binary output format, and specifies the address at which
 337 the output code will eventually be loaded.
 338 .PP
 339 .I GROUP grpname seg1 seg2...
 340 is used by the
 341 .I obj
 342 (Microsoft 16-bit) output format, and defines segment groups. This
 343 format also uses
 344 .IR UPPERCASE ,
 345 which directs that all segment, group and symbol names output to the
 346 object file should be in uppercase. Note that the actual assembly is
 347 still case sensitive.
 348 .PP
 349 .I LIBRARY libname
 350 is used by the
 351 .I rdf
 352 output format, and causes a dependency record to be written to the
 353 output file which indicates that the program requires a certain
 354 library in order to run.
 355 .SS MACRO PREPROCESSOR
 356 Single-line macros are defined using the
 357 .I %define
 358 or
 359 .I %idefine
 360 commands, in a similar fashion to the C preprocessor. They can be
 361 overloaded with respect to number of parameters, although defining a
 362 macro with no parameters prevents the definition of any macro with
 363 the same name taking parameters, and vice versa.
 364 .I %define
 365 defines macros whose names match case-sensitively, whereas
 366 .I %idefine
 367 defines case-insensitive macros.
 368 .PP
 369 Multi-line macros are defined using
 370 .I %macro
 371 and
 372 .I %imacro
 373 (the distinction is the same as that between
 374 .I %define
 375 and
 376 .IR %idefine ),
 377 whose syntax is as follows:
 378 .PP
 379 .ti +6n
 380 %macro
 381 .I name
 382 .IR minprm [- maxprm "][+][.nolist] [" defaults ]
 383 .br
 384 .ti +15n
 385 <some lines of macro expansion text>
 386 .br
 387 .ti +6n
 388 %endmacro
 389 .PP
 390 Again, these macros may be overloaded. The trailing plus sign
 391 indicates that any parameters after the last one get subsumed, with
 392 their separating commas, into the last parameter. The
 393 .I defaults
 394 part can be used to specify defaults for unspecified macro
 395 parameters after
 396 .IR minparam .
 397 .I %endm
 398 is a valid synonym for
 399 .IR %endmacro .
 400 .PP
 401 To refer to the macro parameters within a macro expansion, you use
 402 .IR %1 ,
 403 .I %2
 404 and so on. You can also enforce that a macro parameter should
 405 contain a condition code by using
 406 .IR %+1 ,
 407 and you can invert the condition code by using
 408 .IR %-1 .
 409 You can also define a label specific to a macro invocation by
 410 prefixing it with a double % sign.
 411 .PP
 412 Files can be included using the
 413 .I %include
 414 directive, which works like C.
 415 .PP
 416 The preprocessor has a `context stack', which may be used by one
 417 macro to store information that a later one will retrieve. You can
 418 push a context on the stack using
 419 .IR %push ,
 420 remove one using
 421 .IR %pop ,
 422 and change the name of the top context (without disturbing any
 423 associated definitions) using
 424 .IR %repl .
 425 Labels and
 426 .I %define
 427 macros specific to the top context may be defined by prefixing their
 428 names with %$, and things specific to the next context down with
 429 %$$, and so on.
 430 .PP
 431 Conditional assembly is done by means of
 432 .IR %ifdef ,
 433 .IR %ifndef ,
 434 .I %else
 435 and
 436 .I %endif
 437 as in C. (Except that
 438 .I %ifdef
 439 can accept several putative macro names, and will evaluate TRUE if
 440 any of them is defined.) In addition, the directives
 441 .I %ifctx
 442 and
 443 .I %ifnctx
 444 can be used to condition on the name of the top context on the
 445 context stack. The obvious set of `else-if' directives,
 446 .IR %elifdef ,
 447 .IR %elifndef ,
 448 .IR %elifctx
 449 and
 450 .IR %elifnctx
 451 are also supported.
 452 .SH BUGS
 453 There is a reported seg-fault on some (Linux) systems with some
 454 large source files. This appears to be very hard to reproduce. All
 455 other
 456 .I known
 457 bugs have been fixed...
 458 .SH RESTRICTIONS
 459 There is no support for listing files, symbol maps, or debugging
 460 object-file records. The advanced features of the ELF and Win32
 461 object file formats are not supported, and there is no means for
 462 warning the programmer against using an instruction beyond the
 463 capability of the target processor.
 464 .SH SEE ALSO
 465 .BR as "(" 1 "),"
 466 .BR ld "(" 1 ")."