From 60e301360cf8fb7e55e3054562f385fbecf0fb5a Mon Sep 17 00:00:00 2001
From: auronandace <auronandace@googlemail.com>
Date: Sun, 14 Jun 2026 14:18:25 +0100
Subject: [PATCH] add descriptions to sys_uio functions and associated unistd
 functions

---
 src/header/sys_uio/mod.rs | 23 +++++++++++++++++++++++
 src/header/unistd/mod.rs  | 26 ++++++++++++++++++++++++++
 2 files changed, 49 insertions(+)

diff --git a/src/header/sys_uio/mod.rs b/src/header/sys_uio/mod.rs
index 6996f10c1e..fc52159a24 100644
--- a/src/header/sys_uio/mod.rs
+++ b/src/header/sys_uio/mod.rs
@@ -15,6 +15,11 @@ use crate::{
 pub use crate::header::bits_iovec::{gather, iovec, scatter};
 
 /// Non-POSIX, see <https://man7.org/linux/man-pages/man2/readv.2.html>.
+///
+/// Combines the functionality of `readv()` and `pread()`.
+///
+/// When successful, returns a non-negative number indicating the number of
+/// bytes actually read. Upon failure, returns `-1`.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn preadv(
     fd: c_int,
@@ -38,6 +43,11 @@ pub unsafe extern "C" fn preadv(
 }
 
 /// Non-POSIX, see <https://man7.org/linux/man-pages/man2/readv.2.html>.
+///
+/// Combined the functionality of `writev()` and `pwrite()`.
+///
+/// When successful, returns a non-negative number indicating the number of
+/// bytes actually written. Upon failure, returns `-1`.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn pwritev(
     fd: c_int,
@@ -57,6 +67,12 @@ pub unsafe extern "C" fn pwritev(
 }
 
 /// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/readv.html>.
+///
+/// Equivalent to `read()` but places the input data into the `iovcnt` buffers
+/// specified by the members of the `iov` array.
+///
+/// When successful, returns a non-negative number indicating the number of
+/// bytes actually read. Upon failure, returns `-1`.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn readv(fd: c_int, iov: *const iovec, iovcnt: c_int) -> ssize_t {
     if !(0..=IOV_MAX).contains(&iovcnt) {
@@ -75,6 +91,13 @@ pub unsafe extern "C" fn readv(fd: c_int, iov: *const iovec, iovcnt: c_int) -> s
 }
 
 /// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/writev.html>.
+///
+/// Equivalent to `write()` but shall gather output data from the `iovcnt`
+/// buffers specified by the members of the `iov` array.
+///
+/// When successful, returns a non-negative number indicating the number of
+/// bytes actually written to the file associated with `fildes`. Upon failure,
+/// returns `-1`.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn writev(fd: c_int, iov: *const iovec, iovcnt: c_int) -> ssize_t {
     if !(0..=IOV_MAX).contains(&iovcnt) {
diff --git a/src/header/unistd/mod.rs b/src/header/unistd/mod.rs
index 14e5a18dbe..f9e041224b 100644
--- a/src/header/unistd/mod.rs
+++ b/src/header/unistd/mod.rs
@@ -864,6 +864,12 @@ pub extern "C" fn posix_close(fildes: c_int, flag: c_int) -> c_int {
 }
 
 /// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/read.html>.
+///
+/// Equivalent to `read()`, except that it shall read from a given position in
+/// the file without changing the file offset.
+///
+/// When successful, returns a non-negative number indicating the number of
+/// bytes actually read. Upon failure, returns `-1`.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn pread(
     fildes: c_int,
@@ -881,6 +887,13 @@ pub unsafe extern "C" fn pread(
 }
 
 /// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/write.html>.
+///
+/// Equivalent to `write()`, except that it writes into a given position and
+/// does not change the file offset (regardless of whether `O_APPEND` is set).
+///
+/// When successful, returns a non-negative number indicating the number of
+/// bytes actually written to the file associated with `fildes`. Upon failure,
+/// returns `-1`.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn pwrite(
     fildes: c_int,
@@ -898,6 +911,12 @@ pub unsafe extern "C" fn pwrite(
 }
 
 /// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/read.html>.
+///
+/// Attempts to read `nbyte` bytes from the file associated with the open file
+/// descriptor, `fildes`, into the buffer pointed to by `buf`.
+///
+/// When successful, returns a non-negative number indicating the number of
+/// bytes actually read. Upon failure, returns `-1`.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn read(fildes: c_int, buf: *mut c_void, nbyte: size_t) -> ssize_t {
     let buf = unsafe { slice::from_raw_parts_mut(buf.cast::<u8>(), nbyte) };
@@ -1295,6 +1314,13 @@ unsafe fn with_argv(
 }
 
 /// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/write.html>.
+///
+/// Attempts to write `nbyte` bytes from the buffer pointed to by `buf` to the
+/// file associated with the open file descriptor, `fildes`.
+///
+/// When successful, returns a non-negative number indicating the number of
+/// bytes actually written to the file associated with `fildes`. Upon failure,
+/// returns `-1`.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn write(fildes: c_int, buf: *const c_void, nbyte: size_t) -> ssize_t {
     let buf = unsafe { slice::from_raw_parts(buf.cast::<u8>(), nbyte) };