Rename to sys_fill_exact and add docs

Author: josephlr

src/freebsd.rs

@@ -7,7 +7,7 @@
 // except according to those terms.
 
 //! Implementation for FreeBSD
-use crate::util_libc::{fill_exact, Weak};
+use crate::util_libc::{sys_fill_exact, Weak};
 use crate::Error;
 use core::num::NonZeroU32;
 use core::{mem, ptr};
@@ -39,9 +39,9 @@ pub fn getrandom_inner(dest: &mut [u8]) -> Result<(), Error> {
     static GETRANDOM: Weak = unsafe { Weak::new("getrandom\0") };
     if let Some(fptr) = GETRANDOM.ptr() {
         let func: GetRandomFn = unsafe { mem::transmute(fptr) };
-        fill_exact(dest, |buf| unsafe { func(buf.as_mut_ptr(), buf.len(), 0) })
+        sys_fill_exact(dest, |buf| unsafe { func(buf.as_mut_ptr(), buf.len(), 0) })
     } else {
-        fill_exact(dest, kern_arnd)
+        sys_fill_exact(dest, kern_arnd)
     }
 }
 

src/linux_android.rs

@@ -10,15 +10,15 @@
 extern crate std;
 
 use crate::util::LazyBool;
-use crate::util_libc::fill_exact;
+use crate::util_libc::sys_fill_exact;
 use crate::{use_file, Error};
 use core::num::NonZeroU32;
 use std::io;
 
 pub fn getrandom_inner(dest: &mut [u8]) -> Result<(), Error> {
     static HAS_GETRANDOM: LazyBool = LazyBool::new();
     if HAS_GETRANDOM.unsync_init(is_getrandom_available) {
-        fill_exact(dest, |buf| unsafe {
+        sys_fill_exact(dest, |buf| unsafe {
             libc::syscall(libc::SYS_getrandom, buf.as_mut_ptr(), buf.len(), 0) as libc::ssize_t
         })
     } else {

src/solaris_illumos.rs

@@ -17,7 +17,7 @@
 //! To make sure we can compile on both Solaris and its derivatives, as well as
 //! function, we check for the existance of getrandom(2) in libc by calling
 //! libc::dlsym.
-use crate::util_libc::{fill_exact, Weak};
+use crate::util_libc::{sys_fill_exact, Weak};
 use crate::{use_file, Error};
 use core::mem;
 use core::num::NonZeroU32;
@@ -34,7 +34,7 @@ pub fn getrandom_inner(dest: &mut [u8]) -> Result<(), Error> {
         // 256 bytes is the lowest common denominator across all the Solaris
         // derived platforms for atomically obtaining random data.
         for chunk in dest.chunks_mut(256) {
-            fill_exact(chunk, |buf| unsafe {
+            sys_fill_exact(chunk, |buf| unsafe {
                 func(buf.as_mut_ptr(), buf.len(), 0) as libc::ssize_t
             })?
         }

src/util_libc.rs

@@ -12,9 +12,15 @@ use crate::Error;
 use core::ptr::NonNull;
 use std::io;
 
-pub fn fill_exact(mut buf: &mut [u8], f: impl Fn(&mut [u8]) -> libc::ssize_t) -> Result<(), Error> {
+// Fill a buffer by repeatedly invoking a system call. The `sys_fill` function:
+//   - should return -1 and set errno on failure
+//   - should return the number of bytes written on success
+pub fn sys_fill_exact(
+    mut buf: &mut [u8],
+    sys_fill: impl Fn(&mut [u8]) -> libc::ssize_t,
+) -> Result<(), Error> {
     while !buf.is_empty() {
-        let res = f(buf);
+        let res = sys_fill(buf);
         if res < 0 {
             let err = io::Error::last_os_error();
             // We should try again if the call was interrupted.