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