Merge branch 'utime-doc' into 'master'

add descriptions to utime header

See merge request redox-os/relibc!1503

src/header/utime/cbindgen.toml

@@ -1,3 +1,8 @@
+# POSIX header spec (obsolete): https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/utime.h.html
+#
+# Spec quotations relating to includes:
+# - "The <utime.h> header shall define the time_t type as described in <sys/types.h>."
+#
 # features included for deprecated annotations
 sys_includes = ["features.h"]
 after_includes = """

src/header/utime/mod.rs

@@ -16,20 +16,38 @@ use crate::{
 };
 
 /// See <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/utime.h.html>.
+///
+/// A structure representing both access and modification times in seconds.
+///
+/// Times are measured in seconds since the Epoch.
 #[deprecated]
 #[repr(C)]
 #[derive(Clone)]
 pub struct utimbuf {
+    /// Access time.
     pub actime: time_t,
+    /// Modification time.
     pub modtime: time_t,
 }
 
 /// See <https://pubs.opengroup.org/onlinepubs/9699919799/functions/utime.html>.
+///
+/// Sets the access and modification times of the file named by the `path`
+/// argument.
+///
+/// Upon success, returns `0`. Upon failure, returns `-1`, sets errno to
+/// indicate the error, and the file times shall not be affected.
+///
+/// # Deprecated
+/// Marked obsolete in issue 7, removed in issue 8.
+///
+/// Should use `utimensat()` instead for greater accuracy because `utimebuf`
+/// uses `time_t` which represents whole seconds only.
 #[deprecated]
-#[allow(deprecated)]
+#[expect(deprecated, reason = "utimbuf struct")]
 #[unsafe(no_mangle)]
-pub unsafe extern "C" fn utime(filename: *const c_char, times: *const utimbuf) -> c_int {
-    let filename_cstr = unsafe { CStr::from_ptr(filename) };
+pub unsafe extern "C" fn utime(path: *const c_char, times: *const utimbuf) -> c_int {
+    let filename_cstr = unsafe { CStr::from_ptr(path) };
     let times_ref = unsafe { &*times };
     let times_spec = [
         timespec {