Merge commit 'upstream/2.20'

[msp430-binutils.git] / binutils / doc / dlltool.1

diff --git a/binutils/doc/dlltool.1 b/binutils/doc/dlltool.1
index ebe04b199a043fbce0a1accacfa617801e88dac9..5d9dd2752b05ab23a680989a3163e7d5fb50d009 100644 (file)
--- a/binutils/doc/dlltool.1
+++ b/binutils/doc/dlltool.1
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
+.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)

 .\"
 .\" Standard preamble:
 .\" ========================================================================
 .\"
 .\" Standard preamble:
 .\" ========================================================================


@@ -48,21 +48,25 @@
 .    ds R" ''
 'br\}
 .\"
 .    ds R" ''
 'br\}
 .\"

+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"

 .\" If the F register is turned on, we'll generate index entries on stderr for
 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
 .\" entries marked with X<> in POD.  Of course, you'll have to process the
 .\" output yourself in some meaningful fashion.
 .\" If the F register is turned on, we'll generate index entries on stderr for
 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
 .\" entries marked with X<> in POD.  Of course, you'll have to process the
 .\" output yourself in some meaningful fashion.

-.if \nF \{\
+.ie \nF \{\

 .    de IX
 .    tm Index:\\$1\t\\n%\t"\\$2"
 ..
 .    nr % 0
 .    rr F
 .\}
 .    de IX
 .    tm Index:\\$1\t\\n%\t"\\$2"
 ..
 .    nr % 0
 .    rr F
 .\}

-.\"
-.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.hy 0
+.el \{\
+.    de IX
+..
+.\}

 .\"
 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
 .\"
 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.


@@ -128,7 +132,11 @@
 .\" ========================================================================
 .\"
 .IX Title "DLLTOOL 1"
 .\" ========================================================================
 .\"
 .IX Title "DLLTOOL 1"

-.TH DLLTOOL 1 "2007-08-06" "binutils-2.17.90" "GNU Development Tools"
+.TH DLLTOOL 1 "2009-10-16" "binutils-2.20" "GNU Development Tools"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh

 .SH "NAME"
 dlltool \- Create files needed to build and use DLLs.
 .SH "SYNOPSIS"
 .SH "NAME"
 dlltool \- Create files needed to build and use DLLs.
 .SH "SYNOPSIS"


@@ -138,6 +146,7 @@ dlltool [\fB\-d\fR|\fB\-\-input\-def\fR \fIdef-file-name\fR]
         [\fB\-e\fR|\fB\-\-output\-exp\fR \fIexports-file-name\fR]
         [\fB\-z\fR|\fB\-\-output\-def\fR \fIdef-file-name\fR]
         [\fB\-l\fR|\fB\-\-output\-lib\fR \fIlibrary-file-name\fR]
         [\fB\-e\fR|\fB\-\-output\-exp\fR \fIexports-file-name\fR]
         [\fB\-z\fR|\fB\-\-output\-def\fR \fIdef-file-name\fR]
         [\fB\-l\fR|\fB\-\-output\-lib\fR \fIlibrary-file-name\fR]

+        [\fB\-y\fR|\fB\-\-output\-delaylib\fR \fIlibrary-file-name\fR]

         [\fB\-\-export\-all\-symbols\fR] [\fB\-\-no\-export\-all\-symbols\fR]
         [\fB\-\-exclude\-symbols\fR \fIlist\fR]
         [\fB\-\-no\-default\-excludes\fR]
         [\fB\-\-export\-all\-symbols\fR] [\fB\-\-no\-export\-all\-symbols\fR]
         [\fB\-\-exclude\-symbols\fR \fIlist\fR]
         [\fB\-\-no\-default\-excludes\fR]


@@ -147,7 +156,10 @@ dlltool [\fB\-d\fR|\fB\-\-input\-def\fR \fIdef-file-name\fR]
         [\fB\-U\fR|\fB\-\-add\-underscore\fR] [\fB\-\-add\-stdcall\-underscore\fR]
         [\fB\-k\fR|\fB\-\-kill\-at\fR] [\fB\-A\fR|\fB\-\-add\-stdcall\-alias\fR]
         [\fB\-p\fR|\fB\-\-ext\-prefix\-alias\fR \fIprefix\fR]
         [\fB\-U\fR|\fB\-\-add\-underscore\fR] [\fB\-\-add\-stdcall\-underscore\fR]
         [\fB\-k\fR|\fB\-\-kill\-at\fR] [\fB\-A\fR|\fB\-\-add\-stdcall\-alias\fR]
         [\fB\-p\fR|\fB\-\-ext\-prefix\-alias\fR \fIprefix\fR]

-        [\fB\-x\fR|\fB\-\-no\-idata4\fR] [\fB\-c\fR|\fB\-\-no\-idata5\fR] [\fB\-i\fR|\fB\-\-interwork\fR]
+        [\fB\-x\fR|\fB\-\-no\-idata4\fR] [\fB\-c\fR|\fB\-\-no\-idata5\fR]
+        [\fB\-\-use\-nul\-prefixed\-import\-tables\fR]
+        [\fB\-I\fR|\fB\-\-identify\fR \fIlibrary-file-name\fR] [\fB\-\-identify\-strict\fR]
+        [\fB\-i\fR|\fB\-\-interwork\fR]

         [\fB\-n\fR|\fB\-\-nodelete\fR] [\fB\-t\fR|\fB\-\-temp\-prefix\fR \fIprefix\fR]
         [\fB\-v\fR|\fB\-\-verbose\fR]
         [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR]
         [\fB\-n\fR|\fB\-\-nodelete\fR] [\fB\-t\fR|\fB\-\-temp\-prefix\fR \fIprefix\fR]
         [\fB\-v\fR|\fB\-\-verbose\fR]
         [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR]


@@ -183,9 +195,7 @@ section of the object file.  This can be done in C by using the
 .Vb 2
 \&          asm (".section .drectve");
 \&          asm (".ascii \e"\-export:my_func\e"");
 .Vb 2
 \&          asm (".section .drectve");
 \&          asm (".ascii \e"\-export:my_func\e"");

-.Ve
-.PP
-.Vb 1
+\&        

 \&          int my_func (void) { ... }
 .Ve
 .PP
 \&          int my_func (void) { ... }
 .Ve
 .PP


@@ -196,9 +206,16 @@ binary file and it can be created by giving the \fB\-e\fR option to
 \&\fBdlltool\fR when it is creating or reading in a \fI.def\fR file.
 .PP
 The third file needed for \s-1DLL\s0 creation is the library file that programs
 \&\fBdlltool\fR when it is creating or reading in a \fI.def\fR file.
 .PP
 The third file needed for \s-1DLL\s0 creation is the library file that programs

-will link with in order to access the functions in the \s-1DLL\s0.  This file
-can be created by giving the \fB\-l\fR option to dlltool when it
-is creating or reading in a \fI.def\fR file.
+will link with in order to access the functions in the \s-1DLL\s0 (an `import
+library').  This file can be created by giving the \fB\-l\fR option to
+dlltool when it is creating or reading in a \fI.def\fR file.
+.PP
+If the \fB\-y\fR option is specified, dlltool generates a delay-import
+library that can be used instead of the normal import library to allow
+a program to link to the dll only as soon as an imported function is
+called for the first time. The resulting executable will need to be
+linked to the static delayimp library containing _\|\fI_delayLoadHelper2()\fR,
+which in turn will import LoadLibraryA and GetProcAddress from kernel32.

 .PP
 \&\fBdlltool\fR builds the library file by hand, but it builds the
 exports file by creating temporary files containing assembler statements
 .PP
 \&\fBdlltool\fR builds the library file by hand, but it builds the
 exports file by creating temporary files containing assembler statements


@@ -220,6 +237,10 @@ that uses that \s-1DLL:\s0
 \&          gcc dll.o exports.o \-o dll.dll
 \&          gcc program.o dll.lib \-o program
 .Ve
 \&          gcc dll.o exports.o \-o dll.dll
 \&          gcc program.o dll.lib \-o program
 .Ve

+.PP
+\&\fBdlltool\fR may also be used to query an existing import library
+to determine the name of the \s-1DLL\s0 to which it is associated.  See the 
+description of the \fB\-I\fR or \fB\-\-identify\fR option.

 .SH "OPTIONS"
 .IX Header "OPTIONS"
 The command line options have the following meanings:
 .SH "OPTIONS"
 .IX Header "OPTIONS"
 The command line options have the following meanings:


@@ -260,6 +281,13 @@ Specifies the name of the \fI.def\fR file to be created by dlltool.
 .IX Item "--output-lib filename"
 .PD
 Specifies the name of the library file to be created by dlltool.
 .IX Item "--output-lib filename"
 .PD
 Specifies the name of the library file to be created by dlltool.

+.IP "\fB\-y\fR \fIfilename\fR" 4
+.IX Item "-y filename"
+.PD 0
+.IP "\fB\-\-output\-delaylib\fR \fIfilename\fR" 4
+.IX Item "--output-delaylib filename"
+.PD
+Specifies the name of the delay-import library file to be created by dlltool.

 .IP "\fB\-\-export\-all\-symbols\fR" 4
 .IX Item "--export-all-symbols"
 Treat all global and weak defined symbols found in the input object
 .IP "\fB\-\-export\-all\-symbols\fR" 4
 .IX Item "--export-all-symbols"
 Treat all global and weak defined symbols found in the input object


@@ -391,6 +419,12 @@ external and import symbols with no leading underscore.
 Specifies that when \fBdlltool\fR is creating the exports and library
 files it should omit the \f(CW\*(C`.idata4\*(C'\fR section.  This is for compatibility
 with certain operating systems.
 Specifies that when \fBdlltool\fR is creating the exports and library
 files it should omit the \f(CW\*(C`.idata4\*(C'\fR section.  This is for compatibility
 with certain operating systems.

+.IP "\fB\-\-use\-nul\-prefixed\-import\-tables\fR" 4
+.IX Item "--use-nul-prefixed-import-tables"
+Specifies that when \fBdlltool\fR is creating the exports and library
+files it should prefix the \f(CW\*(C`.idata4\*(C'\fR and \f(CW\*(C`.idata5\*(C'\fR by zero an
+element. This emulates old gnu import library generation of
+\&\f(CW\*(C`dlltool\*(C'\fR. By default this option is turned off.

 .IP "\fB\-c\fR" 4
 .IX Item "-c"
 .PD 0
 .IP "\fB\-c\fR" 4
 .IX Item "-c"
 .PD 0


@@ -400,6 +434,23 @@ with certain operating systems.
 Specifies that when \fBdlltool\fR is creating the exports and library
 files it should omit the \f(CW\*(C`.idata5\*(C'\fR section.  This is for compatibility
 with certain operating systems.
 Specifies that when \fBdlltool\fR is creating the exports and library
 files it should omit the \f(CW\*(C`.idata5\*(C'\fR section.  This is for compatibility
 with certain operating systems.

+.IP "\fB\-I\fR \fIfilename\fR" 4
+.IX Item "-I filename"
+.PD 0
+.IP "\fB\-\-identify\fR \fIfilename\fR" 4
+.IX Item "--identify filename"
+.PD
+Specifies that \fBdlltool\fR should inspect the import library
+indicated by \fIfilename\fR and report, on \f(CW\*(C`stdout\*(C'\fR, the name(s)
+of the associated \s-1DLL\s0(s).  This can be performed in addition to any
+other operations indicated by the other options and arguments.
+\&\fBdlltool\fR fails if the import library does not exist or is not
+actually an import library. See also \fB\-\-identify\-strict\fR.
+.IP "\fB\-\-identify\-strict\fR" 4
+.IX Item "--identify-strict"
+Modifies the behavior of the \fB\-\-identify\fR option, such
+that an error is reported if \fIfilename\fR is associated with
+more than one \s-1DLL\s0.

 .IP "\fB\-i\fR" 4
 .IX Item "-i"
 .PD 0
 .IP "\fB\-i\fR" 4
 .IX Item "-i"
 .PD 0


@@ -454,7 +505,7 @@ Displays dlltool's version number and then exits.
 Read command-line options from \fIfile\fR.  The options read are
 inserted in place of the original @\fIfile\fR option.  If \fIfile\fR
 does not exist, or cannot be read, then the option will be treated
 Read command-line options from \fIfile\fR.  The options read are
 inserted in place of the original @\fIfile\fR option.  If \fIfile\fR
 does not exist, or cannot be read, then the option will be treated

-literally, and not removed.  
+literally, and not removed.

 .Sp
 Options in \fIfile\fR are separated by whitespace.  A whitespace
 character may be included in an option by surrounding the entire
 .Sp
 Options in \fIfile\fR are separated by whitespace.  A whitespace
 character may be included in an option by surrounding the entire


@@ -468,10 +519,10 @@ The Info pages for \fIbinutils\fR.
 .SH "COPYRIGHT"
 .IX Header "COPYRIGHT"
 Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
 .SH "COPYRIGHT"
 .IX Header "COPYRIGHT"
 Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,

-2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.

 .PP
 Permission is granted to copy, distribute and/or modify this document
 .PP
 Permission is granted to copy, distribute and/or modify this document

-under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.1
+under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3

 or any later version published by the Free Software Foundation;
 with no Invariant Sections, with no Front-Cover Texts, and with no
 Back-Cover Texts.  A copy of the license is included in the
 or any later version published by the Free Software Foundation;
 with no Invariant Sections, with no Front-Cover Texts, and with no
 Back-Cover Texts.  A copy of the license is included in the