pelite\pe64/
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::pe64::{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::pe64::{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
123mod pe;
124mod view;
125mod file;
126pub mod headers;
127pub(crate) mod rich_structure;
128pub mod exports;
129pub mod imports;
130pub(crate) mod base_relocs;
131pub mod load_config;
132pub mod resources;
133pub mod tls;
134pub(crate) mod security;
135pub mod exception;
136pub mod debug;
137mod ptr;
138pub mod scanner;
139pub mod msvc;
140
141pub use self::image::{Va, Rva};
142pub use self::pe::{Align, Pe, PeObject};
143pub use self::view::{PeView};
144pub use self::file::{PeFile};
145pub use self::ptr::Ptr;
146
147#[cfg(feature = "unstable")]
148pub use self::pe::headers_mut;
pelite\pe64/mod.rs

pelite\pe64/
mod.rs
