Visual Studio, Microsoft Portable Executable and Common Object File Format Specification - 1

Visual Studio, Microsoft Portable Executable and Common Object File Format Specification

Revision 8.0 - May 16, 2006

Abstract

This specification describes the structure of executable (image) files and object files under the Microsoft® Windows® family of operating systems. These files are referred to as Portable Executable (PE) and Common Object File Format (COFF) files, respectively.

Note

This document is provided to aid in the development of tools and applications for Microsoft Windows but is not guaranteed to be a complete specification in all respects. Microsoft reserves the right to alter this document without notice.

This revision of the Microsoft Portable Executable and Common Object File Format Specification replaces Revision 6.0 of this specification.

The current version of this specification is maintained on the Web at:

Legal Notice

Microsoft Portable Executable and CommonObjectFileFormat Specification
Microsoft Corporation
Revision 8.0

Note: This specification is provided to aid in the development of certain development tools for the Microsoft Windows platform. However, Microsoft does not guarantee that it is a complete specification in all respects, and cannot guarantee the accuracy of any information presented after the date of publication. Microsoft reserves the right to alter this specification without notice.

Microsoft will grant a royalty-free license, under reasonable and non-discriminatory terms and conditions, to any Microsoft patent claims (if any exist) that Microsoft deems necessary for the limited purpose of implementing and complying with the required portions of this specification only in the software development tools known as compilers, linkers, and assemblers targeting Microsoft Windows.

Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this specification may be reproduced, stored in or introduced into a retrieval system, modified or used in a derivative work, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft.

Microsoft may have intellectual property rights covering subject matter in this specification. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this specification does not give you any license to any intellectual property rights, and no other rights are granted by implication, estoppel, or otherwise.

© 2006 Microsoft Corporation. All rights reserved.

This specification is provided “AS IS.” Microsoft makes no representations or warranties, express, implied, or statutory, as (1) to the information in this specification, including any warranties of merchantability, fitness for a particular purpose, non-infringement, or title; (2) that the contents of this specification are suitable for any purpose; nor (3) that the implementation of such contents will not infringe any third party patents, copyrights, trademarks, or other rights.

Microsoft will not be liable for any direct, indirect, special, incidental, or consequential damages arising out of or relating to any use or distribution of this specification.

Microsoft, MS-DOS, MSDN, Visual Studio, Visual C++, Win32, Windows, Windows NT, Windows Server, and Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. Other product and company names mentioned herein may be the trademarks of their respective owners.

The foregoing names and trademarks may not be used in any manner, including advertising or publicity pertaining to this specification or its contents without specific, written prior permission from the respective owners.

Contents

1. General Concepts

2. Overview

3. File Headers

3.1. MSDOS Stub (Image Only)

3.2. Signature (Image Only)

3.3. COFF File Header (Object and Image)

3.3.1. Machine Types

3.3.2. Characteristics

3.4. Optional Header (Image Only)

3.4.1. Optional Header Standard Fields (Image Only)

3.4.2. Optional Header Windows-Specific Fields (Image Only)

3.4.3. Optional Header Data Directories (Image Only)

4. Section Table (Section Headers)

4.1. Section Flags

4.2. Grouped Sections (Object Only)

5. Other Contents of the File

5.1. Section Data

5.2. COFF Relocations (Object Only)

5.2.1. Type Indicators

5.3. COFF Line Numbers (Deprecated)

5.4. COFF Symbol Table

5.4.1. Symbol Name Representation

5.4.2. Section Number Values

5.4.3. Type Representation

5.4.4. Storage Class

5.5. Auxiliary Symbol Records

5.5.1. Auxiliary Format 1: Function Definitions

5.5.2. Auxiliary Format 2: .bf and .ef Symbols

5.5.3. Auxiliary Format 3: Weak Externals

5.5.4. Auxiliary Format 4: Files

5.5.5. Auxiliary Format 5: Section Definitions

5.5.6. COMDAT Sections (Object Only)

5.5.7. CLR Token Definition (Object Only)

5.6. COFF String Table

5.7. The Attribute Certificate Table (Image Only)

5.7.1. Certificate Data

5.8. Delay-Load Import Tables (Image Only)

5.8.1. The Delay-Load Directory Table

5.8.2. Attributes

5.8.3. Name

5.8.4. Module Handle

5.8.5. Delay Import Address Table

5.8.6. Delay Import Name Table

5.8.7. Delay Bound Import Address Table and Time Stamp

5.8.8. Delay Unload Import Address Table

6. Special Sections

6.1. The .debug Section

6.1.1. Debug Directory (Image Only)

6.1.2. Debug Type

6.1.3. .debug$F (Object Only)

6.1.4. .debug$S (Object Only)

6.1.5. .debug$P (Object Only)

6.1.6. .debug$T (Object Only)

6.1.7. Linker Support for Microsoft Debug Information

6.2. The .drectve Section (Object Only)

6.3. The .edata Section (Image Only)

6.3.1. Export Directory Table

6.3.2. Export Address Table

6.3.3. Export Name Pointer Table

6.3.4. Export Ordinal Table

6.3.5. Export Name Table

6.4. The .idata Section

6.4.1. Import Directory Table

6.4.2. Import Lookup Table

6.4.3. Hint/Name Table

6.4.4. Import Address Table

6.5. The .pdata Section

6.6. The .reloc Section (Image Only)

6.6.1. Base Relocation Block

6.6.2. Base Relocation Types

6.7. The .tls Section

6.7.1. The TLS Directory

6.7.2. TLS Callback Functions

6.8. The Load Configuration Structure (Image Only)

6.8.1. Load Configuration Directory

6.8.2. Load Configuration Layout

6.9. The .rsrc Section

6.9.1. Resource Directory Table

6.9.2. Resource Directory Entries

6.9.3. Resource Directory String

6.9.4. Resource Data Entry

6.10. The .cormeta Section (Object Only)

6.11. The .sxdata Section

7. Archive (Library) File Format

7.1. Archive File Signature

7.2. Archive Member Headers

7.3. First Linker Member

7.4. Second Linker Member

7.5. Longnames Member

8. Import Library Format

8.1. Import Header

8.2. Import Type

8.3. Import Name Type

Appendix A: Calculating Authenticode PE Image Hash

A.1 What is an Authenticode PE Image Hash?

A.2 What is Covered in an Authenticode PE Image Hash?

References

1. General Concepts

This document specifies the structure of executable (image) files and object files under the Microsoft® Windows® family of operating systems. These files are referred to as Portable Executable (PE) and Common Object File Format (COFF) files, respectively. The name “Portable Executable” refers to the fact that the format is not architecturespecific.

Certain concepts that appear throughout this specification are described in the following table:

Name / Description
attribute certificate / A certificate that is used to associate verifiable statements with an image. A number of different verifiable statements can be associated with a file; one of the most useful ones is a statement by a software manufacturer that indicates what the message digest of the image is expected to be. A message digest is similar to a checksum except that it is extremely difficult to forge. Therefore, it is very difficult to modify a file to have the same message digest as the original file. The statement can be verified as being made by the manufacturer by using public or private key cryptography schemes. This document describes details about attribute certificates other than to allow for their insertion into image files.
date/time stamp / A stamp that is used for different purposes in several places in a PE or COFF file. The format of each stamp is the same as that used by the time functions in the C run-time library.
file pointer / The location of an item within the file itself, before being processed by the linker (in the case of object files) or the loader (in the case of image files). In other words, this is a position within the file as stored on disk.
linker / A reference to the linker that is provided with Microsoft Visual Studio®.
object file / A file that is given as input to the linker. The linker produces an image file, which in turn is used as input by the loader. The term “object file” does not necessarily imply any connection to object-oriented programming.
reserved, must be 0 / A description of a field that indicates that the value of the field must be zero for generators and consumers must ignore the field.
RVA / Relative virtual address. In an image file, the address of an item after it is loaded into memory, with the base address of the image file subtracted from it. The RVA of an item almost always differs from its position within the file on disk (file pointer).
In an object file, an RVA is less meaningful because memory locations are not assigned. In this case, an RVA would be an address within a section (described later in this table), to which a relocation is later applied during linking. For simplicity, a compiler should just set the first RVA in each section to zero.
section / The basic unit of code or data within a PE or COFF file. For example, all code in an object file can be combined within a single section or (depending on compiler behavior) each function can occupy its own section. With more sections, there is more file overhead, but the linker is able to link in code more selectively. A section is similar to a segment in Intel 8086 architecture. All the raw data in a section must be loaded contiguously. In addition, an image file can contain a number of sections, such as .tls or .reloc, which have special purposes.
VA / virtual address. Same as RVA, except that the base address of the image file is not subtracted. The address is called a “VA” because Windows creates a distinct VA space for each process, independent of physical memory. For almost all purposes, a VA should be considered just an address. A VA is not as predictable as an RVA because the loader might not load the image at its preferred location.

2. Overview

Figure 1 illustrates the Microsoft PE executable format:

MS-DOS 2.0 Compatible
EXE Header / Base of Image Header
unused
OEM Identifier
OEM Information
Offset to
PE Header / MSDOS 2.0 Section
(for MSDOS compatibility only)
MSDOS 2.0 Stub Program
and
Relocation Table
unused
PE Header
(aligned on 8-byte boundary)
Section Headers
Image Pages:
import info
export info
base relocations
resource info

Figure 1. Typical Portable EXE File Layout

Figure 2 illustrates the Microsoft COFF object-module format:

Microsoft COFF Header
Section Headers
Raw Data:
code
data
debug info
relocations

Figure 2. Typical COFF Object Module Layout

3. File Headers

The PE file header consists of a Microsoft MSDOS® stub, the PE signature, the COFF file header, and an optional header. A COFF object file header consists of a COFF file header and an optional header. In both cases, the file headers are followed immediately by section headers.

3.1.MSDOS Stub (Image Only)

The MSDOSstub is a valid application that runs under MSDOS. It is placed at the front of the EXE image. The linker places a default stub here, which prints out the message “This program cannot be run in DOS mode” when the image is run in MSDOS. The user can specify a different stub by using the /STUB linker option.

At location 0x3c, the stub has the file offset to the PE signature. This information enables Windows to properly execute the image file, even though it has anMSDOS stub. This file offset is placed at location 0x3c during linking.

3.2. Signature (Image Only)

After the MSDOS stub, at the file offset specified at offset 0x3c, is a 4-byte signature that identifies the file as a PE format image file. This signature is “PE\0\0” (the letters “P” and “E” followed by two null bytes).

3.3. COFF File Header (Object and Image)

At the beginning of an object file, or immediately after the signature of an image file, is a standard COFF file header in the following format. Note that the Windows loader limits the number of sections to 96.

Offset / Size / Field / Description
0 / 2 / Machine / The number that identifies the type of target machine. For more information, see section 3.3.1, “Machine Types.”
2 / 2 / NumberOfSections / The number of sections. This indicates the size of the section table, which immediately follows the headers.
4 / 4 / TimeDateStamp / The low 32bits of the number of seconds since 00:00 January 1, 1970 (a C run-time time_t value), that indicates when the file was created.
8 / 4 / PointerToSymbolTable / The file offset of the COFF symbol table, or zero if no COFF symbol table is present. This value should be zero for an image because COFF debugging information is deprecated.
12 / 4 / NumberOfSymbols / The number of entries in the symbol table. This data can be used to locate the string table, which immediately follows the symbol table. This value should be zero for an image because COFF debugging information is deprecated.
16 / 2 / SizeOfOptionalHeader / The size of the optional header, which is required for executable files but not for object files. This value should be zero for an object file. For a description of the header format, see section 3.4, “Optional Header (Image Only).”
18 / 2 / Characteristics / The flags that indicate the attributes of the file. For specific flag values, see section 3.3.2, “Characteristics.”

3.3.1. Machine Types

The Machine field has one of the following values that specifies its CPU type. An image file can be run only on the specified machine or on a system that emulates the specified machine.

Constant / Value / Description
IMAGE_FILE_MACHINE_UNKNOWN / 0x0 / The contents of this field are assumed to be applicable to any machine type
IMAGE_FILE_MACHINE_AM33 / 0x1d3 / Matsushita AM33
IMAGE_FILE_MACHINE_AMD64 / 0x8664 / x64
IMAGE_FILE_MACHINE_ARM / 0x1c0 / ARM little endian
IMAGE_FILE_MACHINE_EBC / 0xebc / EFI byte code
IMAGE_FILE_MACHINE_I386 / 0x14c / Intel 386 or later processors and compatible processors
IMAGE_FILE_MACHINE_IA64 / 0x200 / Intel Itaniumprocessor family
IMAGE_FILE_MACHINE_M32R / 0x9041 / Mitsubishi M32R little endian
IMAGE_FILE_MACHINE_MIPS16 / 0x266 / MIPS16
IMAGE_FILE_MACHINE_MIPSFPU / 0x366 / MIPS with FPU
IMAGE_FILE_MACHINE_MIPSFPU16 / 0x466 / MIPS16 with FPU
IMAGE_FILE_MACHINE_POWERPC / 0x1f0 / Power PC little endian
IMAGE_FILE_MACHINE_POWERPCFP / 0x1f1 / Power PC with floating point support
IMAGE_FILE_MACHINE_R4000 / 0x166 / MIPS little endian
IMAGE_FILE_MACHINE_SH3 / 0x1a2 / Hitachi SH3
IMAGE_FILE_MACHINE_SH3DSP / 0x1a3 / Hitachi SH3 DSP
IMAGE_FILE_MACHINE_SH4 / 0x1a6 / Hitachi SH4
IMAGE_FILE_MACHINE_SH5 / 0x1a8 / Hitachi SH5
IMAGE_FILE_MACHINE_THUMB / 0x1c2 / Thumb
IMAGE_FILE_MACHINE_WCEMIPSV2 / 0x169 / MIPS little-endian WCE v2

3.3.2. Characteristics

The Characteristics field contains flags that indicate attributes of the object or image file. The following flags are currently defined:

Flag / Value / Description
IMAGE_FILE_RELOCS_STRIPPED / 0x0001 / Image only, Windows CE, and Microsoft WindowsNT® and later. This indicates that the file does not contain base relocations and must therefore be loaded at its preferred base address. If the base address is not available, the loader reports an error. The default behavior of the linker is to strip base relocations from executable (EXE) files.
IMAGE_FILE_EXECUTABLE_IMAGE / 0x0002 / Image only. This indicates that the image file is valid and can be run. If this flag is not set, it indicates a linker error.
IMAGE_FILE_LINE_NUMS_STRIPPED / 0x0004 / COFF line numbers have been removed. This flag is deprecated and should be zero.
IMAGE_FILE_LOCAL_SYMS_STRIPPED / 0x0008 / COFF symbol table entries for local symbols have been removed. This flag is deprecated and should be zero.
IMAGE_FILE_AGGRESSIVE_WS_TRIM / 0x0010 / Obsolete. Aggressively trim working set. This flag is deprecated for Windows 2000 and later and must be zero.
IMAGE_FILE_LARGE_ADDRESS_AWARE / 0x0020 / Application can handle > 2GB addresses.
0x0040 / This flag is reserved for future use.
IMAGE_FILE_BYTES_REVERSED_LO / 0x0080 / Little endian: the least significant bit (LSB) precedes the most significant bit (MSB) in memory. This flag is deprecated and should be zero.
IMAGE_FILE_32BIT_MACHINE / 0x0100 / Machine is based on a 32-bit-word architecture.
IMAGE_FILE_DEBUG_STRIPPED / 0x0200 / Debugging information is removed from the image file.
IMAGE_FILE_REMOVABLE_RUN_FROM_SWAP / 0x0400 / If the image is on removable media, fully load it and copy it to the swap file.
IMAGE_FILE_NET_RUN_FROM_SWAP / 0x0800 / If the image is on network media, fully load it and copy it to the swap file.
IMAGE_FILE_SYSTEM / 0x1000 / The image file is a system file, not a user program.
IMAGE_FILE_DLL / 0x2000 / The image file is a dynamic-link library (DLL). Such files are considered executable files for almost all purposes, although they cannot be directly run.
IMAGE_FILE_UP_SYSTEM_ONLY / 0x4000 / The file should be run only on a uniprocessor machine.
IMAGE_FILE_BYTES_REVERSED_HI / 0x8000 / Big endian: the MSB precedes the LSB in memory. This flag is deprecated and should be zero.

3.4. Optional Header (Image Only)

Every image file has an optional header that provides information to the loader. This header is optional in the sense that some files (specifically, object files) do not have it. For image files, this header is required. An object file can have an optional header, but generally this header has no function in an object file except to increase its size.

Note that the size of the optional header is not fixed. The SizeOfOptionalHeader field in the COFF header must be used to validate that a probe into the file for a particular data directory does not go beyond SizeOfOptionalHeader. For more information, see section 3.3, “COFF File Header (Object and Image).”

The NumberOfRvaAndSizes field of the optional header should also be used to ensure that no probe for a particular data directory entry goes beyond the optional header. In addition, it is important to validate the optional header magic number for format compatibility.

The optional header magic number determines whether an image is a PE32 or PE32+ executable:

Magic number / PE format
0x10b / PE32
0x20b / PE32+

PE32+ images allow for a 64-bit address space while limiting the image size to 2gigabytes. Other PE32+ modifications are addressed in their respective sections.

The optional header itself has three major parts:

Offset (PE32/PE32+) / Size (PE32/PE32+) / Header part / Description
0 / 28/24 / Standard fields / Fields that are defined for all implementations of COFF, including UNIX.
28/24 / 68/88 / Windows-specific fields / Additional fields to support specific features of Windows (for example, subsystems).
96/112 / Variable / Data directories / Address/size pairs for special tables that are found in the image file and are used by the operating system (for example, the import table and the export table).

3.4.1.Optional Header Standard Fields (Image Only)

The first eight fields of the optional header are standard fields that are defined for every implementation of COFF. These fields contain general information that is useful for loading and running an executable file. They are unchanged for the PE32+ format.