Merge branch 'utime-docs' into 'master'

Add utime.h docs, use unsafe blocks

See merge request redox-os/relibc!538

src/header/mod.rs

@@ -71,6 +71,7 @@ pub mod sys_wait;
 pub mod termios;
 pub mod time;
 pub mod unistd;
+#[deprecated]
 pub mod utime;
 pub mod utmp;
 pub mod wchar;

src/header/utime/mod.rs

@@ -1,4 +1,12 @@
-//! utime implementation for Redox, following http://pubs.opengroup.org/onlinepubs/7908799/xsh/utime.h.html
+//! `utime.h` implementation.
+//!
+//! See <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/utime.h.html>.
+//!
+//! The `utime.h` header was marked obsolescent in the Open Group Base
+//! Specifications Issue 7, and removed in Issue 8.
+
+// TODO: set this for entire crate when possible
+#![deny(unsafe_op_in_unsafe_fn)]
 
 use crate::{
     c_str::CStr,
@@ -7,6 +15,8 @@ use crate::{
     platform::{types::*, Pal, Sys},
 };
 
+/// See <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/utime.h.html>.
+#[deprecated]
 #[repr(C)]
 #[derive(Clone)]
 pub struct utimbuf {
@@ -14,20 +24,23 @@ pub struct utimbuf {
     pub modtime: time_t,
 }
 
+/// See <https://pubs.opengroup.org/onlinepubs/9699919799/functions/utime.html>.
+#[deprecated]
 #[no_mangle]
 pub unsafe extern "C" fn utime(filename: *const c_char, times: *const utimbuf) -> c_int {
-    let filename = CStr::from_ptr(filename);
+    let filename_cstr = unsafe { CStr::from_ptr(filename) };
+    let times_ref = unsafe { &*times };
     let times_spec = [
         timespec {
-            tv_sec: (*times).actime,
+            tv_sec: times_ref.actime,
             tv_nsec: 0,
         },
         timespec {
-            tv_sec: (*times).modtime,
+            tv_sec: times_ref.modtime,
             tv_nsec: 0,
         },
     ];
-    Sys::utimens(filename, times_spec.as_ptr())
+    unsafe { Sys::utimens(filename_cstr, times_spec.as_ptr()) }
         .map(|()| 0)
         .or_minus_one_errno()
 }