pelite\pe32/
mod.rs

1/*!
2PE32 binary files.
3
4[Peering Inside the PE: A Tour of the Win32 Portable Executable File Format](https://msdn.microsoft.com/en-us/library/ms809762.aspx)
5
6# Getting started
7
8PE files exist in two states:
9
10* When loaded in memory ready to be executed the sections are aligned at the requested section alignment in the optional header, typically 4 KiB.
11
12  This alignment relates to the page size of virtual memory, since each section may want different memory protection settings.
13
14* 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.
15
16  This alignment relates to the block size of the underlying file system storage.
17
18This library provides a way to interact with either format through the [`Pe`](trait.Pe.html) trait.
19
20## Executable files on disk
21
22To load a file on disk, read it into memory using the [filesystem API](https://doc.rust-lang.org/std/fs/),
23read it using the [`memmap` crate](https://crates.io/crates/memmap) or get it done quickly and without any
24additional dependencies using the provided [`FileMap`](../struct.FileMap.html) loader.
25
26Take a byte slice of the entire file contents and construct it with [`PeFile::from_bytes`](struct.PeFile.html#method.from_bytes).
27
28Import the [`Pe`](trait.Pe.html) trait to continue from here.
29
30```
31# #![allow(dead_code)]
32use std::path::Path;
33use pelite::{FileMap, Result};
34use pelite::pe32::{Pe, PeFile};
35
36fn file_map<P: AsRef<Path> + ?Sized>(path: &P) -> Result<()> {
37	let path = path.as_ref();
38	if let Ok(map) = FileMap::open(path) {
39		let file = PeFile::from_bytes(&map)?;
40
41		// Access the file contents through the Pe trait
42		let image_base = file.optional_header().ImageBase;
43		println!("The preferred load address of {:?} is {}.", path, image_base);
44
45		// See the respective modules to access other parts of the PE file.
46	}
47	Ok(())
48}
49```
50
51## Executable images in memory
52
53To simulate the system loading and mapping images with virtual memory alignment use the [`ImageMap`](../struct.ImageMap.html) loader.
54Note however that this is only available on Windows targets as this maps the image using Windows file mapping facilities.
55
56Take a byte slice of the entire image and construct it with [`PeView::from_bytes`](struct.PeView.html#method.from_bytes).
57
58Import the [`Pe`](trait.Pe.html) trait to continue from here.
59
60If you don't know which to choose, go with [`PeFile`](struct.PeFile.html).
61
62```
63# #[cfg(windows)] {
64# #![allow(dead_code)]
65use std::path::Path;
66use pelite::{ImageMap, Result};
67use pelite::pe32::{Pe, PeView};
68
69fn image_map<P: AsRef<Path> + ?Sized>(path: &P) -> Result<()> {
70	let path = path.as_ref();
71	if let Ok(image) = ImageMap::open(path) {
72		let view = PeView::from_bytes(&image)?;
73
74		// Access the image contents through the Pe trait
75		let image_size = view.optional_header().SizeOfImage;
76		println!("The size of image in memory of {:?} is {}", path, image_size);
77
78		// See the respective modules to access other parts of the PE image.
79	}
80	Ok(())
81}
82# }
83```
84
85# Advanced usage
86
87When 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.
88[`pelite::pe32`](../pe32/index.html) if compiled for 32-bit targets and [`pelite::pe64`](../pe64/index.html) for 64-bit targets.
89
90Evidently this alias is only available on Windows targets.
91
92Access the your own module with [`PeView::new`](struct.PeView.html#method.new) to construct a view into your own image.
93This is mostly safe, but be cautious when using it to read from writable sections.
94
95Access other modules in the process with [`PeView::module`](struct.PeView.html#method.module) to construct a view into other images in the process.
96This 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.
97
98```
99# #[cfg(windows)] {
100# #![allow(dead_code)]
101use std::path::Path;
102use pelite::Result;
103use pelite::pe::{Pe, PeView};
104
105fn image_base() {
106	let view = unsafe { PeView::new() };
107
108	// Access the image contents through the Pe trait
109	let image_size = view.optional_header().SizeOfImage;
110	println!("The size of our image is {}", image_size);
111
112	// See the respective modules to access other parts of the PE image.
113}
114# }
115```
116*/
117
118#[macro_use]
119mod macros;
120
121pub mod image;
122
123// I love Rust <3
124
125#[path = "../pe64/pe.rs"]
126mod pe;
127#[path = "../pe64/view.rs"]
128mod view;
129#[path = "../pe64/file.rs"]
130mod file;
131#[path = "../pe64/headers.rs"]
132pub mod headers;
133#[path = "../pe64/rich_structure.rs"]
134pub(crate) mod rich_structure;
135#[path = "../pe64/exports.rs"]
136pub mod exports;
137#[path = "../pe64/imports.rs"]
138pub mod imports;
139#[path = "../pe64/base_relocs.rs"]
140pub(crate) mod base_relocs;
141#[path = "../pe64/load_config.rs"]
142pub mod load_config;
143#[path = "../pe64/resources.rs"]
144pub mod resources;
145#[path = "../pe64/tls.rs"]
146pub mod tls;
147#[path = "../pe64/security.rs"]
148pub(crate) mod security;
149#[path = "../pe64/exception.rs"]
150pub mod exception;
151#[path = "../pe64/debug.rs"]
152pub mod debug;
153#[path = "../pe64/ptr.rs"]
154mod ptr;
155#[path = "../pe64/scanner.rs"]
156pub mod scanner;
157
158pub mod msvc;
159
160pub use self::image::{Va, Rva};
161pub use self::pe::{Align, Pe, PeObject};
162pub use self::view::{PeView};
163pub use self::file::{PeFile};
164pub use self::ptr::Ptr;
165
166#[cfg(feature = "unstable")]
167pub use self::pe::headers_mut;
pelite\pe32/mod.rs

pelite\pe32/
mod.rs
