Module Definition Files

Go Up to Technical Details About ILINK32 and ILINK64

You use module definition files with ILINK32. A module definition file is an ASCII text file that provides information to ILINK32 about the contents and system requirements of a Windows application. Use IMPDEF to create a module definition file.

The module definition file names the .EXE or .DLL, identifies the application type, lists imported and exported functions, describes the code section and data segment attributes, lets you specify attributes for additional code sections and data segments, specifies the size of the stack, and provides for the inclusion of a stub program.

CODE Statement

Defines the default attributes of code sections. Code sections can have any name, but must belong to section classes whose names end in CODE (such as CODE or MYCODE).

CODE [PRELOAD | LOADONCALL]
      [EXECUTEONLY | EXECUTEREAD]

• PRELOAD means code is loaded when the calling program is loaded.
• LOADONCALL (the default) means the code is loaded when called by the program.
• EXECUTEONLY means a code section can only be executed.
• EXECUTEREAD (the default) means the code section can be read and executed.
• FIXED (the default) means the section remains at a fixed memory location.
• MOVEABLE means the section can be moved.
• DISCARDABLE means the section can be discarded if it is no longer needed (this implies MOVEABLE).
• NONDISCARDABLE (the default) means the section cannot be discarded.

DATA Statement

Defines attributes of data segments:

DATA [NONE | SINGLE | MULTIPLE]
     [READONLY | READWRITE]
     [PRELOAD | LOADONCALL]
     [SHARED | NONSHARED]

• NONE means that there is no data section created. This option is available only for libraries.
• SINGLE (the default for .DLLs) means a single data section is created and shared by all processes.
• MULTIPLE (the default for .EXEs) means that a data section is created for each process.
• READONLY means the data section can be only read.
• READWRITE (the default) means the data section can be read and written to.
• PRELOAD means the data section is loaded when a module that uses it is first loaded.
• LOADONCALL (the default) means the data section is loaded when it is first accessed. (LOADONCALL is ignored for 32-bit applications.)
• SHARED means one copy of the data section is shared among all processes.
• NONSHARED (the default for programs .DLLs) means a copy of the data section is loaded for each process needing to use the data section.

DESCRIPTION Statement (optional)

Inserts text into the application module and is typically used to embed author, date, or copyright information:

DESCRIPTION 'Text'

Text is an ASCII string delimited with single quotation marks.

EXETYPE Statement

Defines the default executable file (.EXE) header type for applications. You can leave this section in for 32-bit applications for backward compatibility, but if you need to change the EXETYPE, see the NAME statement.

EXETYPE  [WINDOWAPI] | [WINDOWCOMPAT]

• WINDOWAPI is a Windows executable, and is equivalent to the ILINK32 option -aa.
• WINDOWCOMPAT is a Windows-compatible character-mode executable, and is equivalent to the ILINK32 option -ap.

EXPORTS Statement

Defines the names and attributes of functions to be exported. The EXPORTS keyword marks the beginning of the definitions. It can be followed by any number of export definitions, each on a separate line.

EXPORTS
   <ExportName> [<Ordinal>]
   [RESIDENTNAME] [<Parameter>]

• <ExportName> specifies an ASCII string that defines the symbol to be exported as follows:

<EntryName> [=<InternalName>]

<EntryName> is the name listed in the executable file's entry table and is externally visible.

<InternalName> is the name used within the application to refer to this entry.

• <Ordinal> defines the function's ordinal value as follows:

@<ordinal>

where <ordinal> is an integer value that specifies the function's ordinal value. When an application or DLL module calls a function exported from a DLL, the calling module can refer to the function by name or by ordinal value. It is faster to refer to the function by ordinal because string comparisons aren't required to locate the function. To use less memory, export a function by ordinal (from the point of view of that function's DLL) and import/call a function by ordinal (from the point of view of the calling module).

When a function is exported by ordinal, the name resides in the nonresident name table. When a function is exported by name, the name resides in the resident name table. The resident name table for a module is in memory whenever the module is loaded; the nonresident name table isn't.

• RESIDENTNAME specifies that the function's name must be resident at all times. This is useful only when exporting by ordinal (when the name wouldn't be resident by default).
• <Parameter> is an optional integer value that specifies the number of words the function expects to be passed as parameters.

HEAPSIZE Statement

Defines the number of bytes the application needs for its local heap. An application uses the local heap whenever it allocates local memory.

HEAPSIZE <Reserve>[, <Commit>]

• <Reserve> can be a decimal or hex value, the default of which is 1MB. To help with backward (16-bit) compatibility for 32-bit ports, the linker uses the default value of 1MB if you specify in the .DEF ile a reserve value less than 64K.
• <Commit> is a decimal or hex value. The commit size is optional, and, if not specified, defaults to 4K. The minimum commit size you can specify is 0. In addition, the specified or default commit size must always be smaller than or equal to the reserve size.

Reserved memory refers to the maximum amount of memory that can be allocated either in physical memory or in the paging file. In other words, reserved memory specifies the maximum possible heap size. The operating system guarantees that the specified amount of memory will be reserved and, if necessary, allocated.

The meaning of committed memory varies among operating systems. In Windows NT, committed memory refers to the amount of physical memory allocated for the heap at application load/initialization time. Committed memory causes space to be allocated either in physical memory or in the paging file. A higher commit value saves time when the application needs more heap space, but increases memory requirements and possible startup time.

You can override any heap reserve or commit size specified in the .DEF file with the -H or -Hc ILINK32 command-line options. -H lets you specify a heap reserve size less than the 64K minimum allowed in the .DEF file.

IMPORTS Statement

Defines the names and attributes of functions to be imported from DLLs. The IMPORTS keyword marks the beginning of the definitions followed by any number of import definitions, each on a separate line.

IMPORTS
[<InternalName>=]<ModuleName>.<Entry>

• <InternalName> is an ASCII string that specifies the unique name the application uses to call the function.
• <ModuleName> specifies one or more uppercase ASCII characters that define the name of the executable module containing the function. The module name must match the name of the executable file. For example, the file SAMPLE.DLL has the module name SAMPLE.
• <Entry> specifies the function to be imported--either an ASCII string that names the function or an integer that gives the function's ordinal value.

Instead of listing imported DLL functions in the IMPORTS statement, you can either specify an import library for the DLL in the ILINK32 command-line interface, or include the import library for the DLL in the Projects Window in RAD Studio.

You must use either __declspec(dllimport) or __import to import any function, class, or data you want imported. The preferred method is to use __declspec(dllimport).

The IMPORTS keyword can also be applied to (global) variables, as follows:

[ in the dll source file (dll.cpp) ] int sample = 100;

[ dll.def ]     EXPORTS       _sample

[ in application source file (app.cpp) ]
int _declspec(dllimport) sample;

[ app.def ]
  IMPORTS
    dll._sample

LIBRARY Statement

Defines the name of a DLL module. A module definition file can contain either a LIBRARY statement to indicate a .DLL, or a NAME statement to indicate a .EXE. A library's module name must match the name of the executable file. For example, the library MYLIB.DLL has the module name MYLIB.

LIBRARY <LibrarName> [INITGLOBAL | INITINSTANCE]

• <LibraryName> (optional) is an ASCII string that defines the name of the library module. If you don't include a LibraryName, ILINK32 uses the file name with the extension removed. If the module definition file includes neither a NAME nor a LIBRARY statement, ILINK32 assumes a NAME statement without a ModuleName parameter.
• INITGLOBAL means the library initialization routine is called.
• INITINSTANCE means the library initialization routine is called each time a new process uses the library.

NAME Statement

Is the name of the application's executable module. The module name identifies the module when exporting functions. NAME must appear before EXETYPE. If NAME and EXETYPE don't specify the same target type, the linker uses the type listed with NAME.

NAME <ModuleName> [WINDOWSAPI] | [WINDOWCOMPAT]

• <ModuleName> (optional) specifies one or more uppercase ASCII characters that name the executable module. The name must match the name of the executable file. For example, an application with the executable file SAMPLE.EXE has the module name SAMPLE.

If <ModuleName> is missing, ILINK32 assumes that the module name matches the file name of the executable file. For example, if you do not specify a module name and the executable file is named MYAPP.EXE, ILINK32 assumes that the module name is MYAPP. If the module definition file includes neither a NAME nor a LIBRARY statement, ILINK32 assumes a NAME statement without a <ModuleName> parameter.

• WINDOWSAPI specifies a Windows executable, and is equivalent to the ILINK32 option -aa.
• WINDOWCOMPAT specifies a Windows-compatible character-mode executable, and is equivalent to the ILINK32 option -ap.

SECTIONS Statement

Lets you set attributes for one or more sections in the image file. You can use this statement to override the default attributes for each different type of section.

SECTIONS<section_name> [CLASS '<ClassName>'] <attributes>

• SECTIONS marks the beginning of a list of section definitions.
• After the SECTIONS keyword, each section definition must be listed on a separate line. Note that the SECTIONS keyword can be on the same line as the first definition or on a preceding line. In addition, the .DEF file can contain one or more SECTIONS statements. The SEGMENTS keyword is supported as a synonym for SECTIONS.
• <ClassName> is case-sensitive. The CLASS keyword is supported for compatibility, but is ignored.
• <Attributes> is one or more of the following: EXECUTE, READ, SHARED, and WRITE.

SEGMENTS Statement

Defines the attributes of additional code and data sections. The SEGMENTS keyword is supported as a synonym for SECTIONS. The syntax is:

SEGMENTS
   <SegmentName> [CLASS '<ClassName>']
        [<MinAlloc>]
        [SHARED | NONSHARED]
        [PRELOAD | LOADONCALL]

• <SegmentName> is a character string that names the new segment. It can be any name, including the standard segment names _TEXT and _DATA, which represent the standard code and data segments.
• <ClassName> (optional) is the class name of the specified segment. If no class name is specified, ILINK32 uses the class name CODE.
• <MinAlloc> (optional) is an integer that specifies the minimum allocation size for the segment. ILINK32 ignores this value.
• SHARED means one copy of the segment is shared among all processes.
• NONSHARED (the default for .EXEs and .DLLs) means a copy of the segment is loaded for each process needing to use the data segment.
• PRELOAD means that the segment is loaded immediately.
• LOADONCALL means that the segment is loaded when it is accessed or called (this is ignored by ILINK32). The Resource Compiler may override the LOADONCALL option and preload segments instead.

STACKSIZE Statement

Defines the number of bytes the application needs for its local stack. An application uses the local stack whenever it makes function calls.

STACKSIZE <Reserve>[, <Commit>]

• <Reserve> can be a decimal or hex value, the default of which is 1MB. To help with backward (16-bit) compatibility, the linker uses the default value of 1MB if you specify in the .DEF file a reserve value less than 64K.
• <Commit> is a decimal or hex value. The commit size is optional, and, if not specified, defaults to 8K. The minimum commit size you can specify is 4K. In addition, the specified or default commit size must always be smaller or equal to the reserve size.

Reserved memory refers to the maximum amount of memory that can be allocated either in physical memory or in the paging file. In other words, reserved memory specifies the maximum possible stack size.

The operating system guarantees that the specified amount of memory will be reserved and, if necessary, allocated.

The meaning of committed memory varies among operating systems. In Windows NT, committed memory refers to the amount of physical memory allocated for the stack at application load/initialization time. Committed memory causes space to be allocated either in physical memory or in the paging file. A higher commit value saves time when the application needs more stack space, but increases memory requirements and possible startup time.

You can override any stack reserve or commit size specified in the .DEF file with the ILINK32 -S or -Sc command-line options. -S lets you specify a stack reserve size less than the 64K minimum allowed in the .DEF file.

Note: Do not use the STACKSIZE statement when compiling .DLLs.

STUB Statement

Appends a DOS executable file specified by <FileName> to the beginning of the module. The executable stub displays a warning message and terminates if the user attempts to run the executable stub in the wrong environment (running a Windows application under DOS, for example).

STUB '<FileName>'

• <FileName> is the name of the DOS executable file to be appended to the module. The name must have the DOS file name format. If the file named by FileName is not in the current directory, ILINK32 searches for the file in the directories specified by the PATH environment variable.

C++Builder adds a built-in stub to the beginning of a Windows application unless a different stub is specified with the STUB statement. You should not use the STUB statement to include WINSTUB.EXE, because the linker does this automatically.

SUBSYSTEM Statement

Lets you specify the Windows subsystem and subsystem version number for the application being linked.

SUBSYSTEM [<subsystem>,]<subsystemID>

• <Subsystem> (optional) can be any one of the following values: WINDOWS, WINDOWAPI, WINDOWCOMPAT. If you do not specify a <Subsystem>, the linker defaults to a WINDOWS subsystem.
• <SubsystemID> must use the format d.d, where d is a decimal number. For example, if you want to specify Windows 4.0, you could use either one of the following two SUBSYSTEM statements:

SUBSYSTEM 4.0

SUBSYSTEM WINDOWS 4.0

You can override any SUBSYSTEM statement in a .DEF file using the -a and -V ILINK32 command-line options.

See Also

• Using ILINK32 and ILINK64 on the Command Line
• IMPDEF.EXE, the Module Definition Manager