Module pelite::pe64

PE32+ binary files.

Peering Inside the PE: A Tour of the Win32 Portable Executable File Format

Getting started

PE files exist in two states:

• When loaded in memory ready to be executed the sections are aligned at the requested section alignment in the optional header, typically 4 KiB.

  This alignment relates to the page size of virtual memory, since each section may want different memory protection settings.

• When stored on disk this may waste space so the sections are aligned at the specified file alignment in the optional header, typically 512 bytes.

  This alignment relates to the block size of the underlying file system storage.

This library provides a way to interact with either format through the Pe trait.

Executable files on disk

To load a file on disk, read it into memory using the filesystem API, read it using the memmap crate or get it done quickly and without any additional dependencies using the provided FileMap loader.

Take a byte slice of the entire file contents and construct it with PeFile::from_bytes.

Import the Pe trait to continue from here.

use std::path::Path;
use pelite::{FileMap, Result};
use pelite::pe64::{Pe, PeFile};

fn file_map<P: AsRef<Path> + ?Sized>(path: &P) -> Result<()> {
    let path = path.as_ref();
    if let Ok(map) = FileMap::open(path) {
        let file = PeFile::from_bytes(&map)?;

        // Access the file contents through the Pe trait
        let image_base = file.optional_header().ImageBase;
        println!("The preferred load address of {:?} is {}.", path, image_base);

        // See the respective modules to access other parts of the PE file.
    }
    Ok(())
}

Executable images in memory

To simulate the system loading and mapping images with virtual memory alignment use the ImageMap loader. Note however that this is only available on Windows targets as this maps the image using Windows file mapping facilities.

Take a byte slice of the entire image and construct it with PeView::from_bytes.

Import the Pe trait to continue from here.

If you don't know which to choose, go with PeFile.

use std::path::Path;
use pelite::{ImageMap, Result};
use pelite::pe64::{Pe, PeView};

fn image_map<P: AsRef<Path> + ?Sized>(path: &P) -> Result<()> {
    let path = path.as_ref();
    if let Ok(image) = ImageMap::open(path) {
        let view = PeView::from_bytes(&image)?;

        // Access the image contents through the Pe trait
        let image_size = view.optional_header().SizeOfImage;
        println!("The size of image in memory of {:?} is {}", path, image_size);

        // See the respective modules to access other parts of the PE image.
    }
    Ok(())
}

Advanced usage

When working with already loaded libraries in your own process there is the pelite::pe module alias which points to the correct module for your target. pelite::pe32 if compiled for 32-bit targets and pelite::pe64 for 64-bit targets.

Evidently this alias is only available on Windows targets.

Access the your own module with PeView::new to construct a view into your own image. This is mostly safe, but be cautious when using it to read from writable sections.

Access other modules in the process with PeView::module to construct a view into other images in the process. This is mostly safe, but be even more cautious when using it to read from writable sections since other libraries written in other languages such as C/C++ respect rust memory aliasing rules even less.

use std::path::Path;
use pelite::Result;
use pelite::pe::{Pe, PeView};

fn image_base() {
    let view = unsafe { PeView::new() };

    // Access the image contents through the Pe trait
    let image_size = view.optional_header().SizeOfImage;
    println!("The size of our image is {}", image_size);

    // See the respective modules to access other parts of the PE image.
}

Re-exports

pub use self::image::Va;

pub use self::image::Rva;

Modules

base_relocs	Base Relocations Directory.
debug	Debug Directory.
exception	Exception Directory.
exports	Export Directory.
headers	PE headers.
image	PE32+ image structures.
imports	Import Directory and the IAT.
load_config	Load Config Directory.
resources	Resource Directory.
scanner	Pattern Scanner.
security	Security Directory.
tls	TLS Directory.

Structs

PeFile	View into an unmapped PE file.
PeView	View into a mapped PE image.
Ptr	Typed virtual address.

Enums

Align

The specific alignment used by the view.

Traits

Pe