getrandom

https://docs.rs/getrandom/latest/
Admin
A Rust library for retrieving cryptographically secure random data from operating system sources.
Tokens:18,351
Snippets:180
Trust Score:9.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### Custom Backend Implementation Example

Source: https://docs.rs/getrandom/latest/getrandom

Example of implementing a custom random data source and integrating it with the getrandom crate's custom backend interface.

```rust
use getrandom::Error;

fn my_entropy_source(buf: &mut [u8]) -> Result<(), getrandom::Error> {
    // ...
    Ok(())
}

#[unsafe(no_mangle)]
unsafe extern "Rust" fn __getrandom_v03_custom(
    dest: *mut u8,
    len: usize,
) -> Result<(), Error> {
    let buf = unsafe {
        // fill the buffer with zeros
        core::ptr::write_bytes(dest, 0, len);
        // create mutable byte slice
        core::slice::from_raw_parts_mut(dest, len)
    };
    my_entropy_source(buf)
}
```

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

### SysRng Usage Example

Source: https://docs.rs/getrandom/latest/getrandom/struct.SysRng.html

Demonstrates how to use SysRng to fill a byte array with random data. This requires the `sys_rng` crate feature.

```rust
use getrandom::{rand_core::TryRng, SysRng};

let mut key = [0u8; 32];
SysRng.try_fill_bytes(&mut key).unwrap();
```

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

### Get a random u64

Source: https://docs.rs/getrandom/latest/getrandom/fn.u64.html

This example demonstrates how to call the `u64()` function to get a random u64 value. It uses the `?` operator to handle potential errors.

```rust
let rng_seed = getrandom::u64()?;
```

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

### Filling a Byte Slice with Random Data

Source: https://docs.rs/getrandom/latest/getrandom/fn.fill.html

This example demonstrates how to use the `getrandom::fill` function to fill a 32-byte buffer with random data. Ensure that the `getrandom` crate is added as a dependency and that the necessary error handling (e.g., using `?`) is in place.

```rust
let mut buf = [0u8; 32];
getrandom::fill(&mut buf)?;
```

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

### Filling a MaybeUninit Buffer with Random Bytes

Source: https://docs.rs/getrandom/latest/getrandom/fn.fill_uninit.html

This example demonstrates how to fill a potentially uninitialized buffer with random bytes using `getrandom::fill_uninit`. It requires the `maybe_uninit_uninit_array` feature. The function returns a mutable reference to the initialized bytes.

```rust
#![feature(maybe_uninit_uninit_array)]
let mut buf = core::mem::MaybeUninit::uninit_array::<1024>();
let buf: &mut [u8] = getrandom::fill_uninit(&mut buf)?;

```

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

### u64

Source: https://docs.rs/getrandom/latest/getrandom/fn.u64.html

Get random u64 from the system’s preferred random number source.

```APIDOC
## u64

### Description
Get random `u64` from the system’s preferred random number source.

### Signature
```rust
pub fn u64() -> Result<u64, Error>
```

### Examples
```rust
let rng_seed = getrandom::u64()?;
```
```

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

### Fill a potentially uninitialized buffer with random data

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

Fills a mutable slice of `MaybeUninit<u8>` with random bytes and returns a mutable reference to the initialized portion. The buffer is guaranteed to be initialized upon successful return. This example requires the `maybe_uninit_uninit_array` unstable feature.

```rust
#![feature(maybe_uninit_uninit_array)]
# fn main() -> Result<(), getrandom::Error> {
let mut buf = core::mem::MaybeUninit::uninit_array::<1024>();
let buf: &mut [u8] = getrandom::fill_uninit(&mut buf)?;
# Ok(())
# }
```

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

### Unsupported Target Compilation Error

Source: https://docs.rs/getrandom/latest/src/getrandom/backends.rs.html

Provides a compile-time error for unsupported target architectures or operating systems, guiding users to define a custom backend.

```rust
else {
        compile_error!(concat("target is not supported. You may need to define a custom backend see: \https://docs.rs/getrandom/", env!("CARGO_PKG_VERSION"), "/#custom-backend")
    }
```

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

### Get a random u64

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

Retrieves a random 64-bit unsigned integer from the system's preferred random number source.

```rust
# // This example is incomplete as it's cut off in the source.
# // Assuming it would be similar to the u32 example:
# fn main() -> Result<(), getrandom::Error> {
# let _ = getrandom::u64()?;
# Ok(())
# }
```

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

### u32

Source: https://docs.rs/getrandom/latest/getrandom/fn.u32.html

Gets a random u32 from the system's preferred random number source. This function returns a Result, which will be Ok(u32) on success or Err(Error) on failure.

```APIDOC
## u32

### Description

Get random `u32` from the system’s preferred random number source.

### Signature

```rust
pub fn u32() -> Result<u32, Error>
```

### Example

```rust
let rng_seed = getrandom::u32()?;
```

### Return Value

- `Result<u32, Error>`: Ok containing a random `u32` on success, or an `Error` on failure.
```

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

### Implement Custom Backend for GetRandom

Source: https://docs.rs/getrandom/latest/getrandom

Demonstrates how to provide a custom implementation for the `fill_uninit` function using the `extern_item_impls` nightly feature. This allows overriding existing backends or providing support for new targets.

```Rust
use core::mem::MaybeUninit;

#[cfg(getrandom_backend = "extern_impl")]
#[getrandom::implementation::fill_uninit]
fn my_fill_uninit_implementation(
    dest: &mut [MaybeUninit<u8>]
) -> Result<(), getrandom::Error> {
    // ...
    Ok(())
}
```

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

### Get a random u32

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

Retrieves a random 32-bit unsigned integer from the system's preferred random number source.

```rust
let rng_seed = getrandom::u32()?;
```

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

### Configure Linux Backend via .cargo/config.toml

Source: https://docs.rs/getrandom/latest/getrandom

Set the getrandom_backend configuration flag for Linux targets in your Cargo configuration file.

```toml
[target.'cfg(target_os = "linux")']
rustflags = ['--cfg', 'getrandom_backend="linux_getrandom"']
```

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

### Standard Windows Backend Selection

Source: https://docs.rs/getrandom/latest/src/getrandom/backends.rs.html

Selects the standard Windows backend for general Windows targets.

```rust
else if #[cfg(windows)] {
        mod windows;
        pub use windows::*
    }
```

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

### Configure Linux Backend via Cargo.toml

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

Set the `getrandom_backend` flag for Linux targets in the `.cargo/config.toml` file. This ensures the correct backend is used for Linux builds.

```toml
# It's recommended to set the flag on a per-target basis:
[target.'cfg(target_os = "linux")']
rustflags = ['--cfg', 'getrandom_backend="linux_getrandom"']
```

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

### Get Random u32

Source: https://docs.rs/getrandom/latest/getrandom/fn.u32.html

Retrieves a random u32 from the system's preferred random number source. This function returns a Result, so error handling is necessary.

```Rust
let rng_seed = getrandom::u32()?;

```

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

### Configure Linux Backend via RUSTFLAGS Environment Variable

Source: https://docs.rs/getrandom/latest/getrandom

Set the getrandom_backend configuration flag for Linux targets using the RUSTFLAGS environment variable.

```bash
RUSTFLAGS='--cfg getrandom_backend="linux_getrandom"' cargo build
```

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

### Windows Legacy (win7) Backend Selection

Source: https://docs.rs/getrandom/latest/src/getrandom/backends.rs.html

Selects the legacy Windows backend for Windows 7.

```rust
else if #[cfg(all(windows, target_vendor = "win7"))] {
        mod windows_legacy;
        pub use windows_legacy::*
    }
```

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

### Running Sanitizer Tests

Source: https://docs.rs/getrandom/latest/getrandom

This command demonstrates how to run sanitizer tests for a crate that depends on getrandom, specifically enabling MemorySanitizer.

```bash
RUSTFLAGS="-Zsanitizer=memory" cargo test -Zbuild-std --target=x86_64-unknown-linux-gnu
```

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

### Solid AS P3 Backend Selection

Source: https://docs.rs/getrandom/latest/src/getrandom/backends.rs.html

Selects the Solid AS P3 specific backend for random number generation.

```rust
else if #[cfg(target_os = "solid_asp3")] {
        mod solid;
        pub use solid::*
    }
```

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

### Apple Other OS Backends Selection

Source: https://docs.rs/getrandom/latest/src/getrandom/backends.rs.html

Selects the backend for various Apple operating systems like iOS, visionOS, watchOS, and tvOS.

```rust
else if #[cfg(any(
        target_os = "ios",
        target_os = "visionos",
        target_os = "watchos",
        target_os = "tvos",
    ))] {
        mod apple_other;
        pub use apple_other::*
    }
```

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

### WASI Backend Selection (p1/p2-3)

Source: https://docs.rs/getrandom/latest/src/getrandom/backends.rs.html

Selects the WebAssembly System Interface (WASI) backend, differentiating between p1 and p2-3 environments.

```rust
else if #[cfg(all(target_arch = "wasm32", target_os = "wasi"))] {
        cfg_if! {
            if #[cfg(target_env = "p1")] {
                mod wasi_p1;
                pub use wasi_p1::*
            } else {
                mod wasi_p2_3;
                pub use wasi_p2_3::*
            }
        }
    }
```

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

### NetBSD Backend Selection

Source: https://docs.rs/getrandom/latest/src/getrandom/backends.rs.html

Selects the NetBSD specific backend for random number generation.

```rust
else if #[cfg(target_os = "netbsd")] {
        mod netbsd;
        pub use netbsd::*
    }
```

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

### Custom Implementation with `implementation::fill_uninit`

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

Demonstrates how to override the default random number generation with a custom implementation using the `#[getrandom::implementation::fill_uninit]` attribute macro. This feature is currently limited to nightly Rust.

```rust
# use core::mem::MaybeUninit;
# #[cfg(getrandom_backend = "extern_impl")]
#[getrandom::implementation::fill_uninit]
fn my_fill_uninit_implementation(
    dest: &mut [MaybeUninit<u8>]
) -> Result<(), getrandom::Error> {
    // ...
#   let _ = dest;
#   Err(Error::UNSUPPORTED)
}
```

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

### fill_uninit

Source: https://docs.rs/getrandom/latest/getrandom/fn.fill_uninit.html

Fills a potentially uninitialized buffer `dest` with random bytes from the system’s preferred random number source and returns a mutable reference to those bytes. On successful completion, the buffer is guaranteed to be initialized.

```APIDOC
## fill_uninit

### Description

Fill potentially uninitialized buffer `dest` with random bytes from the system’s preferred random number source and return a mutable reference to those bytes. On successful completion this function is guaranteed to return a slice which points to the same memory as `dest` and has the same length. In other words, it’s safe to assume that `dest` is initialized after this function has returned `Ok`. No part of `dest` will ever be de-initialized at any point, regardless of what is returned.

### Function Signature

```rust
pub fn fill_uninit(dest: &mut [MaybeUninit<u8>]) -> Result<&mut [u8], Error>
```

### Parameters

#### Path Parameters

* `dest` (*mut [MaybeUninit<u8>]) - A mutable slice of `MaybeUninit<u8>` to be filled with random bytes.

### Returns

* `Result<&mut [u8], Error>` - On success, returns a mutable reference to the initialized byte slice. On failure, returns an `Error`.

### Examples

ⓘ
```rust
#![feature(maybe_uninit_uninit_array)]
let mut buf = core::mem::MaybeUninit::uninit_array::<1024>();
let buf: &mut [u8] = getrandom::fill_uninit(&mut buf)?;
```
```

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

### Add getrandom Dependency to Cargo.toml

Source: https://docs.rs/getrandom/latest/getrandom

To use the getrandom crate, add it as a dependency in your Cargo.toml file. Specify the desired version.

```toml
[dependencies]
getrandom = "0.3"
```

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

### PartialEq Implementation

Source: https://docs.rs/getrandom/latest/getrandom/struct.Error.html

Demonstrates the `PartialEq` trait implementation for comparing `Error` instances for equality.

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

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

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

### SGX (x86_64) Backend Selection

Source: https://docs.rs/getrandom/latest/src/getrandom/backends.rs.html

Selects the rdrand backend for x86_64 architecture within Intel SGX environments.

```rust
else if #[cfg(all(target_arch = "x86_64", target_env = "sgx"))] {
        mod rdrand;
        pub use rdrand::*
    }
```

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

### Hermit Backend Selection

Source: https://docs.rs/getrandom/latest/src/getrandom/backends.rs.html

Selects the HermitCore operating system specific backend for random number generation.

```rust
else if #[cfg(target_os = "hermit")] {
        mod hermit;
        pub use hermit::*
    }
```

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

### Default Implementation: inner_u64

Source: https://docs.rs/getrandom/latest/src/getrandom/util.rs.html

Provides a default implementation for generating a u64 using `fill_uninit`. It initializes a MaybeUninit<u64> and fills it with random bytes.

```rust
#![allow(dead_code)]
use crate::Error;
use core::{mem::MaybeUninit, ptr, slice};

/// Default implementation of `inner_u64` on top of `fill_uninit`
#[inline]
pub fn inner_u64() -> Result<u64, Error> {
    let mut res = MaybeUninit::<u64>::uninit();
    // SAFETY: the created slice has the same size as `res`
    let dst = unsafe {
        let p: *mut MaybeUninit<u8> = res.as_mut_ptr().cast();
        slice::from_raw_parts_mut(p, core::mem::size_of::<u64>())
    };
    crate::fill_uninit(dst)?;
    // SAFETY: `dst` has been fully initialized by `imp::fill_inner`
    // since it returned `Ok`.
    Ok(unsafe { res.assume_init() })
}
```

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

### Conditional Compilation for getrandom Backends

Source: https://docs.rs/getrandom/latest/src/getrandom/backends.rs.html

This snippet shows how `cfg_if!` macro is used to select the appropriate backend implementation for getrandom based on compile-time configuration flags. It covers various operating systems and specific configurations like custom implementations, Linux variants, RDRAND, EFI, Windows legacy, and external implementations.

```rust
cfg_if! {
    if #[cfg(getrandom_backend = "custom")] {
        mod custom;
        pub use custom::*;
    } else if #[cfg(getrandom_backend = "linux_getrandom")] {
        mod getrandom;
        pub use getrandom::*;
    } else if #[cfg(getrandom_backend = "linux_raw")] {
        mod linux_raw;
        pub use linux_raw::*;
    } else if #[cfg(getrandom_backend = "rdrand")] {
        mod rdrand;
        pub use rdrand::*;
    } else if #[cfg(getrandom_backend = "rndr")] {
        mod rndr;
        pub use rndr::*;
    } else if #[cfg(getrandom_backend = "efi_rng")] {
        mod efi_rng;
        pub use efi_rng::*;
    } else if #[cfg(getrandom_backend = "windows_legacy")] {
        mod windows_legacy;
        pub use windows_legacy::*;
    } else if #[cfg(getrandom_backend = "unsupported")] {
        mod unsupported;
        pub use unsupported::*;
    } else if #[cfg(getrandom_backend = "extern_impl")] {
        pub(crate) mod extern_impl;
        pub use extern_impl::*;
    } else if #[cfg(all(target_os = "linux", target_env = ""))] {
        mod linux_raw;
        pub use linux_raw::*;
    } else if #[cfg(target_os = "espidf")] {
        mod esp_idf;
        pub use esp_idf::*;
    } else if #[cfg(any(
        target_os = "haiku",
        target_os = "redox",
        target_os = "nto",
        target_os = "aix",
    ))] {
        mod use_file;
        pub use use_file::*;
    } else if #[cfg(any(
        target_os = "macos",
        target_os = "openbsd",
        target_os = "vita",
        target_os = "emscripten",
    ))] {
        mod getentropy;
        pub use getentropy::*;
    } else if #[cfg(any(
        // Rust supports Android API level 19 (KitKat) [0] and the next upgrade targets
        // level 21 (Lollipop) [1], while `getrandom(2)` was added only in
        // level 23 (Marshmallow). Note that it applies only to the "old" `target_arch`es,
        // RISC-V Android targets sufficiently new API level, same will apply for potential
        // new Android `target_arch`es.
        // [0]: https://blog.rust-lang.org/2023/01/09/android-ndk-update-r25.html
        // [1]: https://github.com/rust-lang/rust/pull/120593
        all(
            target_os = "android",
            any(
                target_arch = "aarch64",
                target_arch = "arm",
                target_arch = "x86",
                target_arch = "x86_64",
            ),
        ),
        // Only on these `target_arch`es Rust supports Linux kernel versions (3.2+) 
        // that precede the version (3.17) in which `getrandom(2)` was added:
        // https://doc.rust-lang.org/stable/rustc/platform-support.html
        all(
            target_os = "linux",
            any(
                target_arch = "aarch64",
                target_arch = "arm",
                target_arch = "powerpc",
                target_arch = "powerpc64",
                target_arch = "s390x",
                target_arch = "x86",
                target_arch = "x86_64",
                // Minimum supported Linux kernel version for MUSL targets
                // is not specified explicitly (as of Rust 1.77) and they
                // are used in practice to target pre-3.17 kernels.
                all(
                    target_env = "musl",
                    not(
                        any(
                            target_arch = "riscv64",
                            target_arch = "riscv32",
                        ),
                    ),
                ),
            ),
        )
    ))] {
        mod use_file;
        mod linux_android_with_fallback;
        pub use linux_android_with_fallback::*;
    } else if #[cfg(any(
        target_os = "android",
        target_os = "linux",
        target_os = "dragonfly",
        target_os = "freebsd",
        target_os = "hurd",
        target_os = "illumos",
        target_os = "cygwin",
        // Check for target_arch = "arm" to only include the 3DS. Does not
        // include the Nintendo Switch (which is target_arch = "aarch64").
        all(target_os = "horizon", target_arch = "arm"),
    ))] {
        mod getrandom;
        pub use getrandom::*;
    } else if #[cfg(target_os = "solaris")] {
        mod solaris;
        pub use solaris::*;
    }
}
```

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

### SysRng as Rng with UnwrapErr

Source: https://docs.rs/getrandom/latest/getrandom/struct.SysRng.html

Shows how to use SysRng as a standard Rng by wrapping it with UnwrapErr, allowing for direct calls to methods like next_u64.

```rust
use getrandom::rand_core::{Rng, UnwrapErr};
use getrandom::SysRng;

let mut rng = UnwrapErr(SysRng);
let random_u64 = rng.next_u64();
```

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

### Motor (x86_64) Backend Selection

Source: https://docs.rs/getrandom/latest/src/getrandom/backends.rs.html

Selects the rdrand backend for x86_64 architecture on the 'motor' OS.

```rust
else if #[cfg(all(target_arch = "x86_64", target_os = "motor"))] {
        mod rdrand;
        pub use rdrand::*
    }
```

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

### fill

Source: https://docs.rs/getrandom/latest/getrandom/fn.fill.html

Fills the provided mutable byte slice `dest` with random bytes from the system's preferred random number source. Returns an error on any failure. If the slice is empty, it returns success immediately.

```APIDOC
## fill

### Description
Fills `dest` with random bytes from the system’s preferred random number source. This function returns an error on any failure, including partial reads. No guarantees are made regarding the contents of `dest` on error. If `dest` is empty, `getrandom` immediately returns success, making no calls to the underlying operating system. Blocking is possible, at least during early boot.

### Signature
```rust
pub fn fill(dest: &mut [u8]) -> Result<(), Error>
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **dest** (`&mut [u8]`) - Required - A mutable slice of bytes to be filled with random data.

### Response
#### Success Response
- `Ok(())` - Indicates that the destination slice was successfully filled with random bytes.

#### Error Response
- `Err(Error)` - Indicates a failure occurred during the random byte generation process.

### Example
```rust
let mut buf = [0u8; 32];
getrandom::fill(&mut buf)?;
```
```

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

### Error Constant: UNSUPPORTED

Source: https://docs.rs/getrandom/latest/getrandom/struct.Error.html

Represents an error indicating that the target platform is not supported by the getrandom crate.

```rust
pub const UNSUPPORTED: Error
```

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

### Platform-Specific Error Code Handling

Source: https://docs.rs/getrandom/latest/src/getrandom/error.rs.html

This snippet demonstrates how the getrandom crate handles error codes differently based on the target operating system. It covers UEFI, POSIX-like systems, and the specific case of Solid.

```rust
#[cfg(target_os = "uefi")]
{
    if code & UEFI_ERROR_FLAG != 0 {
        Some(code)
    } else {
        None
    }
}

#[cfg(not(target_os = "uefi"))]
{
    // On most targets `std` expects positive error codes while retrieving error strings:
    // - `libc`-based targets use `strerror_r` which expects positive error codes.
    // - Hermit relies on the `hermit-abi` crate, which expects positive error codes:
    //   https://docs.rs/hermit-abi/0.4.0/src/hermit_abi/errno.rs.html#400-532
    // - WASIp1 uses the same conventions as `libc`:
    //   https://github.com/rust-lang/rust/blob/1.85.0/library/std/src/sys/pal/wasi/os.rs#L57-L67
    //
    // The only exception is Solid, `std` expects negative system error codes, see:
    // https://github.com/rust-lang/rust/blob/1.85.0/library/std/src/sys/pal/solid/error.rs#L5-L31
    if code >= 0 {
        None
    } else if cfg!(not(target_os = "solid_asp3")) {
        code.checked_neg()
    } else {
        Some(code)
    }
}
```

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

### Default Implementation: inner_u32

Source: https://docs.rs/getrandom/latest/src/getrandom/util.rs.html

Provides a default implementation for generating a u32 using `fill_uninit`. It initializes a MaybeUninit<u32> and fills it with random bytes.

```rust
#![allow(dead_code)]
use crate::Error;
use core::{mem::MaybeUninit, ptr, slice};

/// Default implementation of `inner_u32` on top of `fill_uninit`
#[inline]
pub fn inner_u32() -> Result<u32, Error> {
    let mut res = MaybeUninit::<u32>::uninit();
    // SAFETY: the created slice has the same size as `res`
    let dst = unsafe {
        let p: *mut MaybeUninit<u8> = res.as_mut_ptr().cast();
        slice::from_raw_parts_mut(p, core::mem::size_of::<u32>())
    };
    crate::fill_uninit(dst)?;
    // SAFETY: `dst` has been fully initialized by `imp::fill_inner`
    // since it returned `Ok`.
    Ok(unsafe { res.assume_init() })
}
```

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

### Fuchsia Backend Selection

Source: https://docs.rs/getrandom/latest/src/getrandom/backends.rs.html

Selects the Fuchsia specific backend for random number generation.

```rust
else if #[cfg(target_os = "fuchsia")] {
        mod fuchsia;
        pub use fuchsia::*
    }
```

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

### Fill Byte Buffer with Random Data

Source: https://docs.rs/getrandom/latest/getrandom

Invoke the `fill` function on a byte buffer to populate it with random data obtained from the system's random number generator. This function returns a Result, indicating success or a getrandom::Error.

```rust
fn get_random_u128() -> Result<u128, getrandom::Error> {
    let mut buf = [0u8; 16];
    getrandom::fill(&mut buf)?;
    Ok(u128::from_ne_bytes(buf))
}
```

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

### fill

Source: https://docs.rs/getrandom/latest/getrandom

Fills a mutable byte slice with random data from the system's random number source.

```APIDOC
## fill

### Description
Fill `dest` with random bytes from the system’s preferred random number source.

### Function Signature
`pub fn fill(dest: &mut [u8]) -> Result<(), Error>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (Ok)
`()` - Indicates the buffer was successfully filled.

#### Error Response (Err)
`Error` - An error occurred while trying to fill the buffer.

### Response Example
None
```

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

### fill

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

Fills a mutable byte slice with random bytes from the system's preferred random number source. It returns an error on any failure and guarantees no partial reads on error. An empty slice results in immediate success.

```APIDOC
## fill

### Description

Fill `dest` with random bytes from the system's preferred random number source.

This function returns an error on any failure, including partial reads. We
make no guarantees regarding the contents of `dest` on error. If `dest` is
empty, `getrandom` immediately returns success, making no calls to the
underlying operating system.

Blocking is possible, at least during early boot; see module documentation.

In general, `getrandom` will be fast enough for interactive usage, though
significantly slower than a user-space CSPRNG; for the latter consider
[`rand::thread_rng`](https://docs.rs/rand/*/rand/fn.thread_rng.html).

### Method

```rust
pub fn fill(dest: &mut [u8]) -> Result<(), Error>
```

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

None

### Request Example

```rust
let mut buf = [0u8; 32];
getrandom::fill(&mut buf)?;
```

### Response

#### Success Response

Returns `Ok(())` on successful completion.

#### Response Example

```rust
Ok(())
```

#### Error Response

Returns `Err(Error)` on failure. The specific error type can be inspected.

```

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

### Declare External u64 Implementation

Source: https://docs.rs/getrandom/latest/getrandom/implementation/attr.u64.html

Use the #[u64] attribute macro to mark a function as an external implementation for u64. This is only available when the getrandom_backend feature is set to extern_impl.

```Rust
#[u64]
```

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

### Wasm32-unknown-unknown with JS Feature

Source: https://docs.rs/getrandom/latest/src/getrandom/backends.rs.html

Handles the wasm32-unknown-unknown target, enabling the 'wasm_js' feature for browser environments. If the feature is not enabled, it provides a compile-time error.

```rust
else if #[cfg(all(target_arch = "wasm32", any(target_os = "unknown", target_os = "none")))] {
        cfg_if! {
            if #[cfg(feature = "wasm_js")] {
                mod wasm_js;
                pub use wasm_js::*
            } else {
                compile_error!(concat("The wasm32-unknown-unknown targets are not supported by default; \you may need to enable the \"wasm_js\" crate feature. \For more information see: \https://docs.rs/getrandom/", env!("CARGO_PKG_VERSION"), "/#webassembly-support")
            }
        }
    }
```

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

### From<Error> for Error Implementation

Source: https://docs.rs/getrandom/latest/getrandom/struct.Error.html

Shows the `From<getrandom::Error> for std::io::Error` conversion, available when the `std` Cargo feature is enabled.

```rust
fn from(err: Error) -> Self
```

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

### StructuralPartialEq Implementation

Source: https://docs.rs/getrandom/latest/getrandom/struct.Error.html

Shows the `StructuralPartialEq` trait implementation for the `Error` struct.

```rust
impl StructuralPartialEq for Error
```

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

### Implementing Display for Error

Source: https://docs.rs/getrandom/latest/src/getrandom/error.rs.html

Implements the `Display` trait for the `Error` enum. This allows errors to be formatted into human-readable strings, handling OS errors, internal descriptions, or unknown errors.

```rust
impl fmt::Display for Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        if let Some(errno) = self.raw_os_error() {
            cfg_if! {
                if #[cfg(feature = "std")] {
                    std::io::Error::from_raw_os_error(errno).fmt(f)
                } else {
                    write!(f, "OS Error: {errno}")
                }
            }
        } else if let Some(desc) = self.internal_desc() {
            f.write_str(desc)
        } else {
            write!(f, "Unknown Error: {}", self.0.get())
        }
    }
}
```

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

### Clone Implementation

Source: https://docs.rs/getrandom/latest/getrandom/struct.Error.html

Demonstrates the `Clone` trait implementation for the `Error` struct, allowing for duplication of error values.

```rust
fn clone(&self) -> Error
```

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

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

### raw_os_error() Method

Source: https://docs.rs/getrandom/latest/getrandom/struct.Error.html

Extracts the raw OS error code if the error originated from the operating system. Returns None if the error is not OS-related. The return type may vary across platforms (e.g., i32, usize).

```rust
pub fn raw_os_error(self) -> Option<RawOsError>
```

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

### Declare External fill_uninit Implementation

Source: https://docs.rs/getrandom/latest/getrandom/implementation/attr.fill_uninit.html

Use the `#[fill_uninit]` attribute macro to declare a function as an external implementation of `fill_uninit`. This is restricted to backends that support external implementations, such as `getrandom_backend=extern_impl`.

```rust
#[fill_uninit]

```

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

### new_custom() Method

Source: https://docs.rs/getrandom/latest/getrandom/struct.Error.html

Creates a new `Error` instance from a specific custom error code. This is useful for defining custom error conditions.

```rust
pub const fn new_custom(n: u16) -> Error
```

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

### Unsafe Helper: slice_as_uninit

Source: https://docs.rs/getrandom/latest/src/getrandom/util.rs.html

Converts a slice of initialized elements into a slice of potentially uninitialized elements. This is an unsafe operation.

```rust
#![allow(dead_code)]
use crate::Error;
use core::{mem::MaybeUninit, ptr, slice};

#[inline(always)]
pub fn slice_as_uninit<T>(slice: &[T]) -> &[MaybeUninit<T>] {
    let ptr = ptr::from_ref(slice) as *const [MaybeUninit<T>];
    // SAFETY: `MaybeUninit<T>` is guaranteed to be layout-compatible with `T`.
    unsafe { &*ptr }
}
```

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

### Auto Trait Implementations

Source: https://docs.rs/getrandom/latest/getrandom/struct.Error.html

Lists the auto trait implementations for `getrandom::Error`, including `Freeze`, `RefUnwindSafe`, `Send`, `Sync`, `Unpin`, `UnsafeUnpin`, and `UnwindSafe`.

```rust
impl Freeze for Error
```

```rust
impl RefUnwindSafe for Error
```

```rust
impl Send for Error
```

```rust
impl Sync for Error
```

```rust
impl Unpin for Error
```

```rust
impl UnsafeUnpin for Error
```

```rust
impl UnwindSafe for Error
```

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

### SysRng

Source: https://docs.rs/getrandom/latest/getrandom

Represents a random number source using the system's preferred RNG.

```APIDOC
## SysRng

### Description
A `TryRng` interface over the system’s preferred random number source.

### Struct Definition
`pub struct SysRng`

### Methods
This struct likely implements methods from the `TryRng` trait, such as `try_rng()`.

### Example Usage
```rust
use getrandom::SysRng;

let mut rng = SysRng;
// Use rng to generate random numbers
```
```

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

### Describing Internal Errors

Source: https://docs.rs/getrandom/latest/src/getrandom/error.rs.html

This method provides a static string description for various internal error codes used by the getrandom crate. It includes platform-specific and backend-specific error messages.

```rust
fn internal_desc(&self) -> Option<&'static str> {
    let desc = match *self {
        Error::UNSUPPORTED => "getrandom: this target is not supported",
        Error::ERRNO_NOT_POSITIVE => "errno: did not return a positive value",
        Error::UNEXPECTED => "unexpected situation",
        #[cfg(any(
            target_os = "ios",
            target_os = "visionos",
            target_os = "watchos",
            target_os = "tvos",
        ))]
        Error::IOS_RANDOM_GEN => "SecRandomCopyBytes: iOS Security framework failure",
        #[cfg(all(windows, target_vendor = "win7"))]
        Error::WINDOWS_RTL_GEN_RANDOM => "RtlGenRandom: Windows system function failure",
        #[cfg(all(
            feature = "wasm_js",
            target_arch = "wasm32",
            any(target_os = "unknown", target_os = "none")
        ))]
        Error::WEB_CRYPTO => "Web Crypto API is unavailable",
        #[cfg(target_os = "vxworks")]
        Error::VXWORKS_RAND_SECURE => "randSecure: VxWorks RNG module is not initialized",

        #[cfg(any(
            getrandom_backend = "rdrand",
            all(target_arch = "x86_64", target_env = "sgx")
        ))]
        Error::FAILED_RDRAND => "RDRAND: failed multiple times: CPU issue likely",
        #[cfg(any(
            getrandom_backend = "rdrand",
            all(target_arch = "x86_64", target_env = "sgx")
        ))]
        Error::NO_RDRAND => "RDRAND: instruction not supported",

        #[cfg(getrandom_backend = "rndr")]
        Error::RNDR_FAILURE => "RNDR: Could not generate a random number",
        #[cfg(getrandom_backend = "rndr")]
        Error::RNDR_NOT_AVAILABLE => "RNDR: Register not supported",
        _ => return None,
    };
    Some(desc)
}
```

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

### Custom Backend Function Signature

Source: https://docs.rs/getrandom/latest/getrandom

Define the required signature for a custom random data generation function for the getrandom crate.

```rust
use getrandom::Error;

#[unsafe(no_mangle)]
unsafe extern "Rust" fn __getrandom_v03_custom(
    dest: *mut u8,
    len: usize,
) -> Result<(), Error> {
    todo!()
}
```

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

### VxWorks Backend Selection

Source: https://docs.rs/getrandom/latest/src/getrandom/backends.rs.html

Selects the VxWorks specific backend for random number generation.

```rust
else if #[cfg(target_os = "vxworks")] {
        mod vxworks;
        pub use vxworks::*
    }
```

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

### Unsafe Helper: uninit_slice_fill_zero

Source: https://docs.rs/getrandom/latest/src/getrandom/util.rs.html

Fills a mutable slice of MaybeUninit<u8> with zeros and returns a mutable slice of u8. This is an unsafe operation.

```rust
#![allow(dead_code)]
use crate::Error;
use core::{mem::MaybeUninit, ptr, slice};

#[inline]
pub fn uninit_slice_fill_zero(slice: &mut [MaybeUninit<u8>]) -> &mut [u8] {
    unsafe { ptr::write_bytes(slice.as_mut_ptr(), 0, slice.len()) };
    unsafe { slice_assume_init_mut(slice) }
}
```

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

### Generic Blanket Implementations

Source: https://docs.rs/getrandom/latest/getrandom/struct.Error.html

Lists generic blanket implementations for `getrandom::Error`, such as `Any`, `Borrow`, `BorrowMut`, `CloneToUninit`, `From<T>`, `Into<U>`, and `ToOwned`.

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

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

```rust
impl<T> Borrow<T>
where T: ?Sized,
```

```rust
fn borrow(&self) -> &T
```

```rust
impl<T> BorrowMut<T>
where T: ?Sized,
```

```rust
fn borrow_mut(&mut self) -> &mut T
```

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

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

```rust
impl<T> From<T> for T
```

```rust
fn from(t: T) -> T
```

```rust
impl<T, U> Into<U>
where U: From<T>,
```

```rust
fn into(self) -> U
```

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

```rust
type Owned = T
```

```rust
fn to_owned(&self) -> T
```

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

### u32

Source: https://docs.rs/getrandom/latest/getrandom

Retrieves a random 32-bit unsigned integer from the system's random number source.

```APIDOC
## u32

### Description
Get random `u32` from the system’s preferred random number source.

### Function Signature
`pub fn u32() -> u32`

### Parameters
None

### Request Example
None

### Response
#### Success Response
`u32` - A random 32-bit unsigned integer.

### Response Example
None
```

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

### Error

Source: https://docs.rs/getrandom/latest/getrandom

A no_std compatible error type for getrandom operations.

```APIDOC
## Error

### Description
A small and `no_std` compatible error type.

### Enum Definition
`pub enum Error`

### Variants
This enum likely contains variants such as `UNEXPECTED` and others to represent different error conditions.

### Example Usage
```rust
use getrandom::Error;

match getrandom::fill(&mut [0u8; 10]) {
    Ok(_) => println!("Success"),
    Err(Error::UNEXPECTED) => println!("Unexpected error"),
    Err(_) => println!("Other error"),
}
```
```

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

### Declare External u32 Implementation

Source: https://docs.rs/getrandom/latest/getrandom/implementation/attr.u32.html

Use the #[u32] attribute macro to mark a function as an external implementation of u32. This is restricted to the `extern_impl` backend.

```rust
#[u32]
```

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

### Creating a Custom Error

Source: https://docs.rs/getrandom/latest/src/getrandom/error.rs.html

This function creates a new `Error` instance from a custom error code. It's used for application-specific error reporting.

```rust
pub const fn new_custom(n: u16) -> Error {
    // SAFETY: code > 0 as CUSTOM_START > 0 and adding `n` won't overflow `RawOsError`.
    let code = Error::CUSTOM_START + (n as RawOsError);
    Error(unsafe { NonZeroRawOsError::new_unchecked(code) })
}
```

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

### u32

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

Retrieves a random 32-bit unsigned integer from the system's preferred random number source.

```APIDOC
## u32

### Description

Get random `u32` from the system's preferred random number source.

### Method

```rust
pub fn u32() -> Result<u32, Error>
```

### Parameters

None

### Request Example

```rust
let rng_seed = getrandom::u32()?;
```

### Response

#### Success Response

Returns `Ok(u32)` containing a random 32-bit unsigned integer.

#### Response Example

```rust
# fn main() -> Result<(), getrandom::Error> {
let rng_seed = getrandom::u32()?;
# Ok(())
# }
```

#### Error Response

Returns `Err(Error)` on failure. The specific error type can be inspected.

```

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

### Error Constant: ERRNO_NOT_POSITIVE

Source: https://docs.rs/getrandom/latest/getrandom/struct.Error.html

Represents an error where the platform-specific errno returned a non-positive value.

```rust
pub const ERRNO_NOT_POSITIVE: Error
```

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

### Error Constant: UNEXPECTED

Source: https://docs.rs/getrandom/latest/getrandom/struct.Error.html

Represents an error for an unexpected situation that should not occur in practice.

```rust
pub const UNEXPECTED: Error
```

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

### getrandom::u64

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

Generates a random 64-bit unsigned integer. This function is a public API provided by the getrandom library.

```APIDOC
## fn u64() -> Result<u64, Error>

### Description
Generates a random 64-bit unsigned integer. This function is a public API provided by the getrandom library.

### Method
Rust Function Call

### Signature
`pub fn u64() -> Result<u64, Error>`

### Returns
A `Result` which contains a `u64` on success, or a `getrandom::Error` on failure.
```
Tokens:
Raw