Skip to content

Commit d2ddafb

Browse files
authored
Improve docs for the custom backend (#550)
1 parent a5bc5fe commit d2ddafb

File tree

1 file changed

+25
-0
lines changed

1 file changed

+25
-0
lines changed

README.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -169,6 +169,31 @@ data and its length in bytes. Note that the buffer MAY be uninitialized.
169169
On success, the function should return `Ok(())` and fully fill the input buffer;
170170
otherwise, it should return an error value.
171171

172+
While wrapping functions which work with byte slices you should fully initialize
173+
the buffer before passing it to the function:
174+
```rust
175+
use getrandom::Error;
176+
177+
fn my_entropy_source(buf: &mut [u8]) -> Result<(), getrandom::Error> {
178+
// ...
179+
Ok(())
180+
}
181+
182+
#[no_mangle]
183+
unsafe extern "Rust" fn __getrandom_v03_custom(
184+
dest: *mut u8,
185+
len: usize,
186+
) -> Result<(), Error> {
187+
let buf = unsafe {
188+
// fill the buffer with zeros
189+
core::ptr::write_bytes(dest, 0, len);
190+
// create mutable byte slice
191+
core::slice::from_raw_parts_mut(dest, len)
192+
};
193+
my_entropy_source(buf)
194+
}
195+
```
196+
172197
If you are confident that `getrandom` is not used in your project, but
173198
it gets pulled nevertheless by one of your dependencies, then you can
174199
use the following custom backend, which always returns the "unsupported" error:

0 commit comments

Comments
 (0)