Merge branch 'sysselect-func-doc' into 'master'

add descriptions to sys_select functions

See merge request redox-os/relibc!1486

src/header/sys_select/cbindgen.toml

@@ -23,9 +23,13 @@ typedef struct {
     unsigned long fds_bits[FD_SETSIZE / 8 / sizeof(long)];
 } fd_set;
 
+// Initializes the descriptor set pointed to by `s` to the null set.
 #define FD_ZERO(s) do { int __i; unsigned long *__b=(s)->fds_bits; for(__i=sizeof (fd_set)/sizeof (long); __i; __i--) *__b++=0; } while(0)
+// Adds the file descriptor `d` to the set pointed to by `s`.
 #define FD_SET(d, s)   ((s)->fds_bits[(d)/(8*sizeof(long))] |= (1UL<<((d)%(8*sizeof(long)))))
+// Removes the file descriptor `d` from the set pointed to by `s`.
 #define FD_CLR(d, s)   ((s)->fds_bits[(d)/(8*sizeof(long))] &= ~(1UL<<((d)%(8*sizeof(long)))))
+// Evaluates to non-zero if the file descriptor `d` is a member of the set pointed to by `s`, otherwise evaluates to zero.
 #define FD_ISSET(d, s) !!((s)->fds_bits[(d)/(8*sizeof(long))] & (1UL<<((d)%(8*sizeof(long)))))
 
 #if defined(_GNU_SOURCE) || defined(_BSD_SOURCE)

src/header/sys_select/mod.rs

@@ -25,6 +25,8 @@ pub use crate::header::bits_timeval::timeval;
 // FD_SETSIZE and fd_set is also defined in C because cbindgen is incompatible with mem::size_of
 
 /// See <https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/sys_select.h.html>.
+///
+/// Maximum number of file descriptors in an `fd_set` structure.
 /// cbindgen:ignore
 pub const FD_SETSIZE: usize = 1024;
 type FdBitSet = BitSet<[u64; FD_SETSIZE / (8 * mem::size_of::<u64>())]>;
@@ -179,6 +181,18 @@ pub unsafe fn select_epoll(
 }
 
 /// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/select.html>.
+///
+/// Examines the file descriptor sets whose addresses are passed in the
+/// `readfds`, `writefds` and `errorfds` parameters to see whether some of
+/// their descriptors are ready for reading, ready for writing, or have an
+/// exceptional condition pending, respectively.
+///
+/// `timeout` is given in seconds and microseconds as represented by `timeval`.
+/// Behaves as `pselect()` does when `sigmask` is a null pointer. When
+/// successful, may modify the object pointed to by `timeout`.
+///
+/// Upon success, returns the total number of bits set in the bit masks. Upon
+/// failure, returns `-1` and sets errno to indicate the error.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn select(
     nfds: c_int,
@@ -224,6 +238,16 @@ pub unsafe extern "C" fn select(
 }
 
 /// See <https://pubs.opengroup.org/onlinepubs/9799919799/functions/pselect.html>.
+///
+/// Examines the file descriptor sets whose addresses are passed in the
+/// `readfds`, `writefds` and `errorfds` parameters to see whether some of
+/// their descriptors are ready for reading, ready for writing, or have an
+/// exceptional condition pending, respectively.
+///
+/// `timeout` is given in seconds and nanoseconds as represented by `timespec`.
+///
+/// Upon success, returns the total number of bits set in the bit masks. Upon
+/// failure, returns `-1` and sets errno to indicate the error.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn pselect(
     nfds: c_int,