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