### Documenting a Function with an Example - Rust

Source: https://docs.rs/findshlibs/latest/scrape-examples-help.html

Shows how a public function in a library and an example calling that function are used by Rustdoc to include the example in the function's documentation.

```rust
// src/lib.rs
pub fn a_func() {}
```

```rust
// examples/ex.rs
fn main() {
  a_crate::a_func();
}
```

--------------------------------

### Example Usage of findshlibs

Source: https://docs.rs/findshlibs/latest/index.html

This example demonstrates how to iterate over all loaded shared libraries in a process and print their names and segment addresses.

```APIDOC
## `findshlibs` Crate Example

### Description
This example program iterates through all shared libraries loaded in the current process and prints their names along with the virtual memory addresses of their segments.

### Method
`TargetSharedLibrary::each`

### Endpoint
N/A (Rust library function)

### Parameters
None

### Request Example
```rust
extern crate findshlibs;
use findshlibs::{Segment, SharedLibrary, TargetSharedLibrary};

fn main() {
    TargetSharedLibrary::each(|shlib| {
        println!("{}", shlib.name().to_string_lossy());

        for seg in shlib.segments() {
            println!("    {}: segment {}",
                     seg.actual_virtual_memory_address(shlib),
                     seg.name());
        }
    });
}
```

### Response
#### Success Response
Prints the name and segment addresses of each loaded shared library to standard output.

#### Response Example
```
libc.so.6
    0x7f1234567890: segment .text
    0x7f1234567891: segment .data
libpthread.so.0
    0x7f1234567892: segment .text
    0x7f1234567893: segment .data
```
```

--------------------------------

### Iterating Through Shared Libraries

Source: https://docs.rs/findshlibs/latest/findshlibs/index.html

This example demonstrates how to use the `SharedLibrary::each` method to iterate over all loaded shared libraries and print their names and segment information.

```APIDOC
## `findshlibs` Example

Find the set of shared libraries currently loaded in this process with a cross platform API.
The API entry point is the `TargetSharedLibrary` type and its `SharedLibrary::each` trait method implementation.

### Example
Here is an example program that prints out each shared library that is loaded in the process and the addresses where each of its segments are mapped into memory.
```rust
extern crate findshlibs;
use findshlibs::{Segment, SharedLibrary, TargetSharedLibrary};

fn main() {
    TargetSharedLibrary::each(|shlib| {
        println!("{}", shlib.name().to_string_lossy());

        for seg in shlib.segments() {
            println!("    {}: segment {}",
                     seg.actual_virtual_memory_address(shlib),
                     seg.name());
        }
    });
}
```
```

--------------------------------

### Iterating Through Shared Libraries

Source: https://docs.rs/findshlibs

This example demonstrates how to use the `TargetSharedLibrary::each` method to iterate over all shared libraries loaded in the current process and print their names and segment information.

```APIDOC
## `findshlibs` Example

This example program prints out each shared library that is loaded in the process and the addresses where each of its segments are mapped into memory.

### Code
```rust
extern crate findshlibs;
use findshlibs::{Segment, SharedLibrary, TargetSharedLibrary};

fn main() {
    TargetSharedLibrary::each(|shlib| {
        println!("{}", shlib.name().to_string_lossy());

        for seg in shlib.segments() {
            println!("    {}: segment {}",
                     seg.actual_virtual_memory_address(shlib),
                     seg.name());
        }
    });
}
```

### Usage
This code snippet can be included in your Rust project to inspect loaded shared libraries at runtime.
```

--------------------------------

### List Segments and Their Addresses

Source: https://docs.rs/findshlibs/latest/findshlibs/trait.Segment.html

Iterates through all shared libraries on the system and prints the name and actual virtual memory address of each segment within them. This example demonstrates how to use the `each` method on `TargetSharedLibrary` and iterate over segments using `shlib.segments()`.

```rust
4fn main() {
5    TargetSharedLibrary::each(|shlib| {
6        println!("{}", shlib.name().to_string_lossy());
7
8        for seg in shlib.segments() {
9            println!(
10                "    {}: segment {}",
11                seg.actual_virtual_memory_address(shlib),
12                seg.name()
13            );
14        }
15    });
16}
```

--------------------------------

### Get Actual Load Address

Source: https://docs.rs/findshlibs/latest/findshlibs/linux/struct.SharedLibrary.html

Returns the actual address where the shared library is loaded into virtual memory.

```rust
fn actual_load_addr(&self) -> Avma
```

--------------------------------

### Iterate and Print Shared Libraries and Segments

Source: https://docs.rs/findshlibs/latest/findshlibs/index.html

Iterates through all shared libraries loaded in the process and prints their names and the virtual memory addresses of their mapped segments. This example demonstrates the primary API usage for inspecting loaded libraries.

```rust
extern crate findshlibs;
use findshlibs::{Segment, SharedLibrary, TargetSharedLibrary};

fn main() {
    TargetSharedLibrary::each(|shlib| {
        println!("{}", shlib.name().to_string_lossy());

        for seg in shlib.segments() {
            println!("    {}: segment {}",
                     seg.actual_virtual_memory_address(shlib),
                     seg.name());
        }
    });
}
```

--------------------------------

### Get Shared Library Name

Source: https://docs.rs/findshlibs/latest/findshlibs/linux/struct.SharedLibrary.html

Retrieves the name of the shared library as an OsStr.

```rust
fn name(&self) -> &OsStr
```

--------------------------------

### Get Stated Load Address

Source: https://docs.rs/findshlibs/latest/findshlibs/linux/struct.SharedLibrary.html

Returns the preferred address where the shared library intends to be loaded into virtual memory.

```rust
fn stated_load_addr(&self) -> Svma
```

--------------------------------

### Implement ToString for T

Source: https://docs.rs/findshlibs/latest/findshlibs/struct.Avma.html

Enables converting a type T into a String, provided that T implements the Display trait. This is a convenient way to get string representations of values.

```rust
impl<T> ToString for T
where T: Display + ?Sized,
```

--------------------------------

### Get Debug File Name

Source: https://docs.rs/findshlibs/latest/findshlibs/linux/struct.SharedLibrary.html

Retrieves the name of the associated debug file for the shared library, if one exists. Returns an Option<&OsStr>.

```rust
fn debug_name(&self) -> Option<&OsStr>
```

--------------------------------

### Get Raw Bytes of SharedLibraryId

Source: https://docs.rs/findshlibs/latest/src/findshlibs/lib.rs.html

Provides a method to retrieve the raw byte representation of a SharedLibraryId. Note that PE signatures do not have a direct byte representation in this context.

```rust
impl SharedLibraryId {
    /// Returns the raw bytes of the shared library ID.
    pub fn as_bytes(&self) -> &[u8] {
        match *self {
            SharedLibraryId::Uuid(ref bytes) => &*bytes,
            SharedLibraryId::GnuBuildId(ref bytes) => bytes,
            SharedLibraryId::PeSignature(_, _) => &[][..],
            SharedLibraryId::PdbSignature(ref bytes, _) => &*bytes,
        }
    }
}
```

--------------------------------

### Any Trait Implementation

Source: https://docs.rs/findshlibs/latest/findshlibs/unsupported/struct.SharedLibrary.html

Implements the Any trait for any type T, providing a way to get the TypeId of the instance.

```rust
where T: 'static + ?Sized,
Source§
#### fn type_id(&self) -> TypeId
Gets the `TypeId` of `self`. Read more
```

--------------------------------

### Get Debug ID

Source: https://docs.rs/findshlibs/latest/findshlibs/linux/struct.SharedLibrary.html

Retrieves the debug-id of the shared library, if available. Returns an Option<SharedLibraryId>.

```rust
fn debug_id(&self) -> Option<SharedLibraryId>
```

--------------------------------

### TryFrom Implementation

Source: https://docs.rs/findshlibs/latest/findshlibs/struct.Avma.html

Provides functionality to attempt conversion from another type into Avma.

```APIDOC
### impl<T, U> TryFrom<U> for T
where U: Into<T>

#### type Error = Infallible

### Description
This implementation allows attempting to convert a type `U` into `T` (where `T` is Avma or a type that can be converted from `U`). The `Error` type is `Infallible`, indicating that conversion errors are not expected under normal circumstances when `U` implements `Into<T>`.

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

### Description
Performs the conversion from type `U` to type `T`.

### Method
`try_from`

### Parameters
- `value` (U): The value to convert.

### Response
- `Result<T, Infallible>`: A `Result` containing the converted value of type `T` if successful, or an `Infallible` error if the conversion fails (which is not expected in this implementation).
```

--------------------------------

### Get Shared Library ID

Source: https://docs.rs/findshlibs/latest/findshlibs/linux/struct.SharedLibrary.html

Retrieves the code-id of the shared library, if available. This is an Option<SharedLibraryId>.

```rust
fn id(&self) -> Option<SharedLibraryId>
```

--------------------------------

### TryInto Implementation

Source: https://docs.rs/findshlibs/latest/findshlibs/struct.Avma.html

Provides functionality to attempt conversion from Avma into another type.

```APIDOC
### impl<T, U> TryInto<U> for T
where U: TryFrom<T>

#### type Error = <U as TryFrom<T>>::Error

### Description
This implementation allows attempting to convert the current type `T` (where `T` is Avma or a type that can be converted into `U`) into another type `U`.

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

### Description
Performs the conversion from the current type `T` to type `U`.

### Method
`try_into`

### Parameters
- `self` (T): The value to convert.

### Response
- `Result<U, <U as TryFrom<T>>::Error>`: A `Result` containing the converted value of type `U` if successful, or an error if the conversion fails.
```

--------------------------------

### Implement CloneToUninit for T

Source: https://docs.rs/findshlibs/latest/findshlibs/struct.Avma.html

A nightly-only experimental API for cloning a value into uninitialized memory. Use with caution as it involves unsafe operations.

```rust
impl<T> CloneToUninit for T
where T: Clone,
```

```rust
unsafe fn clone_to_uninit(&self, dest: *mut u8)
```

--------------------------------

### Segment Length Method

Source: https://docs.rs/findshlibs/latest/findshlibs/linux/struct.Segment.html

Gets the length of the segment in memory, in bytes. This method is part of the Segment trait implementation.

```rust
fn len(&self) -> usize
```

--------------------------------

### Create a New SharedLibrary Instance in Rust

Source: https://docs.rs/findshlibs/latest/src/findshlibs/linux/mod.rs.html

Constructs a `SharedLibrary` instance from `dl_phdr_info`. It handles retrieving the library name, which might involve looking up the executable path or using `dladdr` for dynamically loaded libraries.

```rust
let mut name = Cow::Borrowed(if info.dlpi_name.is_null() {
            CStr::from_bytes_with_nul_unchecked(b"\0")
        } else {
            CStr::from_ptr(info.dlpi_name)
        });
        if name.to_bytes().is_empty() {
            if is_first_lib {
                if let Ok(exe) = current_exe() {
                    name = Cow::Owned(CString::from_vec_unchecked(exe.into_os_string().into_vec()));
                }
            } else {
                let mut dlinfo: libc::Dl_info = mem::zeroed();
                if libc::dladdr(info.dlpi_addr as *const libc::c_void, &mut dlinfo) != 0 {
                    name = Cow::Owned(CString::from(CStr::from_ptr(dlinfo.dli_fname)));
                }
            }
        }

        SharedLibrary {
            size: size,
            addr: info.dlpi_addr as usize as *const _,
            name,
            headers: slice::from_raw_parts(info.dlpi_phdr, info.dlpi_phnum as usize),
        }
```

--------------------------------

### Get Segment Length in Rust

Source: https://docs.rs/findshlibs/latest/src/findshlibs/linux/mod.rs.html

Returns the size of the program segment in memory. This indicates how much space the segment occupies when loaded.

```rust
self.phdr().p_memsz as _
```

--------------------------------

### Get Virtual Memory Bias

Source: https://docs.rs/findshlibs/latest/findshlibs/linux/struct.SharedLibrary.html

Retrieves the virtual memory bias of the shared library. This indicates the preferred base address for loading.

```rust
fn virtual_memory_bias(&self) -> Bias
```

--------------------------------

### SharedLibrary::each Method

Source: https://docs.rs/findshlibs/latest/findshlibs/trait.SharedLibrary.html

Iterates over all shared libraries loaded in the process. The provided closure `f` is called for each library, and its return value controls the iteration.

```rust
fn each<F, C>(f: F)
   where F: FnMut(&Self) -> C,
         C: Into<IterationControl>;
```

--------------------------------

### Nightly/Experimental SegmentIter Methods

Source: https://docs.rs/findshlibs/latest/findshlibs/unsupported/struct.SegmentIter.html

These methods are experimental or require a nightly Rust toolchain to use.

```APIDOC
## Experimental SegmentIter Methods

### Description
Experimental methods available on `SegmentIter` that may require a nightly Rust compiler.

### Methods
- `next_chunk<const N: usize>() -> Result<[Segment<'a>; N], IntoIter<Segment<'a>, N>>`: Advances the iterator and returns an array of `N` values.
- `advance_by(&mut self, n: usize) -> Result<(), NonZero<usize>>`: Advances the iterator by `n` elements.
```

--------------------------------

### SharedLibrary Methods

Source: https://docs.rs/findshlibs/latest/findshlibs/linux/struct.SharedLibrary.html

This section details the methods available on the SharedLibrary struct for Linux.

```APIDOC
## SharedLibrary Methods

### `name()`

- **Description**: Get the name of this shared library.
- **Signature**: `fn name(&self) -> &OsStr`

### `id()`

- **Description**: Get the code-id of this shared library if available.
- **Signature**: `fn id(&self) -> Option<SharedLibraryId>`

### `segments()`

- **Description**: Iterate over this shared library’s segments.
- **Signature**: `fn segments(&self) -> Self::SegmentIter`

### `virtual_memory_bias()`

- **Description**: Get the bias of this shared library.
- **Signature**: `fn virtual_memory_bias(&self) -> Bias`

### `each<F, C>(f: F)`

- **Description**: Find all shared libraries in this process and invoke `f` with each one.
- **Signature**: `fn each<F, C>(f: F) where F: FnMut(&Self) -> C, C: Into<IterationControl>`

### `debug_name()`

- **Description**: Get the name of the debug file with this shared library if there is one.
- **Signature**: `fn debug_name(&self) -> Option<&OsStr>`

### `debug_id()`

- **Description**: Get the debug-id of this shared library if available.
- **Signature**: `fn debug_id(&self) -> Option<SharedLibraryId>`

### `actual_load_addr()`

- **Description**: Returns the address of where the library is loaded into virtual memory.
- **Signature**: `fn actual_load_addr(&self) -> Avma`

### `stated_load_addr()`

- **Description**: Returns the address of where the library prefers to be loaded into virtual memory.
- **Signature**: `fn stated_load_addr(&self) -> Svma`

### `len()`

- **Description**: Returns the size of the image.
- **Signature**: `fn len(&self) -> usize`

### `avma_to_svma(address: Avma)`

- **Description**: Given an AVMA within this shared library, convert it back to an SVMA by removing this shared library’s bias.
- **Signature**: `fn avma_to_svma(&self, address: Avma) -> Svma`
```

--------------------------------

### Newtype Wrappers

Source: https://docs.rs/findshlibs/latest/src/findshlibs/lib.rs.html

Simple newtype wrappers for usize to represent virtual memory addresses and biases with specific formatting.

```APIDOC
## type Svma = usize

### Description
Stated virtual memory address.

### Default Value
`0`

### Display Format
`{:#x}`

## type Avma = usize

### Description
Actual virtual memory address.

### Default Value
`0`

### Display Format
`{:#x}`

## type Bias = usize

### Description
Virtual memory bias.

### Default Value
`0`

### Display Format
`{:#x}`
```

--------------------------------

### Get Raw Bytes of SharedLibraryId

Source: https://docs.rs/findshlibs/latest/findshlibs/enum.SharedLibraryId.html

Returns the raw bytes of the shared library ID. This method is useful for direct byte manipulation or comparison.

```rust
pub fn as_bytes(&self) -> &[u8]
```

--------------------------------

### product

Source: https://docs.rs/findshlibs/latest/findshlibs/linux/struct.SegmentIter.html

Iterates over the entire iterator, multiplying all the elements. The element type must implement the `Product` trait.

```APIDOC
## fn product<P>(self) -> P
where Self: Sized,
 P: Product<Self::Item>,

Iterates over the entire iterator, multiplying all the elements.
```

--------------------------------

### Segment Stated Virtual Memory Address Method

Source: https://docs.rs/findshlibs/latest/findshlibs/linux/struct.Segment.html

Gets the stated virtual memory address of the segment. This method is part of the Segment trait implementation.

```rust
fn stated_virtual_memory_address(&self) -> Svma
```

--------------------------------

### map_windows

Source: https://docs.rs/findshlibs/latest/findshlibs/unsupported/struct.SegmentIter.html

Calls a function for each contiguous window of size N over the iterator and returns an iterator over the results. This is a nightly-only experimental API.

```APIDOC
## fn map_windows<F, R, const N: usize>(self, f: F) -> MapWindows<Self, F, N>
where Self: Sized, F: FnMut(&[Self::Item; N]) -> R,

### Description
🔬 This is a nightly-only experimental API. (`iter_map_windows`)
Calls the given function `f` for each contiguous window of size `N` over `self` and returns an iterator over the outputs of `f`. Like `slice::windows()`, the windows during mapping overlap as well.

### Parameters
- `f`: A closure that takes a slice representing the window and returns a value.

### Returns
A new iterator (`MapWindows`) that yields the results of applying `f` to each window.
```

--------------------------------

### Implement PartialEq for Svma

Source: https://docs.rs/findshlibs/latest/findshlibs/struct.Svma.html

Allows comparison of two Svma values for equality. This is fundamental for checking if two virtual memory addresses are the same.

```rust
impl PartialEq for Svma {
    fn eq(&self, other: &Svma) -> bool
    fn ne(&self, other: &Rhs) -> bool
}
```

--------------------------------

### PartialEq for Svma

Source: https://docs.rs/findshlibs/latest/findshlibs/struct.Svma.html

Provides equality comparison for Svma instances.

```APIDOC
### impl PartialEq for Svma

#### fn eq(&self, other: &Svma) -> bool
Tests for `self` and `other` values to be equal, and is used by `==`.

#### fn ne(&self, other: &Rhs) -> bool
Tests for `!=`.
```

--------------------------------

### Iterate Over All Shared Libraries

Source: https://docs.rs/findshlibs/latest/findshlibs/linux/struct.SharedLibrary.html

Finds all shared libraries loaded in the current process and applies a closure to each one. The closure's return value controls the iteration.

```rust
fn each<F, C>(f: F)
where F: FnMut(&Self) -> C, C: Into<IterationControl>,
```

--------------------------------

### Get Stated Virtual Memory Address in Rust

Source: https://docs.rs/findshlibs/latest/src/findshlibs/linux/mod.rs.html

Retrieves the stated virtual memory address (SVMA) of a program segment. This is the address where the segment is intended to be loaded in memory.

```rust
Svma(self.phdr().p_vaddr as _)
```

--------------------------------

### map_windows

Source: https://docs.rs/findshlibs/latest/findshlibs/linux/struct.SegmentIter.html

Calls a given function for each contiguous window of a specified size over the iterator and returns an iterator over the results. Windows overlap during mapping.

```APIDOC
## fn map_windows<F, R, const N: usize>(self, f: F) -> MapWindows<Self, F, N>

### Description
Calls the given function `f` for each contiguous window of size `N` over `self` and returns an iterator over the outputs of `f`. Like `slice::windows()`, the windows during mapping overlap as well.

### Parameters
- `f` (F): A closure that takes a slice representing the window and returns a value `R`.

### Returns
- `MapWindows<Self, F, N>`: An iterator over the results of applying `f` to each window.
```

--------------------------------

### Segment Actual Virtual Memory Address Method

Source: https://docs.rs/findshlibs/latest/findshlibs/linux/struct.Segment.html

Gets the actual virtual memory address of the segment, considering the shared library context. This method is part of the Segment trait implementation.

```rust
fn actual_virtual_memory_address(&self, shlib: &Self::SharedLibrary) -> Avma
```

--------------------------------

### Segment Trait

Source: https://docs.rs/findshlibs/latest/src/findshlibs/lib.rs.html

The Segment trait defines the interface for accessing information about a mapped segment within a shared library. It includes methods to get the segment's name, virtual memory addresses, and length.

```APIDOC
## trait Segment

### Description
A mapped segment in a shared library.

### Methods

*   `name(&self) -> &str`
    Get this segment's name.

*   `is_code(&self) -> bool`
    Returns `true` if this is a code segment.

*   `is_load(&self) -> bool`
    Returns `true` if this is a segment loaded into memory.

*   `stated_virtual_memory_address(&self) -> Svma`
    Get this segment's stated virtual memory address of this segment. This is the virtual memory address without the bias applied.

*   `len(&self) -> usize`
    Get the length of this segment in memory (in bytes).

*   `actual_virtual_memory_address(&self, shlib: &Self::SharedLibrary) -> Avma`
    Get this segment's actual virtual memory address. This is the virtual memory address with the bias applied.

*   `contains_svma(&self, address: Svma) -> bool`
    Does this segment contain the given stated virtual memory address?

*   `contains_avma(&self, shlib: &Self::SharedLibrary, address: Avma) -> bool`
    Does this segment contain the given actual virtual memory address?
```

--------------------------------

### by_ref

Source: https://docs.rs/findshlibs/latest/findshlibs/unsupported/struct.SegmentIter.html

Creates a "by reference" adapter for an iterator, allowing mutable borrowing of the iterator itself.

```APIDOC
## fn by_ref(&mut self) -> &mut Self
where Self: Sized,

### Description
Creates a “by reference” adapter for this instance of `Iterator`.

### Returns
A mutable reference to the iterator itself, allowing operations that require `&mut self` to be called on the adapter.
```

--------------------------------

### Test: Get and Validate Shared Library Names

Source: https://docs.rs/findshlibs/latest/src/findshlibs/linux/mod.rs.html

This test iterates through all shared libraries, extracts their names, and asserts that the names contain expected substrings like 'findshlibs' and 'libc.so'. It filters out empty names before validation.

```rust
    #[test]
    fn get_name() {
        use std::ffi::OsStr;
        let mut names = vec![];
        linux::SharedLibrary::each(|shlib| {
            println!("{:?}", shlib);
            let name = shlib.name();
            if name != OsStr::new("") {
                names.push(name.to_str().unwrap().to_string());
            }
        });

        assert!(names.iter().any(|x| x.contains("findshlibs")));
        assert!(names.iter().any(|x| x.contains("libc.so")));
    }
```

--------------------------------

### SharedLibrary::actual_load_addr Method

Source: https://docs.rs/findshlibs/latest/findshlibs/trait.SharedLibrary.html

Returns the actual memory address where the shared library is loaded. This corresponds to the `Avma` of the first segment.

```rust
fn actual_load_addr(&self) -> Avma { ... }
```

--------------------------------

### Verify GNU Build ID of Linux Shared Libraries

Source: https://docs.rs/findshlibs/latest/src/findshlibs/linux/mod.rs.html

Iterates through each shared library, retrieves its GNU Build ID, and compares it with the ID reported by the `readelf -n` command. This test is only executed on Linux systems.

```rust
    #[test]
    #[cfg(target_os = "linux")]
    fn get_id() {
        use std::path::Path;
        use std::process::Command;

        linux::SharedLibrary::each(|shlib| {
            let name = shlib.name();
            let id = shlib.id();
            if id.is_none() {
                println!("no id found for {:?}", name);
                return;
            }
            let path: &Path = name.as_ref();
            if !path.is_absolute() {
                return;
            }
            let gnu_build_id = id.unwrap().to_string();
            let readelf = Command::new("readelf")
                .arg("-n")
                .arg(path)
                .output()
                .unwrap();
            for line in String::from_utf8(readelf.stdout).unwrap().lines() {
                if let Some(index) = line.find("Build ID: ") {
                    let readelf_build_id = line[index + 9..].trim();
                    assert_eq!(readelf_build_id, gnu_build_id);
                }
            }
            println!("{}: {}", path.display(), gnu_build_id);
        });
    }
```

--------------------------------

### Get GNU Build ID from Shared Library

Source: https://docs.rs/findshlibs/latest/src/findshlibs/linux/mod.rs.html

Retrieves the GNU Build ID from a shared library by searching for `PT_NOTE` segments and specifically the `NT_GNU_BUILD_ID` note type with the name `GNU`. This ID is a unique identifier generated by the linker.

```rust
    fn id(&self) -> Option<SharedLibraryId> {
        // Search for `PT_NOTE` segments, containing auxilliary information.
        // Such segments contain a series of "notes" and one kind of note is
        // `NT_GNU_BUILD_ID`, whose payload contains a unique identifier
        // generated by the linker. Return the first one we find, if any.
        for segment in self.note_segments() {
            for (note_type, note_name, note_descriptor) in unsafe { segment.notes(self) } {
                if note_type == NT_GNU_BUILD_ID && note_name == b"GNU\0" {
                    return Some(SharedLibraryId::GnuBuildId(note_descriptor.to_vec()));
                }
            }
        }

        None
    }
```

--------------------------------

### by_ref

Source: https://docs.rs/findshlibs/latest/findshlibs/linux/struct.SegmentIter.html

Creates a reference adapter for an iterator, allowing mutable borrowing of the iterator itself for operations.

```APIDOC
## fn by_ref(&mut self) -> &mut Self

### Description
Creates a “by reference” adapter for this instance of `Iterator`.

### Returns
- `&mut Self`: A mutable reference to the iterator.
```

--------------------------------

### PartialOrd for Svma

Source: https://docs.rs/findshlibs/latest/findshlibs/struct.Svma.html

Provides partial ordering comparison for Svma instances.

```APIDOC
### impl PartialOrd for Svma

#### fn partial_cmp(&self, other: &Svma) -> Option<Ordering>
This method returns an ordering between `self` and `other` values if one exists.

#### fn lt(&self, other: &Rhs) -> bool
Tests less than (for `self` and `other`) and is used by the `<` operator.

#### fn le(&self, other: &Rhs) -> bool
Tests less than or equal to (for `self` and `other`) and is used by the `<=` operator.

#### fn gt(&self, other: &Rhs) -> bool
Tests greater than (for `self` and `other`) and is used by the `>` operator.

#### fn ge(&self, other: &Rhs) -> bool
Tests greater than or equal to (for `self` and `other`) and is used by the `>=` operator.
```

--------------------------------

### Nightly-Only API: advance_by

Source: https://docs.rs/findshlibs/latest/findshlibs/linux/struct.SegmentIter.html

This nightly-only experimental API advances the iterator by a specified number of elements. It requires the `iter_advance_by` feature.

```rust
fn advance_by(&mut self, n: usize) -> Result<(), NonZero<usize>>

```

--------------------------------

### Implement Display for Avma

Source: https://docs.rs/findshlibs/latest/findshlibs/struct.Avma.html

Allows Avma instances to be formatted as strings, typically for user-facing output. This enables printing Avma values directly.

```rust
impl Display for Avma {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result
}
```

--------------------------------

### Implement PartialEq for Avma

Source: https://docs.rs/findshlibs/latest/findshlibs/struct.Avma.html

Enables equality comparison between Avma instances. This allows checking if two memory addresses are the same.

```rust
impl PartialEq for Avma {
    fn eq(&self, other: &Avma) -> bool
}
```

```rust
fn ne(&self, other: &Rhs) -> bool
```

--------------------------------

### Clone for Svma

Source: https://docs.rs/findshlibs/latest/findshlibs/struct.Svma.html

Provides methods for cloning Svma instances.

```APIDOC
### impl Clone for Svma

#### fn clone(&self) -> Svma
Returns a duplicate of the value.

#### fn clone_from(&mut self, source: &Self)
Performs copy-assignment from `source`.
```

--------------------------------

### SharedLibrary Trait Methods

Source: https://docs.rs/findshlibs/latest/trait.SharedLibrary.html

This section details the methods available on the SharedLibrary trait, categorized into required and provided methods.

```APIDOC
## Trait: SharedLibrary

A trait representing a shared library that is loaded in this process.

### Required Methods

#### fn name(&self) -> &OsStr
Get the name of this shared library.

#### fn id(&self) -> Option<SharedLibraryId>
Get the code-id of this shared library if available.

#### fn segments(&self) -> Self::SegmentIter
Iterate over this shared library’s segments.

#### fn virtual_memory_bias(&self) -> Bias
Get the bias of this shared library.

#### fn each<F, C>(f: F)
where F: FnMut(&Self) -> C, C: Into<IterationControl>,
Find all shared libraries in this process and invoke `f` with each one.

### Provided Methods

#### fn debug_name(&self) -> Option<&OsStr>
Get the name of the debug file with this shared library if there is one.

#### fn debug_id(&self) -> Option<SharedLibraryId>
Get the debug-id of this shared library if available.

#### fn actual_load_addr(&self) -> Avma
Returns the address of where the library is loaded into virtual memory.

#### fn stated_load_addr(&self) -> Svma
Returns the address of where the library prefers to be loaded into virtual memory.

#### fn len(&self) -> usize
Returns the size of the image.

#### fn avma_to_svma(&self, address: Avma) -> Svma
Given an AVMA within this shared library, convert it back to an SVMA by removing this shared library’s bias.
```

--------------------------------

### Implement Any for T

Source: https://docs.rs/findshlibs/latest/findshlibs/struct.Avma.html

Provides dynamic type information for any type T. This is part of Rust's trait system for runtime type identification.

```rust
impl<T> Any for T
where T: 'static + ?Sized,
```

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### Define Simple Newtype Wrappers

Source: https://docs.rs/findshlibs/latest/src/findshlibs/lib.rs.html

This macro simplifies the creation of newtype wrappers for primitive types, providing common implementations like `Default`, `From`, `Debug`, `PartialEq`, `Eq`, `PartialOrd`, `Ord`, and `Hash`. It's useful for creating distinct types with specific formatting or behavior.

```rust
macro_rules! simple_newtypes {
    (
        $(
            $(#[$attr:meta])* 
            type $name:ident = $oldty:ty
            where
                default = $default:expr ,
                display = $format:expr ;
        )*
    ) => {
        $( 
            $(#[$attr])* 
            #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
            pub struct $name(pub $oldty);

            impl Default for $name {
                #[inline]
                fn default() -> Self {
                    $name( $default )
                }
            }

            impl From<$oldty> for $name {
                fn from(x: $oldty) -> $name {
                    $name(x)
                }
            }

            impl From<$name> for $oldty {
                fn from($name(x): $name) -> $oldty {
                    x
                }
            }

            impl fmt::Display for $name {
                fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
                    write!(f, $format, self.0)
                }
            }
        )*
    }
}

simple_newtypes! {
    /// Stated virtual memory address.
    ///
    /// See the module documentation for details.
    type Svma = usize
    where
        default = 0,
        display = "{:#x}";

    /// Actual virtual memory address.
    ///
    /// See the module documentation for details.
    type Avma = usize
    where
        default = 0,
        display = "{:#x}";

    /// Virtual memory bias.
    ///
    /// See the module documentation for details.
    type Bias = usize
    where
        default = 0,
        display = "{:#x}";
}
```

--------------------------------

### as_bytes Method

Source: https://docs.rs/findshlibs/latest/findshlibs/enum.SharedLibraryId.html

Returns the raw bytes of the shared library ID.

```APIDOC
## impl SharedLibraryId

### pub fn as_bytes(&self) -> &[u8]

Returns the raw bytes of the shared library ID.
```

--------------------------------

### TryInto<U> for Svma

Source: https://docs.rs/findshlibs/latest/findshlibs/struct.Svma.html

Implementation of the TryInto trait for Svma, allowing conversion into other types.

```APIDOC
### impl<T, U> TryInto<U> for T
where U: TryFrom<T>

#### type Error = <U as TryFrom<T>>::Error

### Description
The type returned in the event of a conversion error.

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

### Description
Performs the conversion.

### Method
`try_into`

### Parameters
None

### Response
#### Success Response
- **U**: The converted value.
#### Error Response
- **Error**: The error type associated with the conversion.
```

--------------------------------

### SharedLibrary::name Method

Source: https://docs.rs/findshlibs/latest/findshlibs/trait.SharedLibrary.html

Retrieves the name of the shared library.

```rust
fn name(&self) -> &OsStr;
```

--------------------------------

### Implement Display for Svma

Source: https://docs.rs/findshlibs/latest/findshlibs/struct.Svma.html

Allows the Svma struct to be formatted for display to the user. This is useful for logging or presenting the virtual memory address in a human-readable format.

```rust
impl Display for Svma {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result
}
```

--------------------------------

### PartialEq for Avma

Source: https://docs.rs/findshlibs/latest/findshlibs/struct.Avma.html

Provides equality comparison for Avma.

```APIDOC
### impl PartialEq for Avma

#### fn eq(&self, other: &Avma) -> bool

Tests for `self` and `other` values to be equal, and is used by `==`.

#### fn ne(&self, other: &Rhs) -> bool

Tests for `!=`.
```

--------------------------------

### TryFrom<U> for Svma

Source: https://docs.rs/findshlibs/latest/findshlibs/struct.Svma.html

Implementation of the TryFrom trait for Svma, allowing conversion from other types.

```APIDOC
### impl<T, U> TryFrom<U> for T
where U: Into<T>

#### type Error = Infallible

### Description
The type returned in the event of a conversion error.

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

### Description
Performs the conversion.

### Method
`try_from`

### Parameters
- **value** (U): The value to convert.

### Response
#### Success Response
- **T**: The converted value.
#### Error Response
- **Infallible**: Indicates that this conversion cannot fail.
```

--------------------------------

### Compare SharedLibraryId for Equality

Source: https://docs.rs/findshlibs/latest/findshlibs/enum.SharedLibraryId.html

Tests for equality between two SharedLibraryId instances. This is part of the PartialEq trait.

```rust
fn eq(&self, other: &SharedLibraryId) -> bool
```

--------------------------------

### TryFrom Implementation

Source: https://docs.rs/findshlibs/latest/findshlibs/struct.Bias.html

Implementation of the TryFrom trait for the Bias struct.

```APIDOC
### impl<T, U> TryFrom<U> for T

#### type Error = Infallible

### Description
The type returned in the event of a conversion error.

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

### Description
Performs the conversion.

### Method
`try_from`

### Parameters
- `value` (U): The value to convert.

### Returns
- `Result<T, <T as TryFrom<U>>::Error>`: A Result containing the converted value or an error.
```

--------------------------------

### TryInto Implementation

Source: https://docs.rs/findshlibs/latest/findshlibs/struct.Bias.html

Implementation of the TryInto trait for the Bias struct.

```APIDOC
### impl<T, U> TryInto<U> for T

#### type Error = <U as TryFrom<T>>::Error

### Description
The type returned in the event of a conversion error.

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

### Description
Performs the conversion.

### Method
`try_into`

### Parameters
None

### Returns
- `Result<U, <U as TryFrom<T>>::Error>`: A Result containing the converted value or an error.
```

--------------------------------

### SharedLibrary Trait Implementations for TargetSharedLibrary

Source: https://docs.rs/findshlibs/latest/findshlibs/type.TargetSharedLibrary.html

Details the methods available on TargetSharedLibrary through its implementation of the SharedLibrary trait.

```APIDOC
## Trait Implementations

### impl<'a> SharedLibrary for SharedLibrary<'a>

#### fn name(&self) -> &OsStr
Get the name of this shared library.

#### fn id(&self) -> Option<SharedLibraryId>
Get the code-id of this shared library if available.

#### fn segments(&self) -> Self::SegmentIter
Iterate over this shared library’s segments.

#### fn virtual_memory_bias(&self) -> Bias
Get the bias of this shared library.

#### fn each<F, C>(f: F)
where F: FnMut(&Self) -> C, C: Into<IterationControl>,
Find all shared libraries in this process and invoke `f` with each one.

#### fn debug_name(&self) -> Option<&OsStr>
Get the name of the debug file with this shared library if there is one.

#### fn debug_id(&self) -> Option<SharedLibraryId>
Get the debug-id of this shared library if available.

#### fn actual_load_addr(&self) -> Avma
Returns the address of where the library is loaded into virtual memory.

#### fn stated_load_addr(&self) -> Svma
Returns the address of where the library prefers to be loaded into virtual memory.

#### fn len(&self) -> usize
Returns the size of the image.

#### fn avma_to_svma(&self, address: Avma) -> Svma
Given an AVMA within this shared library, convert it back to an SVMA by removing this shared library’s bias.
```

--------------------------------

### Iterate Through Program Headers with `dl_iterate_phdr`

Source: https://docs.rs/findshlibs/latest/src/findshlibs/linux/mod.rs.html

This function iterates through all program headers of loaded shared libraries. It accepts a closure that is called for each library, allowing for custom processing. The iteration can be controlled by returning `IterationControl::Break` or `IterationControl::Continue` from the closure.

```rust
    #[inline]
    fn each<F, C>(
        f: F,
    )
    where
        F: FnMut(&Self) -> C,
        C: Into<IterationControl>,
    {
        let mut state = IterState {
            f: f,
            panic: None,
            idx: 0,
        };

        unsafe {
            libc::dl_iterate_phdr(Some(Self::callback::<F, C>), &mut state as *mut _ as *mut _);
        }

        if let Some(panic) = state.panic {
            panic::resume_unwind(panic);
        }
    }
```

--------------------------------

### SharedLibrary::len Method

Source: https://docs.rs/findshlibs/latest/findshlibs/trait.SharedLibrary.html

Returns the size of the shared library's image, typically the size of its executable code segment. Useful for symbolication systems.

```rust
fn len(&self) -> usize { ... }
```

--------------------------------

### Conversion

Source: https://docs.rs/findshlibs/latest/findshlibs/linux/struct.SegmentIter.html

Methods related to value conversion and iteration.

```APIDOC
## fn from(t: T) -> T

### Description
Returns the argument unchanged.

### Method Signature
`fn from(t: T) -> T`
```

```APIDOC
## fn into(self) -> U

### Description
Calls `U::from(self)`. That is, this conversion is whatever the implementation of `From<T> for U` chooses to do.

### Method Signature
`fn into(self) -> U`

### Type Constraints
`where U: From<T>`
```

```APIDOC
## fn into_iter(self) -> I

### Description
Creates an iterator from a value.

### Method Signature
`fn into_iter(self) -> I`

### Type Constraints
`where I: Iterator`
```

```APIDOC
## fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

### Description
Performs the conversion.

### Method Signature
`fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>`
```

```APIDOC
## fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

### Description
Performs the conversion.

### Method Signature
`fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>`
```

--------------------------------

### Implement Clone for Svma

Source: https://docs.rs/findshlibs/latest/findshlibs/struct.Svma.html

Enables creating copies of Svma values. This is a common requirement for passing values around or storing multiple instances.

```rust
impl Clone for Svma {
    fn clone(&self) -> Svma
}
```

```rust
fn clone_from(&mut self, source: &Self)
```

--------------------------------

### any

Source: https://docs.rs/findshlibs/latest/findshlibs/unsupported/struct.SegmentIter.html

Tests if any element of the iterator matches a predicate.

```APIDOC
## fn any<F>(&mut self, f: F) -> bool
where Self: Sized, F: FnMut(Self::Item) -> bool,

### Description
Tests if any element of the iterator matches a predicate.

### Parameters
- `f`: A closure that takes an item and returns `true` if it matches the predicate, `false` otherwise.

### Returns
`true` if at least one element matches the predicate, `false` otherwise.
```

--------------------------------

### List Shared Library Segments in Rust

Source: https://docs.rs/findshlibs/latest/src/list_segments/list_segments.rs.html

Iterates through all loaded shared libraries and prints the virtual memory address and name of each segment within them. Ensure the findshlibs crate is added as a dependency.

```rust
extern crate findshlibs;
use findshlibs::{Segment, SharedLibrary, TargetSharedLibrary};

fn main() {
    TargetSharedLibrary::each(|shlib| {
        println!("{}", shlib.name().to_string_lossy());

        for seg in shlib.segments() {
            println!(
                "    {}: segment {}",
                seg.actual_virtual_memory_address(shlib),
                seg.name()
            );
        }
    });
}
```

--------------------------------

### partition

Source: https://docs.rs/findshlibs/latest/findshlibs/unsupported/struct.SegmentIter.html

Consumes an iterator and divides its elements into two collections based on a predicate.

```APIDOC
## fn partition<B, F>(self, f: F) -> (B, B)
where Self: Sized, B: Default + Extend<Self::Item>, F: FnMut(&Self::Item) -> bool,

### Description
Consumes an iterator, creating two collections from it based on a predicate.

### Parameters
- `f`: A closure that takes a reference to an item and returns `true` if the item belongs to the first collection, `false` otherwise.

### Returns
A tuple containing two collections (`B`), where the first contains elements for which `f` returned `true`, and the second contains elements for which `f` returned `false`.
```

--------------------------------

### Ord for Svma

Source: https://docs.rs/findshlibs/latest/findshlibs/struct.Svma.html

Provides total ordering comparison for Svma instances.

```APIDOC
### impl Ord for Svma

#### fn cmp(&self, other: &Svma) -> Ordering
This method returns an `Ordering` between `self` and `other`.

#### fn max(self, other: Self) -> Self
Compares and returns the maximum of two values.

#### fn min(self, other: Self) -> Self
Compares and returns the minimum of two values.

#### fn clamp(self, min: Self, max: Self) -> Self
Restrict a value to a certain interval.
```

--------------------------------

### SharedLibrary Trait Implementations

Source: https://docs.rs/findshlibs/latest/findshlibs/unsupported/struct.SharedLibrary.html

This section details the implementations of the SharedLibrary trait for the SharedLibrary struct, outlining the available methods for interacting with shared library information.

```APIDOC
## impl<'a> SharedLibrary for SharedLibrary<'a>

### Associated Types

- **Segment**: `Segment<'a>`
- **SegmentIter**: `SegmentIter<'a>`

### Methods

- **`name(&self) -> &OsStr`**: Get the name of this shared library.
- **`id(&self) -> Option<SharedLibraryId>`**: Get the code-id of this shared library if available.
- **`segments(&self) -> Self::SegmentIter`**: Iterate over this shared library’s segments.
- **`virtual_memory_bias(&self) -> Bias`**: Get the bias of this shared library.
- **`each<F, C>(_f: F)`**: Find all shared libraries in this process and invoke `f` with each one.
- **`debug_name(&self) -> Option<&OsStr>`**: Get the name of the debug file with this shared library if there is one.
- **`debug_id(&self) -> Option<SharedLibraryId>`**: Get the debug-id of this shared library if available.
- **`actual_load_addr(&self) -> Avma`**: Returns the address of where the library is loaded into virtual memory.
- **`stated_load_addr(&self) -> Svma`**: Returns the address of where the library prefers to be loaded into virtual memory.
- **`len(&self) -> usize`**: Returns the size of the image.
- **`avma_to_svma(&self, address: Avma) -> Svma`**: Given an AVMA within this shared library, convert it back to an SVMA by removing this shared library’s bias.
```

--------------------------------

### Borrowing

Source: https://docs.rs/findshlibs/latest/findshlibs/linux/struct.SegmentIter.html

Provides methods for borrowing data immutably or mutably.

```APIDOC
## fn borrow(&self) -> &T

### Description
Immutably borrows from an owned value.

### Method Signature
`fn borrow(&self) -> &T`
```

```APIDOC
## fn borrow_mut(&mut self) -> &mut T

### Description
Mutably borrows from an owned value.

### Method Signature
`fn borrow_mut(&mut self) -> &mut T`
```

--------------------------------

### SharedLibrary::stated_load_addr Method

Source: https://docs.rs/findshlibs/latest/findshlibs/trait.SharedLibrary.html

Returns the preferred memory address for loading the shared library. This corresponds to the `Svma` of the first segment.

```rust
fn stated_load_addr(&self) -> Svma { ... }
```

--------------------------------

### Iterate Over Shared Libraries

Source: https://docs.rs/findshlibs/latest/src/findshlibs/lib.rs.html

This function iterates over all shared libraries loaded in the current process and applies a closure to each one. The iteration can be controlled using the `IterationControl` enum.

```APIDOC
## each<F, C>(f: F)

### Description
Find all shared libraries in this process and invoke `f` with each one.

### Parameters
* `f` - A closure that takes a reference to a `Self` (the shared library) and returns a value that can be converted into `IterationControl`.

### Type Parameters
* `F`: The type of the closure.
* `C`: The type returned by the closure, which must implement `Into<IterationControl>`.
```

--------------------------------

### Implement From<T> for T

Source: https://docs.rs/findshlibs/latest/findshlibs/struct.Avma.html

A trivial implementation of From where a type is converted into itself. This is a standard identity conversion.

```rust
impl<T> From<T> for T {
    fn from(t: T) -> T
}
```

--------------------------------

### Display for Svma

Source: https://docs.rs/findshlibs/latest/findshlibs/struct.Svma.html

Provides a Display implementation for Svma, allowing it to be formatted for display.

```APIDOC
### impl Display for Svma

#### fn fmt(&self, f: &mut Formatter<'_>) -> Result
Formats the value using the given formatter.
```

--------------------------------

### Implement Debug for Avma

Source: https://docs.rs/findshlibs/latest/findshlibs/struct.Avma.html

Enables Avma instances to be formatted for debugging output. This is crucial for inspecting the values of Avma during development.

```rust
impl Debug for Avma {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result
}
```

--------------------------------

### Implement Default for Avma

Source: https://docs.rs/findshlibs/latest/findshlibs/struct.Avma.html

Provides a default value for Avma, typically representing a null or zero address. This is useful for initializing Avma variables.

```rust
impl Default for Avma {
    fn default() -> Self
}
```