Fix PR 249

["Ben Elliston" <bje at au1 dot ibm dot com>]

This patch documents the .def file format for dlltool(1).  I struggled
to find a good way to format the file's grammar, but compromised with
table entries and @code/@var markup.

Tested with "make dvi" and inspection with xdvi(1).
Okay for mainline?

Ben


2004-12-06  Ben Elliston  <bje@au.ibm.com>

	PR binutils/249
	* doc/binutils.texi (def file format): New node.
	(dlltool): Use the tool name as the @chapter name, like all the
	other binutils.  Use @file{.def} throughout for consistency.

Index: binutils.texi
===================================================================
RCS file: /home/bje/src-cvs/src/binutils/doc/binutils.texi,v
retrieving revision 1.62
diff -u -p -r1.62 binutils.texi
--- binutils.texi	6 Dec 2004 05:35:31 -0000	1.62
+++ binutils.texi	6 Dec 2004 06:17:02 -0000
@@ -2854,16 +2854,25 @@ the Info entries for @file{binutils}.
 @end ignore
 
 @node dlltool
-@chapter Create files needed to build and use DLLs
+@chapter dlltool
 @cindex DLL
 @kindex dlltool
 
-@command{dlltool} may be used to create the files needed to build and use
-dynamic link libraries (DLLs).
+@command{dlltool} is used to create the files needed to create dynamic
+link libraries (DLLs) on systems which understand PE format image
+files such as Windows.  A DLL contains an export table which contains
+information that the runtime loader needs to resolve references from a
+referencing program.
+
+The export table is generated by this program by reading in a
+@file{.def} file or scanning the @file{.a} and @file{.o} files which
+will be in the DLL.  A @file{.o} file can contain information in
+special @samp{.drectve} sections with export information.
 
 @quotation
-@emph{Warning:} @command{dlltool} is not always built as part of the binary
-utilities, since it is only useful for those targets which support DLLs.
+@emph{Note:} @command{dlltool} is not always built as part of the
+binary utilities, since it is only useful for those targets which
+support DLLs.
 @end quotation
 
 @c man title dlltool Create files needed to build and use DLLs.
@@ -2906,13 +2915,13 @@ When creating a DLL, along with the sour
 to have three other files.  @command{dlltool} can help with the creation of
 these files.
 
-The first file is a @samp{.def} file which specifies which functions are
+The first file is a @file{.def} file which specifies which functions are
 exported from the DLL, which functions the DLL imports, and so on.  This
 is a text file and can be created by hand, or @command{dlltool} can be used
 to create it using the @option{-z} option.  In this case @command{dlltool}
 will scan the object files specified on its command line looking for
 those functions which have been specially marked as being exported and
-put entries for them in the .def file it creates.
+put entries for them in the @file{.def} file it creates.
 
 In order to mark a function as being exported from a DLL, it needs to
 have an @option{-export:<name_of_function>} entry in the @samp{.drectve}
@@ -2930,12 +2939,12 @@ The second file needed for DLL creation 
 is linked with the object files that make up the body of the DLL and it
 handles the interface between the DLL and the outside world.  This is a
 binary file and it can be created by giving the @option{-e} option to
-@command{dlltool} when it is creating or reading in a .def file. 
+@command{dlltool} when it is creating or reading in a @file{.def} file. 
 
 The third file needed for DLL creation is the library file that programs
 will link with in order to access the functions in the DLL.  This file
 can be created by giving the @option{-l} option to dlltool when it
-is creating or reading in a .def file.
+is creating or reading in a @file{.def} file.
 
 @command{dlltool} builds the library file by hand, but it builds the
 exports file by creating temporary files containing assembler statements
@@ -2969,7 +2978,7 @@ The command line options have the follow
 @item -d @var{filename}
 @itemx --input-def @var{filename}
 @cindex input .def file
-Specifies the name of a .def file to be read in and processed.
+Specifies the name of a @file{.def} file to be read in and processed.
 
 @item -b @var{filename}
 @itemx --base-file @var{filename}
@@ -2984,7 +2993,7 @@ Specifies the name of the export file to
 
 @item -z @var{filename}
 @itemx --output-def @var{filename}
-Specifies the name of the .def file to be created by dlltool.
+Specifies the name of the @file{.def} file to be created by dlltool.
 
 @item -l @var{filename}
 @itemx --output-lib @var{filename}
@@ -2998,7 +3007,7 @@ option.  You may add to the list of symb
 @option{--exclude-symbols} option.
 
 @item --no-export-all-symbols
-Only export symbols explicitly listed in an input .def file or in
+Only export symbols explicitly listed in an input @file{.def} file or in
 @samp{.drectve} sections in the input object files.  This is the default
 behaviour.  The @samp{.drectve} sections are created by @samp{dllexport}
 attributes in the source code.
@@ -3034,10 +3043,10 @@ double quotes.
 
 @item -D @var{name}
 @itemx --dll-name @var{name}
-Specifies the name to be stored in the .def file as the name of the DLL
-when the @option{-e} option is used.  If this option is not present, then
-the filename given to the @option{-e} option will be used as the name of
-the DLL.
+Specifies the name to be stored in the @file{.def} file as the name of
+the DLL when the @option{-e} option is used.  If this option is not
+present, then the filename given to the @option{-e} option will be
+used as the name of the DLL.
 
 @item -m @var{machine}
 @itemx -machine @var{machine}
@@ -3125,9 +3134,60 @@ Displays dlltool's version number and th
 
 @c man end
 
+@menu
+* def file format::             The format of the dlltool @file{.def} file
+@end menu
+
+@node def file format
+@section The format of the @command{dlltool} @file{.def} file
+
+A @file{.def} file contains any number of the following commands:
+
+@table @asis
+
+@item @code{NAME} @var{name} @code{[ ,} @var{base} @code{]}
+The result is going to be named @var{name}@code{.exe}.
+
+@item @code{LIBRARY} @var{name} @code{[ ,} @var{base} @code{]}
+The result is going to be named @var{name}@code{.dll}.
+
+@item @code{EXPORTS ( ( (} @var{name1} @code{[ = } @var{name2} @code{] ) | ( } @var{name1} @code{=} @var{module-name} @code{.} @var{external-name} @code{) )}
+@item @code{[} @var{integer} @code{] [ NONAME ] [ CONSTANT ] [ DATA ] [ PRIVATE ] ) *}
+Declares @var{name1} as an exported symbol from the DLL, with optional
+ordinal number @var{integer}, or declares @var{name1} as an alias
+(forward) of the function @var{external-name} in the DLL
+@var{module-name}.
+
+@item @code{IMPORTS ( (} @var{internal-name} @code{=} @var{module-name} @code{.} @var{integer} @code{) | [} @var{internal-name} @code{= ]} @var{module-name} @code{.} @var{external-name} @code{) ) *}
+Declares that @var{external-name} or the exported function whose
+ordinal number is @var{integer} is to be imported from the file
+@var{module-name}.  If @var{internal-name} is specified then this is
+the name that the imported function will be referred to in the body of
+the DLL.
+
+@item @code{DESCRIPTION} @var{string}
+Puts @var{string} into the output @file{.exp} file in the
+@code{.rdata} section.
+
+@item @code{STACKSIZE} @var{number-reserve} @code{[, } @var{number-commit} @code{]}
+@item @code{HEAPSIZE} @var{number-reserve} @code{[, } @var{number-commit} @code{]}
+Generates @code{--stack} or @code{--heap}
+@var{number-reserve},@var{number-commit} in the output @code{.drectve}
+section.  The linker will see this and act upon it.
+
+@item @code{CODE} @var{attr} @code{+}
+@item @code{DATA} @var{attr} @code{+}
+@item @code{SECTIONS (} @var{section-name} @var{attr}@code{ + ) *}
+Generates @code{--attr} @var{section-name} @var{attr} in the output
+@code{.drectve} section, where @var{attr} is one of @code{READ},
+@code{WRITE}, @code{EXECUTE} or @code{SHARED}.  The linker will see
+this and act upon it.
+
+@end table
+
 @ignore
 @c man begin SEEALSO dlltool
-the Info entries for @file{binutils}.
+The Info pages for @file{binutils}.
 @c man end
 @end ignore

Attachment: signature.asc
Description: Digital signature