"Fossies" - the Fresh Open Source Software Archive

Member "nasm-2.15.05/doc/html/nasmdoc8.html" (28 Aug 2020, 72389 Bytes) of package /linux/misc/nasm-2.15.05-xdoc.tar.xz:

As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) HTML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 <?xml version="1.0" encoding="UTF-8" standalone="no" ?>
    2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
    3 <html xmlns="http://www.w3.org/1999/xhtml">
    4 <head>
    5 <title>NASM - The Netwide Assembler</title>
    6 <link href="nasmdoc.css" rel="stylesheet" type="text/css" />
    7 <link href="local.css" rel="stylesheet" type="text/css" />
    8 </head>
    9 <body>
   10 <ul class="navbar">
   11 <li class="first"><a class="prev" href="nasmdoc7.html">Chapter 7</a></li>
   12 <li><a class="next" href="nasmdoc9.html">Chapter 9</a></li>
   13 <li><a class="toc" href="nasmdoc0.html">Contents</a></li>
   14 <li class="last"><a class="index" href="nasmdoci.html">Index</a></li>
   15 </ul>
   16 <div class="title">
   17 <h1>NASM - The Netwide Assembler</h1>
   18 <span class="subtitle">version 2.15.05</span>
   19 </div>
   20 <div class="contents"
   21 >
   22 <h2 id="chapter-8">Chapter 8: Output Formats</h2>
   23 <p>NASM is a portable assembler, designed to be able to compile on any ANSI
   24 C-supporting platform and produce output to run on a variety of Intel x86
   25 operating systems. For this reason, it has a large number of available
   26 output formats, selected using the <code>-f</code> option on the NASM
   27 command line. Each of these formats, along with its extensions to the base
   28 NASM syntax, is detailed in this chapter.</p>
   29 <p>As stated in <a href="nasmdoc2.html#section-2.1.1">section 2.1.1</a>,
   30 NASM chooses a default name for your output file based on the input file
   31 name and the chosen output format. This will be generated by removing the
   32 extension (<code>.asm</code>, <code>.s</code>, or whatever you like to use)
   33 from the input file name, and substituting an extension defined by the
   34 output format. The extensions are given with each format below.</p>
   35 <h3 id="section-8.1">8.1 <code>bin</code>: Flat-Form Binary Output</h3>
   36 <p>The <code>bin</code> format does not produce object files: it generates
   37 nothing in the output file except the code you wrote. Such `pure binary'
   38 files are used by MS-DOS: <code>.COM</code> executables and
   39 <code>.SYS</code> device drivers are pure binary files. Pure binary output
   40 is also useful for operating system and boot loader development.</p>
   41 <p>The <code>bin</code> format supports multiple section names. For details
   42 of how NASM handles sections in the <code>bin</code> format, see
   43 <a href="#section-8.1.3">section 8.1.3</a>.</p>
   44 <p>Using the <code>bin</code> format puts NASM by default into 16-bit mode
   45 (see <a href="nasmdoc7.html#section-7.1">section 7.1</a>). In order to use
   46 <code>bin</code> to write 32-bit or 64-bit code, such as an OS kernel, you
   47 need to explicitly issue the <code>BITS 32</code> or <code>BITS 64</code>
   48 directive.</p>
   49 <p><code>bin</code> has no default output file name extension: instead, it
   50 leaves your file name as it is once the original extension has been
   51 removed. Thus, the default is for NASM to assemble <code>binprog.asm</code>
   52 into a binary file called <code>binprog</code>.</p>
   53 <h4 id="section-8.1.1">8.1.1 <code>ORG</code>: Binary File Program Origin</h4>
   54 <p>The <code>bin</code> format provides an additional directive to the list
   55 given in <a href="nasmdoc7.html">chapter 7</a>: <code>ORG</code>. The
   56 function of the <code>ORG</code> directive is to specify the origin address
   57 which NASM will assume the program begins at when it is loaded into memory.</p>
   58 <p>For example, the following code will generate the longword
   59 <code>0x00000104</code>:</p>
   60 <pre>
   61         org     0x100 
   62         dd      label 
   63 label:
   64 </pre>
   65 <p>Unlike the <code>ORG</code> directive provided by MASM-compatible
   66 assemblers, which allows you to jump around in the object file and
   67 overwrite code you have already generated, NASM's <code>ORG</code> does
   68 exactly what the directive says: <em>origin</em>. Its sole function is to
   69 specify one offset which is added to all internal address references within
   70 the section; it does not permit any of the trickery that MASM's version
   71 does. See <a href="nasmdo13.html#section-13.1.3">section 13.1.3</a> for
   72 further comments.</p>
   73 <h4 id="section-8.1.2">8.1.2 <code>bin</code> Extensions to the <code>SECTION</code> Directive, <code>bin</code> extensions to}</h4>
   74 <p>The <code>bin</code> output format extends the <code>SECTION</code> (or
   75 <code>SEGMENT</code>) directive to allow you to specify the alignment
   76 requirements of segments. This is done by appending the <code>ALIGN</code>
   77 qualifier to the end of the section-definition line. For example,</p>
   78 <pre>
   79 section .data   align=16
   80 </pre>
   81 <p>switches to the section <code>.data</code> and also specifies that it
   82 must be aligned on a 16-byte boundary.</p>
   83 <p>The parameter to <code>ALIGN</code> specifies how many low bits of the
   84 section start address must be forced to zero. The alignment value given may
   85 be any power of two.</p>
   86 <h4 id="section-8.1.3">8.1.3 Multisection Support for the <code>bin</code> Format</h4>
   87 <p>The <code>bin</code> format allows the use of multiple sections, of
   88 arbitrary names, besides the "known" <code>.text</code>,
   89 <code>.data</code>, and <code>.bss</code> names.</p>
   90 <ul>
   91 <li>
   92 <p>Sections may be designated <code>progbits</code> or <code>nobits</code>.
   93 Default is <code>progbits</code> (except <code>.bss</code>, which defaults
   94 to <code>nobits</code>, of course).</p>
   95 </li>
   96 <li>
   97 <p>Sections can be aligned at a specified boundary following the previous
   98 section with <code>align=</code>, or at an arbitrary byte-granular position
   99 with <code>start=</code>.</p>
  100 </li>
  101 <li>
  102 <p>Sections can be given a virtual start address, which will be used for
  103 the calculation of all memory references within that section with
  104 <code>vstart=</code>.</p>
  105 </li>
  106 <li>
  107 <p>Sections can be ordered using
  108 <code>follows=</code><code>&lt;section&gt;</code> or
  109 <code>vfollows=</code><code>&lt;section&gt;</code> as an alternative to
  110 specifying an explicit start address.</p>
  111 </li>
  112 <li>
  113 <p>Arguments to <code>org</code>, <code>start</code>, <code>vstart</code>,
  114 and <code>align=</code> are critical expressions. See
  115 <a href="nasmdoc3.html#section-3.8">section 3.8</a>. E.g.
  116 <code>align=(1 &lt;&lt; ALIGN_SHIFT)</code> &ndash;
  117 <code>ALIGN_SHIFT</code> must be defined before it is used here.</p>
  118 </li>
  119 <li>
  120 <p>Any code which comes before an explicit <code>SECTION</code> directive
  121 is directed by default into the <code>.text</code> section.</p>
  122 </li>
  123 <li>
  124 <p>If an <code>ORG</code> statement is not given, <code>ORG 0</code> is
  125 used by default.</p>
  126 </li>
  127 <li>
  128 <p>The <code>.bss</code> section will be placed after the last
  129 <code>progbits</code> section, unless <code>start=</code>,
  130 <code>vstart=</code>, <code>follows=</code>, or <code>vfollows=</code> has
  131 been specified.</p>
  132 </li>
  133 <li>
  134 <p>All sections are aligned on dword boundaries, unless a different
  135 alignment has been specified.</p>
  136 </li>
  137 <li>
  138 <p>Sections may not overlap.</p>
  139 </li>
  140 <li>
  141 <p>NASM creates the <code>section.&lt;secname&gt;.start</code> for each
  142 section, which may be used in your code.</p>
  143 </li>
  144 </ul>
  145 <h4 id="section-8.1.4">8.1.4 Map Files</h4>
  146 <p>Map files can be generated in <code>-f bin</code> format by means of the
  147 <code>[map]</code> option. Map types of <code>all</code> (default),
  148 <code>brief</code>, <code>sections</code>, <code>segments</code>, or
  149 <code>symbols</code> may be specified. Output may be directed to
  150 <code>stdout</code> (default), <code>stderr</code>, or a specified file.
  151 E.g. <code>[map symbols myfile.map]</code>. No "user form" exists, the
  152 square brackets must be used.</p>
  153 <h3 id="section-8.2">8.2 <code>ith</code>: Intel Hex Output</h3>
  154 <p>The <code>ith</code> file format produces Intel hex-format files. Just
  155 as the <code>bin</code> format, this is a flat memory image format with no
  156 support for relocation or linking. It is usually used with ROM programmers
  157 and similar utilities.</p>
  158 <p>All extensions supported by the <code>bin</code> file format is also
  159 supported by the <code>ith</code> file format.</p>
  160 <p><code>ith</code> provides a default output file-name extension of
  161 <code>.ith</code>.</p>
  162 <h3 id="section-8.3">8.3 <code>srec</code>: Motorola S-Records Output</h3>
  163 <p>The <code>srec</code> file format produces Motorola S-records files.
  164 Just as the <code>bin</code> format, this is a flat memory image format
  165 with no support for relocation or linking. It is usually used with ROM
  166 programmers and similar utilities.</p>
  167 <p>All extensions supported by the <code>bin</code> file format is also
  168 supported by the <code>srec</code> file format.</p>
  169 <p><code>srec</code> provides a default output file-name extension of
  170 <code>.srec</code>.</p>
  171 <h3 id="section-8.4">8.4 <code>obj</code>: Microsoft OMF Object Files</h3>
  172 <p>The <code>obj</code> file format (NASM calls it <code>obj</code> rather
  173 than <code>omf</code> for historical reasons) is the one produced by MASM
  174 and TASM, which is typically fed to 16-bit DOS linkers to produce
  175 <code>.EXE</code> files. It is also the format used by OS/2.</p>
  176 <p><code>obj</code> provides a default output file-name extension of
  177 <code>.obj</code>.</p>
  178 <p><code>obj</code> is not exclusively a 16-bit format, though: NASM has
  179 full support for the 32-bit extensions to the format. In particular, 32-bit
  180 <code>obj</code> format files are used by Borland's Win32 compilers,
  181 instead of using Microsoft's newer <code>win32</code> object file format.</p>
  182 <p>The <code>obj</code> format does not define any special segment names:
  183 you can call your segments anything you like. Typical names for segments in
  184 <code>obj</code> format files are <code>CODE</code>, <code>DATA</code> and
  185 <code>BSS</code>.</p>
  186 <p>If your source file contains code before specifying an explicit
  187 <code>SEGMENT</code> directive, then NASM will invent its own segment
  188 called <code>__NASMDEFSEG</code> for you.</p>
  189 <p>When you define a segment in an <code>obj</code> file, NASM defines the
  190 segment name as a symbol as well, so that you can access the segment
  191 address of the segment. So, for example:</p>
  192 <pre>
  193 segment data 
  195 dvar:   dw      1234 
  197 segment code 
  199 function: 
  200         mov     ax,data         ; get segment address of data 
  201         mov     ds,ax           ; and move it into DS 
  202         inc     word [dvar]     ; now this reference will work 
  203         ret
  204 </pre>
  205 <p>The <code>obj</code> format also enables the use of the <code>SEG</code>
  206 and <code>WRT</code> operators, so that you can write code which does
  207 things like</p>
  208 <pre>
  209 extern  foo 
  211       mov   ax,seg foo            ; get preferred segment of foo 
  212       mov   ds,ax 
  213       mov   ax,data               ; a different segment 
  214       mov   es,ax 
  215       mov   ax,[ds:foo]           ; this accesses `foo' 
  216       mov   [es:foo wrt data],bx  ; so does this
  217 </pre>
  218 <h4 id="section-8.4.1">8.4.1 <code>obj</code> Extensions to the <code>SEGMENT</code> Directive</h4>
  219 <p>The <code>obj</code> output format extends the <code>SEGMENT</code> (or
  220 <code>SECTION</code>) directive to allow you to specify various properties
  221 of the segment you are defining. This is done by appending extra qualifiers
  222 to the end of the segment-definition line. For example,</p>
  223 <pre>
  224 segment code private align=16
  225 </pre>
  226 <p>defines the segment <code>code</code>, but also declares it to be a
  227 private segment, and requires that the portion of it described in this code
  228 module must be aligned on a 16-byte boundary.</p>
  229 <p>The available qualifiers are:</p>
  230 <ul>
  231 <li>
  232 <p><code>PRIVATE</code>, <code>PUBLIC</code>, <code>COMMON</code> and
  233 <code>STACK</code> specify the combination characteristics of the segment.
  234 <code>PRIVATE</code> segments do not get combined with any others by the
  235 linker; <code>PUBLIC</code> and <code>STACK</code> segments get
  236 concatenated together at link time; and <code>COMMON</code> segments all
  237 get overlaid on top of each other rather than stuck end-to-end.</p>
  238 </li>
  239 <li>
  240 <p><code>ALIGN</code> is used, as shown above, to specify how many low bits
  241 of the segment start address must be forced to zero. The alignment value
  242 given may be any power of two from 1 to 4096; in reality, the only values
  243 supported are 1, 2, 4, 16, 256 and 4096, so if 8 is specified it will be
  244 rounded up to 16, and 32, 64 and 128 will all be rounded up to 256, and so
  245 on. Note that alignment to 4096-byte boundaries is a PharLap extension to
  246 the format and may not be supported by all linkers.</p>
  247 </li>
  248 <li>
  249 <p><code>CLASS</code> can be used to specify the segment class; this
  250 feature indicates to the linker that segments of the same class should be
  251 placed near each other in the output file. The class name can be any word,
  252 e.g. <code>CLASS=CODE</code>.</p>
  253 </li>
  254 <li>
  255 <p><code>OVERLAY</code>, like <code>CLASS</code>, is specified with an
  256 arbitrary word as an argument, and provides overlay information to an
  257 overlay-capable linker.</p>
  258 </li>
  259 <li>
  260 <p>Segments can be declared as <code>USE16</code> or <code>USE32</code>,
  261 which has the effect of recording the choice in the object file and also
  262 ensuring that NASM's default assembly mode when assembling in that segment
  263 is 16-bit or 32-bit respectively.</p>
  264 </li>
  265 <li>
  266 <p>When writing OS/2 object files, you should declare 32-bit segments as
  267 <code>FLAT</code>, which causes the default segment base for anything in
  268 the segment to be the special group <code>FLAT</code>, and also defines the
  269 group if it is not already defined.</p>
  270 </li>
  271 <li>
  272 <p>The <code>obj</code> file format also allows segments to be declared as
  273 having a pre-defined absolute segment address, although no linkers are
  274 currently known to make sensible use of this feature; nevertheless, NASM
  275 allows you to declare a segment such as
  276 <code>SEGMENT SCREEN ABSOLUTE=0xB800</code> if you need to. The
  277 <code>ABSOLUTE</code> and <code>ALIGN</code> keywords are mutually
  278 exclusive.</p>
  279 </li>
  280 </ul>
  281 <p>NASM's default segment attributes are <code>PUBLIC</code>,
  282 <code>ALIGN=1</code>, no class, no overlay, and <code>USE16</code>.</p>
  283 <h4 id="section-8.4.2">8.4.2 <code>GROUP</code>: Defining Groups of Segments</h4>
  284 <p>The <code>obj</code> format also allows segments to be grouped, so that
  285 a single segment register can be used to refer to all the segments in a
  286 group. NASM therefore supplies the <code>GROUP</code> directive, whereby
  287 you can code</p>
  288 <pre>
  289 segment data 
  291         ; some data 
  293 segment bss 
  295         ; some uninitialized data 
  297 group dgroup data bss
  298 </pre>
  299 <p>which will define a group called <code>dgroup</code> to contain the
  300 segments <code>data</code> and <code>bss</code>. Like <code>SEGMENT</code>,
  301 <code>GROUP</code> causes the group name to be defined as a symbol, so that
  302 you can refer to a variable <code>var</code> in the <code>data</code>
  303 segment as <code>var wrt data</code> or as <code>var wrt dgroup</code>,
  304 depending on which segment value is currently in your segment register.</p>
  305 <p>If you just refer to <code>var</code>, however, and <code>var</code> is
  306 declared in a segment which is part of a group, then NASM will default to
  307 giving you the offset of <code>var</code> from the beginning of the
  308 <em>group</em>, not the <em>segment</em>. Therefore <code>SEG var</code>,
  309 also, will return the group base rather than the segment base.</p>
  310 <p>NASM will allow a segment to be part of more than one group, but will
  311 generate a warning if you do this. Variables declared in a segment which is
  312 part of more than one group will default to being relative to the first
  313 group that was defined to contain the segment.</p>
  314 <p>A group does not have to contain any segments; you can still make
  315 <code>WRT</code> references to a group which does not contain the variable
  316 you are referring to. OS/2, for example, defines the special group
  317 <code>FLAT</code> with no segments in it.</p>
  318 <h4 id="section-8.4.3">8.4.3 <code>UPPERCASE</code>: Disabling Case Sensitivity in Output</h4>
  319 <p>Although NASM itself is case sensitive, some OMF linkers are not;
  320 therefore it can be useful for NASM to output single-case object files. The
  321 <code>UPPERCASE</code> format-specific directive causes all segment, group
  322 and symbol names that are written to the object file to be forced to upper
  323 case just before being written. Within a source file, NASM is still
  324 case-sensitive; but the object file can be written entirely in upper case
  325 if desired.</p>
  326 <p><code>UPPERCASE</code> is used alone on a line; it requires no
  327 parameters.</p>
  328 <h4 id="section-8.4.4">8.4.4 <code>IMPORT</code>: Importing DLL Symbols</h4>
  329 <p>The <code>IMPORT</code> format-specific directive defines a symbol to be
  330 imported from a DLL, for use if you are writing a DLL's import library in
  331 NASM. You still need to declare the symbol as <code>EXTERN</code> as well
  332 as using the <code>IMPORT</code> directive.</p>
  333 <p>The <code>IMPORT</code> directive takes two required parameters,
  334 separated by white space, which are (respectively) the name of the symbol
  335 you wish to import and the name of the library you wish to import it from.
  336 For example:</p>
  337 <pre>
  338     import  WSAStartup wsock32.dll
  339 </pre>
  340 <p>A third optional parameter gives the name by which the symbol is known
  341 in the library you are importing it from, in case this is not the same as
  342 the name you wish the symbol to be known by to your code once you have
  343 imported it. For example:</p>
  344 <pre>
  345     import  asyncsel wsock32.dll WSAAsyncSelect
  346 </pre>
  347 <h4 id="section-8.4.5">8.4.5 <code>EXPORT</code>: Exporting DLL Symbols</h4>
  348 <p>The <code>EXPORT</code> format-specific directive defines a global
  349 symbol to be exported as a DLL symbol, for use if you are writing a DLL in
  350 NASM. You still need to declare the symbol as <code>GLOBAL</code> as well
  351 as using the <code>EXPORT</code> directive.</p>
  352 <p><code>EXPORT</code> takes one required parameter, which is the name of
  353 the symbol you wish to export, as it was defined in your source file. An
  354 optional second parameter (separated by white space from the first) gives
  355 the <em>external</em> name of the symbol: the name by which you wish the
  356 symbol to be known to programs using the DLL. If this name is the same as
  357 the internal name, you may leave the second parameter off.</p>
  358 <p>Further parameters can be given to define attributes of the exported
  359 symbol. These parameters, like the second, are separated by white space. If
  360 further parameters are given, the external name must also be specified,
  361 even if it is the same as the internal name. The available attributes are:</p>
  362 <ul>
  363 <li>
  364 <p><code>resident</code> indicates that the exported name is to be kept
  365 resident by the system loader. This is an optimization for frequently used
  366 symbols imported by name.</p>
  367 </li>
  368 <li>
  369 <p><code>nodata</code> indicates that the exported symbol is a function
  370 which does not make use of any initialized data.</p>
  371 </li>
  372 <li>
  373 <p><code>parm=NNN</code>, where <code>NNN</code> is an integer, sets the
  374 number of parameter words for the case in which the symbol is a call gate
  375 between 32-bit and 16-bit segments.</p>
  376 </li>
  377 <li>
  378 <p>An attribute which is just a number indicates that the symbol should be
  379 exported with an identifying number (ordinal), and gives the desired
  380 number.</p>
  381 </li>
  382 </ul>
  383 <p>For example:</p>
  384 <pre>
  385     export  myfunc 
  386     export  myfunc TheRealMoreFormalLookingFunctionName 
  387     export  myfunc myfunc 1234  ; export by ordinal 
  388     export  myfunc myfunc resident parm=23 nodata
  389 </pre>
  390 <h4 id="section-8.4.6">8.4.6 <code>..start</code>: Defining the Program Entry Point</h4>
  391 <p><code>OMF</code> linkers require exactly one of the object files being
  392 linked to define the program entry point, where execution will begin when
  393 the program is run. If the object file that defines the entry point is
  394 assembled using NASM, you specify the entry point by declaring the special
  395 symbol <code>..start</code> at the point where you wish execution to begin.</p>
  396 <h4 id="section-8.4.7">8.4.7 <code>obj</code> Extensions to the <code>EXTERN</code> Directive</h4>
  397 <p>If you declare an external symbol with the directive</p>
  398 <pre>
  399     extern  foo
  400 </pre>
  401 <p>then references such as <code>mov ax,foo</code> will give you the offset
  402 of <code>foo</code> from its preferred segment base (as specified in
  403 whichever module <code>foo</code> is actually defined in). So to access the
  404 contents of <code>foo</code> you will usually need to do something like</p>
  405 <pre>
  406         mov     ax,seg foo      ; get preferred segment base 
  407         mov     es,ax           ; move it into ES 
  408         mov     ax,[es:foo]     ; and use offset `foo' from it
  409 </pre>
  410 <p>This is a little unwieldy, particularly if you know that an external is
  411 going to be accessible from a given segment or group, say
  412 <code>dgroup</code>. So if <code>DS</code> already contained
  413 <code>dgroup</code>, you could simply code</p>
  414 <pre>
  415         mov     ax,[foo wrt dgroup]
  416 </pre>
  417 <p>However, having to type this every time you want to access
  418 <code>foo</code> can be a pain; so NASM allows you to declare
  419 <code>foo</code> in the alternative form</p>
  420 <pre>
  421     extern  foo:wrt dgroup
  422 </pre>
  423 <p>This form causes NASM to pretend that the preferred segment base of
  424 <code>foo</code> is in fact <code>dgroup</code>; so the expression
  425 <code>seg foo</code> will now return <code>dgroup</code>, and the
  426 expression <code>foo</code> is equivalent to <code>foo wrt dgroup</code>.</p>
  427 <p>This default-<code>WRT</code> mechanism can be used to make externals
  428 appear to be relative to any group or segment in your program. It can also
  429 be applied to common variables: see <a href="#section-8.4.8">section
  430 8.4.8</a>.</p>
  431 <h4 id="section-8.4.8">8.4.8 <code>obj</code> Extensions to the <code>COMMON</code> Directive</h4>
  432 <p>The <code>obj</code> format allows common variables to be either near or
  433 far; NASM allows you to specify which your variables should be by the use
  434 of the syntax</p>
  435 <pre>
  436 common  nearvar 2:near   ; `nearvar' is a near common 
  437 common  farvar  10:far   ; and `farvar' is far
  438 </pre>
  439 <p>Far common variables may be greater in size than 64Kb, and so the OMF
  440 specification says that they are declared as a number of <em>elements</em>
  441 of a given size. So a 10-byte far common variable could be declared as ten
  442 one-byte elements, five two-byte elements, two five-byte elements or one
  443 ten-byte element.</p>
  444 <p>Some <code>OMF</code> linkers require the element size, as well as the
  445 variable size, to match when resolving common variables declared in more
  446 than one module. Therefore NASM must allow you to specify the element size
  447 on your far common variables. This is done by the following syntax:</p>
  448 <pre>
  449 common  c_5by2  10:far 5        ; two five-byte elements 
  450 common  c_2by5  10:far 2        ; five two-byte elements
  451 </pre>
  452 <p>If no element size is specified, the default is 1. Also, the
  453 <code>FAR</code> keyword is not required when an element size is specified,
  454 since only far commons may have element sizes at all. So the above
  455 declarations could equivalently be</p>
  456 <pre>
  457 common  c_5by2  10:5            ; two five-byte elements 
  458 common  c_2by5  10:2            ; five two-byte elements
  459 </pre>
  460 <p>In addition to these extensions, the <code>COMMON</code> directive in
  461 <code>obj</code> also supports default-<code>WRT</code> specification like
  462 <code>EXTERN</code> does (explained in <a href="#section-8.4.7">section
  463 8.4.7</a>). So you can also declare things like</p>
  464 <pre>
  465 common  foo     10:wrt dgroup 
  466 common  bar     16:far 2:wrt data 
  467 common  baz     24:wrt data:6
  468 </pre>
  469 <h4 id="section-8.4.9">8.4.9 Embedded File Dependency Information</h4>
  470 <p>Since NASM 2.13.02, <code>obj</code> files contain embedded dependency
  471 file information. To suppress the generation of dependencies, use</p>
  472 <pre>
  473 %pragma obj nodepend
  474 </pre>
  475 <h3 id="section-8.5">8.5 <code>win32</code>: Microsoft Win32 Object Files</h3>
  476 <p>The <code>win32</code> output format generates Microsoft Win32 object
  477 files, suitable for passing to Microsoft linkers such as Visual C++. Note
  478 that Borland Win32 compilers do not use this format, but use
  479 <code>obj</code> instead (see <a href="#section-8.4">section 8.4</a>).</p>
  480 <p><code>win32</code> provides a default output file-name extension of
  481 <code>.obj</code>.</p>
  482 <p>Note that although Microsoft say that Win32 object files follow the
  483 <code>COFF</code> (Common Object File Format) standard, the object files
  484 produced by Microsoft Win32 compilers are not compatible with COFF linkers
  485 such as DJGPP's, and vice versa. This is due to a difference of opinion
  486 over the precise semantics of PC-relative relocations. To produce COFF
  487 files suitable for DJGPP, use NASM's <code>coff</code> output format;
  488 conversely, the <code>coff</code> format does not produce object files that
  489 Win32 linkers can generate correct output from.</p>
  490 <h4 id="section-8.5.1">8.5.1 <code>win32</code> Extensions to the <code>SECTION</code> Directive</h4>
  491 <p>Like the <code>obj</code> format, <code>win32</code> allows you to
  492 specify additional information on the <code>SECTION</code> directive line,
  493 to control the type and properties of sections you declare. Section types
  494 and properties are generated automatically by NASM for the standard section
  495 names <code>.text</code>, <code>.data</code> and <code>.bss</code>, but may
  496 still be overridden by these qualifiers.</p>
  497 <p>The available qualifiers are:</p>
  498 <ul>
  499 <li>
  500 <p><code>code</code>, or equivalently <code>text</code>, defines the
  501 section to be a code section. This marks the section as readable and
  502 executable, but not writable, and also indicates to the linker that the
  503 type of the section is code.</p>
  504 </li>
  505 <li>
  506 <p><code>data</code> and <code>bss</code> define the section to be a data
  507 section, analogously to <code>code</code>. Data sections are marked as
  508 readable and writable, but not executable. <code>data</code> declares an
  509 initialized data section, whereas <code>bss</code> declares an
  510 uninitialized data section.</p>
  511 </li>
  512 <li>
  513 <p><code>rdata</code> declares an initialized data section that is readable
  514 but not writable. Microsoft compilers use this section to place constants
  515 in it.</p>
  516 </li>
  517 <li>
  518 <p><code>info</code> defines the section to be an informational section,
  519 which is not included in the executable file by the linker, but may (for
  520 example) pass information <em>to</em> the linker. For example, declaring an
  521 <code>info</code>&ndash;type section called <code>.drectve</code> causes
  522 the linker to interpret the contents of the section as command-line
  523 options.</p>
  524 </li>
  525 <li>
  526 <p><code>align=</code>, used with a trailing number as in <code>obj</code>,
  527 gives the alignment requirements of the section. The maximum you may
  528 specify is 64: the Win32 object file format contains no means to request a
  529 greater section alignment than this. If alignment is not explicitly
  530 specified, the defaults are 16-byte alignment for code sections, 8-byte
  531 alignment for rdata sections and 4-byte alignment for data (and BSS)
  532 sections. Informational sections get a default alignment of 1 byte (no
  533 alignment), though the value does not matter.</p>
  534 </li>
  535 </ul>
  536 <p>The defaults assumed by NASM if you do not specify the above qualifiers
  537 are:</p>
  538 <pre>
  539 section .text    code  align=16 
  540 section .data    data  align=4 
  541 section .rdata   rdata align=8 
  542 section .bss     bss   align=4
  543 </pre>
  544 <p>The <code>win64</code> format also adds:</p>
  545 <pre>
  546 section .pdata   rdata align=4 
  547 section .xdata   rdata align=8
  548 </pre>
  549 <p>Any other section name is treated by default like <code>.text</code>.</p>
  550 <h4 id="section-8.5.2">8.5.2 <code>win32</code>: Safe Structured Exception Handling</h4>
  551 <p>Among other improvements in Windows XP SP2 and Windows Server 2003
  552 Microsoft has introduced concept of "safe structured exception handling."
  553 General idea is to collect handlers' entry points in designated read-only
  554 table and have alleged entry point verified against this table prior
  555 exception control is passed to the handler. In order for an executable
  556 module to be equipped with such "safe exception handler table," all object
  557 modules on linker command line has to comply with certain criteria. If one
  558 single module among them does not, then the table in question is omitted
  559 and above mentioned run-time checks will not be performed for application
  560 in question. Table omission is by default silent and therefore can be
  561 easily overlooked. One can instruct linker to refuse to produce binary
  562 without such table by passing <code>/safeseh</code> command line option.</p>
  563 <p>Without regard to this run-time check merits it's natural to expect NASM
  564 to be capable of generating modules suitable for <code>/safeseh</code>
  565 linking. From developer's viewpoint the problem is two-fold:</p>
  566 <ul>
  567 <li>
  568 <p>how to adapt modules not deploying exception handlers of their own;</p>
  569 </li>
  570 <li>
  571 <p>how to adapt/develop modules utilizing custom exception handling;</p>
  572 </li>
  573 </ul>
  574 <p>Former can be easily achieved with any NASM version by adding following
  575 line to source code:</p>
  576 <pre>
  577 $@feat.00 equ 1
  578 </pre>
  579 <p>As of version 2.03 NASM adds this absolute symbol automatically. If it's
  580 not already present to be precise. I.e. if for whatever reason developer
  581 would choose to assign another value in source file, it would still be
  582 perfectly possible.</p>
  583 <p>Registering custom exception handler on the other hand requires certain
  584 "magic." As of version 2.03 additional directive is implemented,
  585 <code>safeseh</code>, which instructs the assembler to produce
  586 appropriately formatted input data for above mentioned "safe exception
  587 handler table." Its typical use would be:</p>
  588 <pre>
  589 section .text 
  590 extern  _MessageBoxA@16 
  591 %if     __?NASM_VERSION_ID?__ &gt;= 0x02030000 
  592 safeseh handler         ; register handler as "safe handler" 
  593 %endif 
  594 handler: 
  595         push    DWORD 1 ; MB_OKCANCEL 
  596         push    DWORD caption 
  597         push    DWORD text 
  598         push    DWORD 0 
  599         call    _MessageBoxA@16 
  600         sub     eax,1   ; incidentally suits as return value 
  601                         ; for exception handler 
  602         ret 
  603 global  _main 
  604 _main: 
  605         push    DWORD handler 
  606         push    DWORD [fs:0] 
  607         mov     DWORD [fs:0],esp ; engage exception handler 
  608         xor     eax,eax 
  609         mov     eax,DWORD[eax]   ; cause exception 
  610         pop     DWORD [fs:0]     ; disengage exception handler 
  611         add     esp,4 
  612         ret 
  613 text:   db      'OK to rethrow, CANCEL to generate core dump',0 
  614 caption:db      'SEGV',0 
  616 section .drectve info 
  617         db      '/defaultlib:user32.lib /defaultlib:msvcrt.lib '
  618 </pre>
  619 <p>As you might imagine, it's perfectly possible to produce .exe binary
  620 with "safe exception handler table" and yet engage unregistered exception
  621 handler. Indeed, handler is engaged by simply manipulating
  622 <code>[fs:0]</code> location at run-time, something linker has no power
  623 over, run-time that is. It should be explicitly mentioned that such failure
  624 to register handler's entry point with <code>safeseh</code> directive has
  625 undesired side effect at run-time. If exception is raised and unregistered
  626 handler is to be executed, the application is abruptly terminated without
  627 any notification whatsoever. One can argue that system could at least have
  628 logged some kind "non-safe exception handler in x.exe at address n" message
  629 in event log, but no, literally no notification is provided and user is
  630 left with no clue on what caused application failure.</p>
  631 <p>Finally, all mentions of linker in this paragraph refer to Microsoft
  632 linker version 7.x and later. Presence of <code>@feat.00</code> symbol and
  633 input data for "safe exception handler table" causes no backward
  634 incompatibilities and "safeseh" modules generated by NASM 2.03 and later
  635 can still be linked by earlier versions or non-Microsoft linkers.</p>
  636 <h4 id="section-8.5.3">8.5.3 Debugging formats for Windows </h4>
  637 <p>The <code>win32</code> and <code>win64</code> formats support the
  638 Microsoft CodeView debugging format. Currently CodeView version 8 format is
  639 supported (<code>cv8</code>), but newer versions of the CodeView debugger
  640 should be able to handle this format as well.</p>
  641 <h3 id="section-8.6">8.6 <code>win64</code>: Microsoft Win64 Object Files</h3>
  642 <p>The <code>win64</code> output format generates Microsoft Win64 object
  643 files, which is nearly 100% identical to the <code>win32</code> object
  644 format (<a href="#section-8.5">section 8.5</a>) with the exception that it
  645 is meant to target 64-bit code and the x86-64 platform altogether. This
  646 object file is used exactly the same as the <code>win32</code> object
  647 format (<a href="#section-8.5">section 8.5</a>), in NASM, with regard to
  648 this exception.</p>
  649 <h4 id="section-8.6.1">8.6.1 <code>win64</code>: Writing Position-Independent Code</h4>
  650 <p>While <code>REL</code> takes good care of RIP-relative addressing, there
  651 is one aspect that is easy to overlook for a Win64 programmer: indirect
  652 references. Consider a switch dispatch table:</p>
  653 <pre>
  654         jmp     qword [dsptch+rax*8] 
  655         ... 
  656 dsptch: dq      case0 
  657         dq      case1 
  658         ...
  659 </pre>
  660 <p>Even a novice Win64 assembler programmer will soon realize that the code
  661 is not 64-bit savvy. Most notably linker will refuse to link it with</p>
  662 <pre>
  663 'ADDR32' relocation to '.text' invalid without /LARGEADDRESSAWARE:NO
  664 </pre>
  665 <p>So [s]he will have to split jmp instruction as following:</p>
  666 <pre>
  667         lea     rbx,[rel dsptch] 
  668         jmp     qword [rbx+rax*8]
  669 </pre>
  670 <p>What happens behind the scene is that effective address in
  671 <code>lea</code> is encoded relative to instruction pointer, or in
  672 perfectly position-independent manner. But this is only part of the
  673 problem! Trouble is that in .dll context <code>caseN</code> relocations
  674 will make their way to the final module and might have to be adjusted at
  675 .dll load time. To be specific when it can't be loaded at preferred
  676 address. And when this occurs, pages with such relocations will be rendered
  677 private to current process, which kind of undermines the idea of sharing
  678 .dll. But no worry, it's trivial to fix:</p>
  679 <pre>
  680         lea     rbx,[rel dsptch] 
  681         add     rbx,[rbx+rax*8] 
  682         jmp     rbx 
  683         ... 
  684 dsptch: dq      case0-dsptch 
  685         dq      case1-dsptch 
  686         ...
  687 </pre>
  688 <p>NASM version 2.03 and later provides another alternative,
  689 <code>wrt ..imagebase</code> operator, which returns offset from base
  690 address of the current image, be it .exe or .dll module, therefore the
  691 name. For those acquainted with PE-COFF format base address denotes start
  692 of <code>IMAGE_DOS_HEADER</code> structure. Here is how to implement switch
  693 with these image-relative references:</p>
  694 <pre>
  695         lea     rbx,[rel dsptch] 
  696         mov     eax,[rbx+rax*4] 
  697         sub     rbx,dsptch wrt ..imagebase 
  698         add     rbx,rax 
  699         jmp     rbx 
  700         ... 
  701 dsptch: dd      case0 wrt ..imagebase 
  702         dd      case1 wrt ..imagebase
  703 </pre>
  704 <p>One can argue that the operator is redundant. Indeed, snippet before
  705 last works just fine with any NASM version and is not even Windows
  706 specific... The real reason for implementing <code>wrt ..imagebase</code>
  707 will become apparent in next paragraph.</p>
  708 <p>It should be noted that <code>wrt ..imagebase</code> is defined as
  709 32-bit operand only:</p>
  710 <pre>
  711         dd      label wrt ..imagebase           ; ok 
  712         dq      label wrt ..imagebase           ; bad 
  713         mov     eax,label wrt ..imagebase       ; ok 
  714         mov     rax,label wrt ..imagebase       ; bad
  715 </pre>
  716 <h4 id="section-8.6.2">8.6.2 <code>win64</code>: Structured Exception Handling</h4>
  717 <p>Structured exception handing in Win64 is completely different matter
  718 from Win32. Upon exception program counter value is noted, and
  719 linker-generated table comprising start and end addresses of all the
  720 functions [in given executable module] is traversed and compared to the
  721 saved program counter. Thus so called <code>UNWIND_INFO</code> structure is
  722 identified. If it's not found, then offending subroutine is assumed to be
  723 "leaf" and just mentioned lookup procedure is attempted for its caller. In
  724 Win64 leaf function is such function that does not call any other function
  725 <em>nor</em> modifies any Win64 non-volatile registers, including stack
  726 pointer. The latter ensures that it's possible to identify leaf function's
  727 caller by simply pulling the value from the top of the stack.</p>
  728 <p>While majority of subroutines written in assembler are not calling any
  729 other function, requirement for non-volatile registers' immutability leaves
  730 developer with not more than 7 registers and no stack frame, which is not
  731 necessarily what [s]he counted with. Customarily one would meet the
  732 requirement by saving non-volatile registers on stack and restoring them
  733 upon return, so what can go wrong? If [and only if] an exception is raised
  734 at run-time and no <code>UNWIND_INFO</code> structure is associated with
  735 such "leaf" function, the stack unwind procedure will expect to find
  736 caller's return address on the top of stack immediately followed by its
  737 frame. Given that developer pushed caller's non-volatile registers on
  738 stack, would the value on top point at some code segment or even
  739 addressable space? Well, developer can attempt copying caller's return
  740 address to the top of stack and this would actually work in some very
  741 specific circumstances. But unless developer can guarantee that these
  742 circumstances are always met, it's more appropriate to assume worst case
  743 scenario, i.e. stack unwind procedure going berserk. Relevant question is
  744 what happens then? Application is abruptly terminated without any
  745 notification whatsoever. Just like in Win32 case, one can argue that system
  746 could at least have logged "unwind procedure went berserk in x.exe at
  747 address n" in event log, but no, no trace of failure is left.</p>
  748 <p>Now, when we understand significance of the <code>UNWIND_INFO</code>
  749 structure, let's discuss what's in it and/or how it's processed. First of
  750 all it is checked for presence of reference to custom language-specific
  751 exception handler. If there is one, then it's invoked. Depending on the
  752 return value, execution flow is resumed (exception is said to be
  753 "handled"), <em>or</em> rest of <code>UNWIND_INFO</code> structure is
  754 processed as following. Beside optional reference to custom handler, it
  755 carries information about current callee's stack frame and where
  756 non-volatile registers are saved. Information is detailed enough to be able
  757 to reconstruct contents of caller's non-volatile registers upon call to
  758 current callee. And so caller's context is reconstructed, and then unwind
  759 procedure is repeated, i.e. another <code>UNWIND_INFO</code> structure is
  760 associated, this time, with caller's instruction pointer, which is then
  761 checked for presence of reference to language-specific handler, etc. The
  762 procedure is recursively repeated till exception is handled. As last resort
  763 system "handles" it by generating memory core dump and terminating the
  764 application.</p>
  765 <p>As for the moment of this writing NASM unfortunately does not facilitate
  766 generation of above mentioned detailed information about stack frame
  767 layout. But as of version 2.03 it implements building blocks for generating
  768 structures involved in stack unwinding. As simplest example, here is how to
  769 deploy custom exception handler for leaf function:</p>
  770 <pre>
  771 default rel 
  772 section .text 
  773 extern  MessageBoxA 
  774 handler: 
  775         sub     rsp,40 
  776         mov     rcx,0 
  777         lea     rdx,[text] 
  778         lea     r8,[caption] 
  779         mov     r9,1    ; MB_OKCANCEL 
  780         call    MessageBoxA 
  781         sub     eax,1   ; incidentally suits as return value 
  782                         ; for exception handler 
  783         add     rsp,40 
  784         ret 
  785 global  main 
  786 main: 
  787         xor     rax,rax 
  788         mov     rax,QWORD[rax]  ; cause exception 
  789         ret 
  790 main_end: 
  791 text:   db      'OK to rethrow, CANCEL to generate core dump',0 
  792 caption:db      'SEGV',0 
  794 section .pdata  rdata align=4 
  795         dd      main wrt ..imagebase 
  796         dd      main_end wrt ..imagebase 
  797         dd      xmain wrt ..imagebase 
  798 section .xdata  rdata align=8 
  799 xmain:  db      9,0,0,0 
  800         dd      handler wrt ..imagebase 
  801 section .drectve info 
  802         db      '/defaultlib:user32.lib /defaultlib:msvcrt.lib '
  803 </pre>
  804 <p>What you see in <code>.pdata</code> section is element of the "table
  805 comprising start and end addresses of function" along with reference to
  806 associated <code>UNWIND_INFO</code> structure. And what you see in
  807 <code>.xdata</code> section is <code>UNWIND_INFO</code> structure
  808 describing function with no frame, but with designated exception handler.
  809 References are <em>required</em> to be image-relative (which is the real
  810 reason for implementing <code>wrt ..imagebase</code> operator). It should
  811 be noted that <code>rdata align=n</code>, as well as
  812 <code>wrt ..imagebase</code>, are optional in these two segments' contexts,
  813 i.e. can be omitted. Latter means that <em>all</em> 32-bit references, not
  814 only above listed required ones, placed into these two segments turn out
  815 image-relative. Why is it important to understand? Developer is allowed to
  816 append handler-specific data to <code>UNWIND_INFO</code> structure, and if
  817 [s]he adds a 32-bit reference, then [s]he will have to remember to adjust
  818 its value to obtain the real pointer.</p>
  819 <p>As already mentioned, in Win64 terms leaf function is one that does not
  820 call any other function <em>nor</em> modifies any non-volatile register,
  821 including stack pointer. But it's not uncommon that assembler programmer
  822 plans to utilize every single register and sometimes even have variable
  823 stack frame. Is there anything one can do with bare building blocks? I.e.
  824 besides manually composing fully-fledged <code>UNWIND_INFO</code>
  825 structure, which would surely be considered error-prone? Yes, there is.
  826 Recall that exception handler is called first, before stack layout is
  827 analyzed. As it turned out, it's perfectly possible to manipulate current
  828 callee's context in custom handler in manner that permits further stack
  829 unwinding. General idea is that handler would not actually "handle" the
  830 exception, but instead restore callee's context, as it was at its entry
  831 point and thus mimic leaf function. In other words, handler would simply
  832 undertake part of unwinding procedure. Consider following example:</p>
  833 <pre>
  834 function: 
  835         mov     rax,rsp         ; copy rsp to volatile register 
  836         push    r15             ; save non-volatile registers 
  837         push    rbx 
  838         push    rbp 
  839         mov     r11,rsp         ; prepare variable stack frame 
  840         sub     r11,rcx 
  841         and     r11,-64 
  842         mov     QWORD[r11],rax  ; check for exceptions 
  843         mov     rsp,r11         ; allocate stack frame 
  844         mov     QWORD[rsp],rax  ; save original rsp value 
  845 magic_point: 
  846         ... 
  847         mov     r11,QWORD[rsp]  ; pull original rsp value 
  848         mov     rbp,QWORD[r11-24] 
  849         mov     rbx,QWORD[r11-16] 
  850         mov     r15,QWORD[r11-8] 
  851         mov     rsp,r11         ; destroy frame 
  852         ret
  853 </pre>
  854 <p>The keyword is that up to <code>magic_point</code> original
  855 <code>rsp</code> value remains in chosen volatile register and no
  856 non-volatile register, except for <code>rsp</code>, is modified. While past
  857 <code>magic_point</code> <code>rsp</code> remains constant till the very
  858 end of the <code>function</code>. In this case custom language-specific
  859 exception handler would look like this:</p>
  860 <pre>
  862         CONTEXT *context,DISPATCHER_CONTEXT *disp) 
  863 {   ULONG64 *rsp; 
  864     if (context-&gt;Rip&lt;(ULONG64)magic_point) 
  865         rsp = (ULONG64 *)context-&gt;Rax; 
  866     else 
  867     {   rsp = ((ULONG64 **)context-&gt;Rsp)[0]; 
  868         context-&gt;Rbp = rsp[-3]; 
  869         context-&gt;Rbx = rsp[-2]; 
  870         context-&gt;R15 = rsp[-1]; 
  871     } 
  872     context-&gt;Rsp = (ULONG64)rsp; 
  874     memcpy (disp-&gt;ContextRecord,context,sizeof(CONTEXT)); 
  875     RtlVirtualUnwind(UNW_FLAG_NHANDLER,disp-&gt;ImageBase, 
  876         dips-&gt;ControlPc,disp-&gt;FunctionEntry,disp-&gt;ContextRecord, 
  877         &amp;disp-&gt;HandlerData,&amp;disp-&gt;EstablisherFrame,NULL); 
  878     return ExceptionContinueSearch; 
  879 }
  880 </pre>
  881 <p>As custom handler mimics leaf function, corresponding
  882 <code>UNWIND_INFO</code> structure does not have to contain any information
  883 about stack frame and its layout.</p>
  884 <h3 id="section-8.7">8.7 <code>coff</code>: Common Object File Format</h3>
  885 <p>The <code>coff</code> output type produces <code>COFF</code> object
  886 files suitable for linking with the DJGPP linker.</p>
  887 <p><code>coff</code> provides a default output file-name extension of
  888 <code>.o</code>.</p>
  889 <p>The <code>coff</code> format supports the same extensions to the
  890 <code>SECTION</code> directive as <code>win32</code> does, except that the
  891 <code>align</code> qualifier and the <code>info</code> section type are not
  892 supported.</p>
  893 <h3 id="section-8.8">8.8 <code>macho32</code> and <code>macho64</code>: Mach Object File Format</h3>
  894 <p>The <code>macho32</code> and <code>macho64</code> output formts produces
  895 Mach-O object files suitable for linking with the MacOS X linker.
  896 <code>macho</code> is a synonym for <code>macho32</code>.</p>
  897 <p><code>macho</code> provides a default output file-name extension of
  898 <code>.o</code>.</p>
  899 <h4 id="section-8.8.1">8.8.1 <code>macho</code> extensions to the <code>SECTION</code> Directive </h4>
  900 <p>The <code>macho</code> output format specifies section names in the
  901 format "<em>segment</em><code>,</code><em>section</em>". No spaces are
  902 allowed around the comma. The following flags can also be specified:</p>
  903 <ul>
  904 <li>
  905 <p><code>data</code> &ndash; this section contains initialized data items</p>
  906 </li>
  907 <li>
  908 <p><code>code</code> &ndash; this section contains code exclusively</p>
  909 </li>
  910 <li>
  911 <p><code>mixed</code> &ndash; this section contains both code and data</p>
  912 </li>
  913 <li>
  914 <p><code>bss</code> &ndash; this section is uninitialized and filled with
  915 zero</p>
  916 </li>
  917 <li>
  918 <p><code>zerofill</code> &ndash; same as <code>bss</code></p>
  919 </li>
  920 <li>
  921 <p><code>no_dead_strip</code> &ndash; inhibit dead code stripping for this
  922 section</p>
  923 </li>
  924 <li>
  925 <p><code>live_support</code> &ndash; set the live support flag for this
  926 section</p>
  927 </li>
  928 <li>
  929 <p><code>strip_static_syms</code> &ndash; strip static symbols for this
  930 section</p>
  931 </li>
  932 <li>
  933 <p><code>debug</code> &ndash; this section contains debugging information</p>
  934 </li>
  935 <li>
  936 <p><code>align=</code><em>alignment</em> &ndash; specify section alignment</p>
  937 </li>
  938 </ul>
  939 <p>The default is <code>data</code>, unless the section name is
  940 <code>__text</code> or <code>__bss</code> in which case the default is
  941 <code>text</code> or <code>bss</code>, respectively.</p>
  942 <p>For compatibility with other Unix platforms, the following standard
  943 names are also supported:</p>
  944 <pre>
  945 .text    = __TEXT,__text  text 
  946 .rodata  = __DATA,__const data 
  947 .data    = __DATA,__data  data 
  948 .bss     = __DATA,__bss   bss
  949 </pre>
  950 <p>If the <code>.rodata</code> section contains no relocations, it is
  951 instead put into the <code>__TEXT,__const</code> section unless this
  952 section has already been specified explicitly. However, it is probably
  953 better to specify <code>__TEXT,__const</code> and
  954 <code>__DATA,__const</code> explicitly as appropriate.</p>
  955 <h4 id="section-8.8.2">8.8.2 Thread Local Storage in Mach-O: <code>macho</code> special symbols and <code>WRT</code></h4>
  956 <p>Mach-O defines the following special symbols that can be used on the
  957 right-hand side of the <code>WRT</code> operator:</p>
  958 <ul>
  959 <li>
  960 <p><code>..tlvp</code> is used to specify access to thread-local storage.</p>
  961 </li>
  962 <li>
  963 <p><code>..gotpcrel</code> is used to specify references to the Global
  964 Offset Table. The GOT is supported in the <code>macho64</code> format only.</p>
  965 </li>
  966 </ul>
  967 <h4 id="section-8.8.3">8.8.3 <code>macho</code> specfic directive <code>subsections_via_symbols</code></h4>
  968 <p>The directive <code>subsections_via_symbols</code> sets the
  969 <code>MH_SUBSECTIONS_VIA_SYMBOLS</code> flag in the Mach-O header, that
  970 effectively separates a block (or a subsection) based on a symbol. It is
  971 often used for eliminating dead codes by a linker.</p>
  972 <p>This directive takes no arguments.</p>
  973 <p>This is a macro implemented as a <code>%pragma</code>. It can also be
  974 specified in its <code>%pragma</code> form, in which case it will not
  975 affect non-Mach-O builds of the same source code:</p>
  976 <pre>
  977      %pragma macho subsections_via_symbols
  978 </pre>
  979 <h4 id="section-8.8.4">8.8.4 <code>macho</code> specfic directive <code>no_dead_strip</code></h4>
  980 <p>The directive <code>no_dead_strip</code> sets the Mach-O
  981 <code>SH_NO_DEAD_STRIP</code> section flag on the section containing a a
  982 specific symbol. This directive takes a list of symbols as its arguments.</p>
  983 <p>This is a macro implemented as a <code>%pragma</code>. It can also be
  984 specified in its <code>%pragma</code> form, in which case it will not
  985 affect non-Mach-O builds of the same source code:</p>
  986 <pre>
  987      %pragma macho no_dead_strip symbol...
  988 </pre>
  989 <h4 id="section-8.8.5">8.8.5 <code>macho</code> specific extensions to the <code>GLOBAL</code> Directive: <code>private_extern</code></h4>
  990 <p>The directive extension to <code>GLOBAL</code> marks the symbol with
  991 limited global scope. For example, you can specify the global symbol with
  992 this extension:</p>
  993 <pre>
  994 global foo:private_extern 
  995 foo: 
  996          ; codes
  997 </pre>
  998 <p>Using with static linker will clear the private extern attribute. But
  999 linker option like <code>-keep_private_externs</code> can avoid it.</p>
 1000 <h3 id="section-8.9">8.9 <code>elf32</code>, <code>elf64</code>, <code>elfx32</code>: Executable and Linkable Format Object Files</h3>
 1001 <p>The <code>elf32</code>, <code>elf64</code> and <code>elfx32</code>
 1002 output formats generate <code>ELF32 and ELF64</code> (Executable and
 1003 Linkable Format) object files, as used by Linux as well as Unix System V,
 1004 including Solaris x86, UnixWare and SCO Unix. ELF provides a default output
 1005 file-name extension of <code>.o</code>. <code>elf</code> is a synonym for
 1006 <code>elf32</code>.</p>
 1007 <p>The <code>elfx32</code> format is used for the x32 ABI, which is a
 1008 32-bit ABI with the CPU in 64-bit mode.</p>
 1009 <h4 id="section-8.9.1">8.9.1 ELF specific directive <code>osabi</code></h4>
 1010 <p>The ELF header specifies the application binary interface for the target
 1011 operating system (OSABI). This field can be set by using the
 1012 <code>osabi</code> directive with the numeric value (0-255) of the target
 1013 system. If this directive is not used, the default value will be "UNIX
 1014 System V ABI" (0) which will work on most systems which support ELF.</p>
 1015 <h4 id="section-8.9.2">8.9.2 ELF extensions to the <code>SECTION</code> Directive </h4>
 1016 <p>Like the <code>obj</code> format, <code>elf</code> allows you to specify
 1017 additional information on the <code>SECTION</code> directive line, to
 1018 control the type and properties of sections you declare. Section types and
 1019 properties are generated automatically by NASM for the standard section
 1020 names, but may still be overridden by these qualifiers.</p>
 1021 <p>The available qualifiers are:</p>
 1022 <ul>
 1023 <li>
 1024 <p><code>alloc</code> defines the section to be one which is loaded into
 1025 memory when the program is run. <code>noalloc</code> defines it to be one
 1026 which is not, such as an informational or comment section.</p>
 1027 </li>
 1028 <li>
 1029 <p><code>exec</code> defines the section to be one which should have
 1030 execute permission when the program is run. <code>noexec</code> defines it
 1031 as one which should not.</p>
 1032 </li>
 1033 <li>
 1034 <p><code>write</code> defines the section to be one which should be
 1035 writable when the program is run. <code>nowrite</code> defines it as one
 1036 which should not.</p>
 1037 </li>
 1038 <li>
 1039 <p><code>progbits</code> defines the section to be one with explicit
 1040 contents stored in the object file: an ordinary code or data section, for
 1041 example.</p>
 1042 </li>
 1043 <li>
 1044 <p><code>nobits</code> defines the section to be one with no explicit
 1045 contents given, such as a BSS section.</p>
 1046 </li>
 1047 <li>
 1048 <p><code>note</code> indicates that this section contains ELF notes. The
 1049 content of ELF notes are specified using normal assembly instructions; it
 1050 is up to the programmer to ensure these are valid ELF notes.</p>
 1051 </li>
 1052 <li>
 1053 <p><code>preinit_array</code> indicates that this section contains function
 1054 addresses to be called before any other initialization has happened.</p>
 1055 </li>
 1056 <li>
 1057 <p><code>init_array</code> indicates that this section contains function
 1058 addresses to be called during initialization.</p>
 1059 </li>
 1060 <li>
 1061 <p><code>fini_array</code> indicates that this section contains function
 1062 pointers to be called during termination.</p>
 1063 </li>
 1064 <li>
 1065 <p><code>align=</code>, used with a trailing number as in <code>obj</code>,
 1066 gives the alignment requirements of the section.</p>
 1067 </li>
 1068 <li>
 1069 <p><code>byte</code>, <code>word</code>, <code>dword</code>,
 1070 <code>qword</code>, <code>tword</code>, <code>oword</code>,
 1071 <code>yword</code>, or <code>zword</code> with an optional
 1072 <code>*</code>multiplier specify the fundamental data item size for a
 1073 section which contains either fixed-sized data structures or strings; it
 1074 also sets a default alignment. This is generally used with the
 1075 <code>strings</code> and <code>merge</code> attributes (see below.) For
 1076 example <code>byte*4</code> defines a unit size of 4 bytes, with a default
 1077 alignment of 1; <code>dword</code> also defines a unit size of 4 bytes, but
 1078 with a default alignment of 4. The <code>align=</code> attribute, if
 1079 specified, overrides this default alignment.</p>
 1080 </li>
 1081 <li>
 1082 <p><code>pointer</code> is equivalent to <code>dword</code> for
 1083 <code>elf32</code> or <code>elfx32</code>, and <code>qword</code> for
 1084 <code>elf64</code>.</p>
 1085 </li>
 1086 <li>
 1087 <p><code>strings</code> indicate that this section contains exclusively
 1088 null-terminated strings. By default these are assumed to be byte strings,
 1089 but a size specifier can be used to override that.</p>
 1090 </li>
 1091 <li>
 1092 <p><code>merge</code> indicates that duplicate data elements in this
 1093 section should be merged with data elements from other object files. Data
 1094 elements can be either fixed-sized objects or null-terminatedstrings (with
 1095 the <code>strings</code> attribute.) A size specifier is required unless
 1096 <code>strings</code> is specified, in which case the size defaults to
 1097 <code>byte</code>.</p>
 1098 </li>
 1099 <li>
 1100 <p><code>tls</code> defines the section to be one which contains thread
 1101 local variables.</p>
 1102 </li>
 1103 </ul>
 1104 <p>The defaults assumed by NASM if you do not specify the above qualifiers
 1105 are:</p>
 1106 <p></p>
 1107 <pre>
 1108 section .text          progbits      alloc   exec    nowrite  align=16 
 1109 section .rodata        progbits      alloc   noexec  nowrite  align=4 
 1110 section .lrodata       progbits      alloc   noexec  nowrite  align=4 
 1111 section .data          progbits      alloc   noexec  write    align=4 
 1112 section .ldata         progbits      alloc   noexec  write    align=4 
 1113 section .bss           nobits        alloc   noexec  write    align=4 
 1114 section .lbss          nobits        alloc   noexec  write    align=4 
 1115 section .tdata         progbits      alloc   noexec  write    align=4   tls 
 1116 section .tbss          nobits        alloc   noexec  write    align=4   tls 
 1117 section .comment       progbits      noalloc noexec  nowrite  align=1 
 1118 section .preinit_array preinit_array alloc   noexec  nowrite  pointer 
 1119 section .init_array    init_array    alloc   noexec  nowrite  pointer 
 1120 section .fini_array    fini_array    alloc   noexec  nowrite  pointer 
 1121 section .note          note          noalloc noexec  nowrite  align=4 
 1122 section other          progbits      alloc   noexec  nowrite  align=1
 1123 </pre>
 1124 <p>(Any section name other than those in the above table is treated by
 1125 default like <code>other</code> in the above table. Please note that
 1126 section names are case sensitive.)</p>
 1127 <h4 id="section-8.9.3">8.9.3 Position-Independent Code: ELF Special Symbols and <code>WRT</code></h4>
 1128 <p>Since <code>ELF</code> does not support segment-base references, the
 1129 <code>WRT</code> operator is not used for its normal purpose; therefore
 1130 NASM's <code>elf</code> output format makes use of <code>WRT</code> for a
 1131 different purpose, namely the PIC-specific relocation types.</p>
 1132 <p><code>elf</code> defines five special symbols which you can use as the
 1133 right-hand side of the <code>WRT</code> operator to obtain PIC relocation
 1134 types. They are <code>..gotpc</code>, <code>..gotoff</code>,
 1135 <code>..got</code>, <code>..plt</code> and <code>..sym</code>. Their
 1136 functions are summarized here:</p>
 1137 <ul>
 1138 <li>
 1139 <p>Referring to the symbol marking the global offset table base using
 1140 <code>wrt ..gotpc</code> will end up giving the distance from the beginning
 1141 of the current section to the global offset table.
 1142 (<code>_GLOBAL_OFFSET_TABLE_</code> is the standard symbol name used to
 1143 refer to the GOT.) So you would then need to add <code>$$</code> to the
 1144 result to get the real address of the GOT.</p>
 1145 </li>
 1146 <li>
 1147 <p>Referring to a location in one of your own sections using
 1148 <code>wrt ..gotoff</code> will give the distance from the beginning of the
 1149 GOT to the specified location, so that adding on the address of the GOT
 1150 would give the real address of the location you wanted.</p>
 1151 </li>
 1152 <li>
 1153 <p>Referring to an external or global symbol using <code>wrt ..got</code>
 1154 causes the linker to build an entry <em>in</em> the GOT containing the
 1155 address of the symbol, and the reference gives the distance from the
 1156 beginning of the GOT to the entry; so you can add on the address of the
 1157 GOT, load from the resulting address, and end up with the address of the
 1158 symbol.</p>
 1159 </li>
 1160 <li>
 1161 <p>Referring to a procedure name using <code>wrt ..plt</code> causes the
 1162 linker to build a procedure linkage table entry for the symbol, and the
 1163 reference gives the address of the PLT entry. You can only use this in
 1164 contexts which would generate a PC-relative relocation normally (i.e. as
 1165 the destination for <code>CALL</code> or <code>JMP</code>), since ELF
 1166 contains no relocation type to refer to PLT entries absolutely.</p>
 1167 </li>
 1168 <li>
 1169 <p>Referring to a symbol name using <code>wrt ..sym</code> causes NASM to
 1170 write an ordinary relocation, but instead of making the relocation relative
 1171 to the start of the section and then adding on the offset to the symbol, it
 1172 will write a relocation record aimed directly at the symbol in question.
 1173 The distinction is a necessary one due to a peculiarity of the dynamic
 1174 linker.</p>
 1175 </li>
 1176 </ul>
 1177 <p>A fuller explanation of how to use these relocation types to write
 1178 shared libraries entirely in NASM is given in
 1179 <a href="nasmdo10.html#section-10.2">section 10.2</a>.</p>
 1180 <h4 id="section-8.9.4">8.9.4 Thread Local Storage in ELF: <code>elf</code> Special Symbols and <code>WRT</code></h4>
 1181 <ul>
 1182 <li>
 1183 <p>In ELF32 mode, referring to an external or global symbol using
 1184 <code>wrt ..tlsie</code>  causes the linker to build an entry <em>in</em>
 1185 the GOT containing the offset of the symbol within the TLS block, so you
 1186 can access the value of the symbol with code such as:</p>
 1187 <pre>
 1188        mov  eax,[tid wrt ..tlsie] 
 1189        mov  [gs:eax],ebx
 1190 </pre>
 1191 </li>
 1192 <li>
 1193 <p>In ELF64 or ELFx32 mode, referring to an external or global symbol using
 1194 <code>wrt ..gottpoff</code>  causes the linker to build an entry
 1195 <em>in</em> the GOT containing the offset of the symbol within the TLS
 1196 block, so you can access the value of the symbol with code such as:</p>
 1197 <pre>
 1198        mov   rax,[rel tid wrt ..gottpoff] 
 1199        mov   rcx,[fs:rax]
 1200 </pre>
 1201 </li>
 1202 </ul>
 1203 <h4 id="section-8.9.5">8.9.5 <code>elf</code> Extensions to the <code>GLOBAL</code> Directive</h4>
 1204 <p><code>ELF</code> object files can contain more information about a
 1205 global symbol than just its address: they can contain the size of the
 1206 symbol and its type as well. These are not merely debugger conveniences,
 1207 but are actually necessary when the program being written is a shared
 1208 library. NASM therefore supports some extensions to the <code>GLOBAL</code>
 1209 directive, allowing you to specify these features.</p>
 1210 <p>You can specify whether a global variable is a function or a data object
 1211 by suffixing the name with a colon and the word <code>function</code> or
 1212 <code>data</code>. (<code>object</code> is a synonym for
 1213 <code>data</code>.) For example:</p>
 1214 <pre>
 1215 global   hashlookup:function, hashtable:data
 1216 </pre>
 1217 <p>exports the global symbol <code>hashlookup</code> as a function and
 1218 <code>hashtable</code> as a data object.</p>
 1219 <p>Optionally, you can control the ELF visibility of the symbol. Just add
 1220 one of the visibility keywords: <code>default</code>,
 1221 <code>internal</code>, <code>hidden</code>, or <code>protected</code>. The
 1222 default is <code>default</code> of course. For example, to make
 1223 <code>hashlookup</code> hidden:</p>
 1224 <pre>
 1225 global   hashlookup:function hidden
 1226 </pre>
 1227 <p>Since version 2.15, it is possible to specify symbols binding. The
 1228 keywords are: <code>weak</code> to generate weak symbol or
 1229 <code>strong</code>. The default is <code>strong</code>.</p>
 1230 <p>You can also specify the size of the data associated with the symbol, as
 1231 a numeric expression (which may involve labels, and even forward
 1232 references) after the type specifier. Like this:</p>
 1233 <pre>
 1234 global  hashtable:data (hashtable.end - hashtable) 
 1236 hashtable: 
 1237         db this,that,theother  ; some data here 
 1238 .end:
 1239 </pre>
 1240 <p>This makes NASM automatically calculate the length of the table and
 1241 place that information into the <code>ELF</code> symbol table.</p>
 1242 <p>Declaring the type and size of global symbols is necessary when writing
 1243 shared library code. For more information, see
 1244 <a href="nasmdo10.html#section-10.2.4">section 10.2.4</a>.</p>
 1245 <h4 id="section-8.9.6">8.9.6 <code>elf</code> Extensions to the <code>EXTERN</code> Directive</h4>
 1246 <p>Since version 2.15 it is possible to specify keyword <code>weak</code>
 1247 to generate weak external reference. Example:</p>
 1248 <pre>
 1249 extern weak_ref:weak
 1250 </pre>
 1251 <h4 id="section-8.9.7">8.9.7 <code>elf</code> Extensions to the <code>COMMON</code> Directive </h4>
 1252 <p><code>ELF</code> also allows you to specify alignment requirements on
 1253 common variables. This is done by putting a number (which must be a power
 1254 of two) after the name and size of the common variable, separated (as
 1255 usual) by a colon. For example, an array of doublewords would benefit from
 1256 4-byte alignment:</p>
 1257 <pre>
 1258 common  dwordarray 128:4
 1259 </pre>
 1260 <p>This declares the total size of the array to be 128 bytes, and requires
 1261 that it be aligned on a 4-byte boundary.</p>
 1262 <h4 id="section-8.9.8">8.9.8 16-bit code and ELF </h4>
 1263 <p>Older versions of the <code>ELF32</code> specification did not provide
 1264 relocations for 8- and 16-bit values. It is now part of the formal
 1265 specification, and any new enough linker should support them.</p>
 1266 <p>ELF has currently no support for segmented programming.</p>
 1267 <h4 id="section-8.9.9">8.9.9 Debug formats and ELF </h4>
 1268 <p>ELF provides debug information in <code>STABS</code> and
 1269 <code>DWARF</code> formats. Line number information is generated for all
 1270 executable sections, but please note that only the ".text" section is
 1271 executable by default.</p>
 1272 <h3 id="section-8.10">8.10 <code>aout</code>: Linux <code>a.out</code> Object Files</h3>
 1273 <p>The <code>aout</code> format generates <code>a.out</code> object files,
 1274 in the form used by early Linux systems (current Linux systems use ELF, see
 1275 <a href="#section-8.9">section 8.9</a>.) These differ from other
 1276 <code>a.out</code> object files in that the magic number in the first four
 1277 bytes of the file is different; also, some implementations of
 1278 <code>a.out</code>, for example NetBSD's, support position-independent
 1279 code, which Linux's implementation does not.</p>
 1280 <p><code>a.out</code> provides a default output file-name extension of
 1281 <code>.o</code>.</p>
 1282 <p><code>a.out</code> is a very simple object format. It supports no
 1283 special directives, no special symbols, no use of <code>SEG</code> or
 1284 <code>WRT</code>, and no extensions to any standard directives. It supports
 1285 only the three standard section names <code>.text</code>,
 1286 <code>.data</code> and <code>.bss</code>.</p>
 1287 <h3 id="section-8.11">8.11 <code>aoutb</code>: NetBSD/FreeBSD/OpenBSD <code>a.out</code> Object Files</h3>
 1288 <p>The <code>aoutb</code> format generates <code>a.out</code> object files,
 1289 in the form used by the various free <code>BSD Unix</code> clones,
 1290 <code>NetBSD</code>, <code>FreeBSD</code> and <code>OpenBSD</code>. For
 1291 simple object files, this object format is exactly the same as
 1292 <code>aout</code> except for the magic number in the first four bytes of
 1293 the file. However, the <code>aoutb</code> format supports
 1294 position-independent code in the same way as the <code>elf</code> format,
 1295 so you can use it to write <code>BSD</code> shared libraries.</p>
 1296 <p><code>aoutb</code> provides a default output file-name extension of
 1297 <code>.o</code>.</p>
 1298 <p><code>aoutb</code> supports no special directives, no special symbols,
 1299 and only the three standard section names <code>.text</code>,
 1300 <code>.data</code> and <code>.bss</code>. However, it also supports the
 1301 same use of <code>WRT</code> as <code>elf</code> does, to provide
 1302 position-independent code relocation types. See
 1303 <a href="#section-8.9.3">section 8.9.3</a> for full documentation of this
 1304 feature.</p>
 1305 <p><code>aoutb</code> also supports the same extensions to the
 1306 <code>GLOBAL</code> directive as <code>elf</code> does: see
 1307 <a href="#section-8.9.5">section 8.9.5</a> for documentation of this.</p>
 1308 <h3 id="section-8.12">8.12 <code>as86</code>: Minix/Linux <code>as86</code> Object Files</h3>
 1309 <p>The Minix/Linux 16-bit assembler <code>as86</code> has its own
 1310 non-standard object file format. Although its companion linker
 1311 <code>ld86</code> produces something close to ordinary <code>a.out</code>
 1312 binaries as output, the object file format used to communicate between
 1313 <code>as86</code> and <code>ld86</code> is not itself <code>a.out</code>.</p>
 1314 <p>NASM supports this format, just in case it is useful, as
 1315 <code>as86</code>. <code>as86</code> provides a default output file-name
 1316 extension of <code>.o</code>.</p>
 1317 <p><code>as86</code> is a very simple object format (from the NASM user's
 1318 point of view). It supports no special directives, no use of
 1319 <code>SEG</code> or <code>WRT</code>, and no extensions to any standard
 1320 directives. It supports only the three standard section names
 1321 <code>.text</code>, <code>.data</code> and <code>.bss</code>. The only
 1322 special symbol supported is <code>..start</code>.</p>
 1323 <h3 id="section-8.13">8.13 <code>rdf</code>: Relocatable Dynamic Object File Format (deprecated)</h3>
 1324 <p><em>The RDOFF format is strongly deprecated and has been disabled
 1325 starting in NASM 2.15.04. The RDOFF backend has been broken since at least
 1326 NASM 2.14. The RDOFF utilities are scheduled to be removed from the NASM
 1327 distribution in NASM 2.16.</em> If you have a strong use case for the RDOFF
 1328 format, file a bug report at
 1329 <a href="https://bugs.nasm.us/"><code>https://bugs.nasm.us/</code></a> as
 1330 soon as possible.</p>
 1331 <p>The <code>rdf</code> output format produces <code>RDOFF</code> object
 1332 files. <code>RDOFF</code> (Relocatable Dynamic Object File Format) is a
 1333 home-grown object-file format, designed alongside NASM itself and
 1334 reflecting in its file format the internal structure of the assembler.</p>
 1335 <p><code>RDOFF</code> is not used by any well-known operating systems.
 1336 Those writing their own systems, however, may well wish to use
 1337 <code>RDOFF</code> as their object format, on the grounds that it is
 1338 designed primarily for simplicity and contains very little file-header
 1339 bureaucracy.</p>
 1340 <p>The Unix NASM archive, and the DOS archive which includes sources, both
 1341 contain an <code>rdoff</code> subdirectory holding a set of RDOFF
 1342 utilities: an RDF linker, an <code>RDF</code> static-library manager, an
 1343 RDF file dump utility, and a program which will load and execute an RDF
 1344 executable under Linux.</p>
 1345 <h4 id="section-8.13.1">8.13.1 Requiring a Library: The <code>LIBRARY</code> Directive</h4>
 1346 <p><code>RDOFF</code> contains a mechanism for an object file to demand a
 1347 given library to be linked to the module, either at load time or run time.
 1348 This is done by the <code>LIBRARY</code> directive, which takes one
 1349 argument which is the name of the module:</p>
 1350 <pre>
 1351     library  mylib.rdl
 1352 </pre>
 1353 <h4 id="section-8.13.2">8.13.2 Specifying a Module Name: The <code>MODULE</code> Directive</h4>
 1354 <p>Special <code>RDOFF</code> header record is used to store the name of
 1355 the module. It can be used, for example, by run-time loader to perform
 1356 dynamic linking. <code>MODULE</code> directive takes one argument which is
 1357 the name of current module:</p>
 1358 <pre>
 1359     module  mymodname
 1360 </pre>
 1361 <p>Note that when you statically link modules and tell linker to strip the
 1362 symbols from output file, all module names will be stripped too. To avoid
 1363 it, you should start module names with <code>$</code>, like:</p>
 1364 <pre>
 1365     module  $kernel.core
 1366 </pre>
 1367 <h4 id="section-8.13.3">8.13.3 <code>rdf</code> Extensions to the <code>GLOBAL</code> Directive</h4>
 1368 <p><code>RDOFF</code> global symbols can contain additional information
 1369 needed by the static linker. You can mark a global symbol as exported, thus
 1370 telling the linker do not strip it from target executable or library file.
 1371 Like in <code>ELF</code>, you can also specify whether an exported symbol
 1372 is a procedure (function) or data object.</p>
 1373 <p>Suffixing the name with a colon and the word <code>export</code> you
 1374 make the symbol exported:</p>
 1375 <pre>
 1376     global  sys_open:export
 1377 </pre>
 1378 <p>To specify that exported symbol is a procedure (function), you add the
 1379 word <code>proc</code> or <code>function</code> after declaration:</p>
 1380 <pre>
 1381     global  sys_open:export proc
 1382 </pre>
 1383 <p>Similarly, to specify exported data object, add the word
 1384 <code>data</code> or <code>object</code> to the directive:</p>
 1385 <pre>
 1386     global  kernel_ticks:export data
 1387 </pre>
 1388 <h4 id="section-8.13.4">8.13.4 <code>rdf</code> Extensions to the <code>EXTERN</code> Directive</h4>
 1389 <p>By default the <code>EXTERN</code> directive in <code>RDOFF</code>
 1390 declares a "pure external" symbol (i.e. the static linker will complain if
 1391 such a symbol is not resolved). To declare an "imported" symbol, which must
 1392 be resolved later during a dynamic linking phase, <code>RDOFF</code> offers
 1393 an additional <code>import</code> modifier. As in <code>GLOBAL</code>, you
 1394 can also specify whether an imported symbol is a procedure (function) or
 1395 data object. For example:</p>
 1396 <pre>
 1397     library $libc 
 1398     extern  _open:import 
 1399     extern  _printf:import proc 
 1400     extern  _errno:import data
 1401 </pre>
 1402 <p>Here the directive <code>LIBRARY</code> is also included, which gives
 1403 the dynamic linker a hint as to where to find requested symbols.</p>
 1404 <h3 id="section-8.14">8.14 <code>dbg</code>: Debugging Format</h3>
 1405 <p>The <code>dbg</code> format does not output an object file as such;
 1406 instead, it outputs a text file which contains a complete list of all the
 1407 transactions between the main body of NASM and the output-format back end
 1408 module. It is primarily intended to aid people who want to write their own
 1409 output drivers, so that they can get a clearer idea of the various requests
 1410 the main program makes of the output driver, and in what order they happen.</p>
 1411 <p>For simple files, one can easily use the <code>dbg</code> format like
 1412 this:</p>
 1413 <pre>
 1414 nasm -f dbg filename.asm
 1415 </pre>
 1416 <p>which will generate a diagnostic file called <code>filename.dbg</code>.
 1417 However, this will not work well on files which were designed for a
 1418 different object format, because each object format defines its own macros
 1419 (usually user-level forms of directives), and those macros will not be
 1420 defined in the <code>dbg</code> format. Therefore it can be useful to run
 1421 NASM twice, in order to do the preprocessing with the native object format
 1422 selected:</p>
 1423 <pre>
 1424 nasm -e -f rdf -o rdfprog.i rdfprog.asm 
 1425 nasm -a -f dbg rdfprog.i
 1426 </pre>
 1427 <p>This preprocesses <code>rdfprog.asm</code> into <code>rdfprog.i</code>,
 1428 keeping the <code>rdf</code> object format selected in order to make sure
 1429 RDF special directives are converted into primitive form correctly. Then
 1430 the preprocessed source is fed through the <code>dbg</code> format to
 1431 generate the final diagnostic output.</p>
 1432 <p>This workaround will still typically not work for programs intended for
 1433 <code>obj</code> format, because the <code>obj</code> <code>SEGMENT</code>
 1434 and <code>GROUP</code> directives have side effects of defining the segment
 1435 and group names as symbols; <code>dbg</code> will not do this, so the
 1436 program will not assemble. You will have to work around that by defining
 1437 the symbols yourself (using <code>EXTERN</code>, for example) if you really
 1438 need to get a <code>dbg</code> trace of an <code>obj</code>&ndash;specific
 1439 source file.</p>
 1440 <p><code>dbg</code> accepts any section name and any directives at all, and
 1441 logs them all to its output file.</p>
 1442 <p><code>dbg</code> accepts and logs any <code>%pragma</code>, but the
 1443 specific <code>%pragma</code>:</p>
 1444 <pre>
 1445      %pragma dbg maxdump &lt;size&gt;
 1446 </pre>
 1447 <p>where <code>&lt;size&gt;</code> is either a number or
 1448 <code>unlimited</code>, can be used to control the maximum size for dumping
 1449 the full contents of a <code>rawdata</code> output object.</p>
 1450 </div>
 1451 </body>
 1452 </html>