microseh 0.1.1

Structured Exception Handling (SEH) for Rust
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

<h1 align="center">MicroSEH ❌</h1>

<div align="center">
  <a href="https://crates.io/crates/microseh"><img src="https://img.shields.io/crates/v/microseh.svg"/></a>
  <a href="https://docs.rs/microseh"><img src="https://docs.rs/microseh/badge.svg"/></a>
  <a href="https://github.com/sonodima/microseh/actions?workflow=CI">
    <img src="https://github.com/sonodima/microseh/workflows/CI/badge.svg"/>
  </a>
  <a href="https://crates.io/crates/microseh"><img src="https://img.shields.io/crates/d/microseh?color=pink"/></a>
  <img src="https://img.shields.io/badge/license-MIT-blue.svg"/>
</div>

<br>

> MicroSEH is a small library for Structured Exception Handling (SEH) in Rust that can catch
> and handle hardware exceptions.

> Isn't Rust supposed to be safe?<br>
> Well, yes, but as soon as you enter the unsafe world, you can do anything you want.
>
> Having a way to handle hardware exceptions is useful, especially when you're interfacing with other C binaries.<br>
> There may be some cases where a hardware exception is not a fatal error, and can be resolved by the program.
>
> The most basic application of such concept is to catch a segmentation fault when accessing an invalid pointer.

## Implementation

It turns out that implementing SEH in safe Rust may not look that straightforward at first glance (as seen
in [this post](https://engineering.zeroitlab.com/2022/03/13/rust-seh))

This library uses a different, simpler approach, which is to use a `C` stub that calls back into Rust,
wrapping the call in a `__try __except` block.

## Usage

Add this to your `Cargo.toml`:

```toml
[dependencies]
microseh = "0.1"
```

> <b>Example:</b> De-referencing a null pointer without crashing the program.

```rust
fn guarded() -> Result<(), Box<dyn Error>> {
    microseh::try_seh(|| {
        *std::ptr::null::<i32>();
    })?;
}
```

## Portability

SEH is a Microsoft extension to the C language, so it's only available on Windows with MSVC.