[libc] add some posix function comments

2 files changed, 71 insertions, 4 deletions

diff --git a/components/libc/posix/io/poll/select.c b/components/libc/posix/io/poll/select.c
index 864411f072..a239a44a30 100644
--- a/components/libc/posix/io/poll/select.c
+++ b/components/libc/posix/io/poll/select.c
@@ -4,14 +4,21 @@
  * SPDX-License-Identifier: Apache-2.0
  *
  * Change Logs:
- * Date           Author       Notes
- * 2016-12-28     Bernard      first version
+ * Date           Author            Notes
+ * 2016-12-28     Bernard           first version
+ * 2024-04-08     TroyMitchell      Add all function comments
  */
 
 #include <rtthread.h>
 #include <poll.h>
 #include <sys/select.h>
 
+/**
+ * @brief   Initialize the file descriptor set to have zero bits for all file descriptors.
+ * @param   set     Pointer to the file descriptor set to be initialized.
+ * @param   nfds    The maximum file descriptor in the set plus one.
+ * @note    The actual size of the 'fd_set' is determined based on the parameter 'nfds'.
+ */
 static void fdszero(fd_set *set, int nfds)
 {
     fd_mask *m;
@@ -29,6 +36,15 @@ static void fdszero(fd_set *set, int nfds)
     }
 }
 
+/**
+ * @brief   Synchronous I/O multiplexing: multiplex input/output over a set of file descriptors.
+ * @param   nfds        The highest-numbered file descriptor in any of the three sets, plus 1.
+ * @param   readfds     A pointer to a set of file descriptors to be checked for read readiness.
+ * @param   writefds    A pointer to a set of file descriptors to be checked for write readiness.
+ * @param   exceptfds   A pointer to a set of file descriptors to be checked for exceptions.
+ * @param   timeout     The maximum time to wait for any of the specified file descriptors to become ready.
+ * @return  Upon successful completion, the total number of file descriptors in all the sets that are ready for the requested operation is returned; otherwise, -1 is returned on error.
+ */
 int select(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout)
 {
     int fd;
diff --git a/components/libc/posix/io/signalfd/signalfd.c b/components/libc/posix/io/signalfd/signalfd.c
index 735740fafc..b4a08fa946 100644
--- a/components/libc/posix/io/signalfd/signalfd.c
+++ b/components/libc/posix/io/signalfd/signalfd.c
@@ -4,8 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  *
  * Change Logs:
- * Date           Author       Notes
- * 2023-08-29   zmq810150896   first version
+ * Date             Author              Notes
+ * 2023-08-29       zmq810150896        first version
+ * 2024-04-08       TroyMitchell        Add all function comments
  */
 
 #include <rtthread.h>
@@ -50,6 +51,11 @@ static const struct dfs_file_ops signalfd_fops =
     .read       = signalfd_read,
 };
 
+/**
+ * @brief   Closes the file descriptor associated with a signalfd file.
+ * @param   file    Pointer to the file structure.
+ * @return  Upon successful completion, returns 0; otherwise, returns an error code.
+ */
 static int signalfd_close(struct dfs_file *file)
 {
     struct rt_signalfd_ctx *sfd;
@@ -68,6 +74,12 @@ static int signalfd_close(struct dfs_file *file)
     return 0;
 }
 
+/**
+ * @brief   Adds a signalfd file descriptor to the poll queue and checks for pending events.
+ * @param   file    Pointer to the file structure.
+ * @param   req     Pointer to the poll request structure.
+ * @return  The events that are ready on the file descriptor.
+ */
 static int signalfd_poll(struct dfs_file *file, struct rt_pollreq *req)
 {
     struct rt_signalfd_ctx *sfd;
@@ -92,8 +104,23 @@ static int signalfd_poll(struct dfs_file *file, struct rt_pollreq *req)
 }
 
 #ifndef RT_USING_DFS_V2
+/**
+ * @brief   Reads signals from a signalfd file descriptor.
+ * @param   file    Pointer to the file structure.
+ * @param   buf     Pointer to the buffer to store the signals.
+ * @param   count   Maximum number of bytes to read.
+ * @return  Upon successful completion, returns the number of bytes read; otherwise, returns an error code.
+ */
 static ssize_t signalfd_read(struct dfs_file *file, void *buf, size_t count)
 #else
+/**
+ * @brief   Reads signals from a signalfd file descriptor with file offset.
+ * @param   file    Pointer to the file structure.
+ * @param   buf     Pointer to the buffer to store the signals.
+ * @param   count   Maximum number of bytes to read.
+ * @param   pos     Pointer to the file offset.
+ * @return  Upon successful completion, returns the number of bytes read; otherwise, returns an negative error code.
+ */
 static ssize_t signalfd_read(struct dfs_file *file, void *buf, size_t count, off_t *pos)
 #endif
 {
@@ -158,6 +185,11 @@ static ssize_t signalfd_read(struct dfs_file *file, void *buf, size_t count, off
     return ret;
 }
 
+/**
+ * @brief   Callback function for signalfd file descriptor notifications.
+ * @param   signalfd_queue  Pointer to the signalfd queue.
+ * @param   signum          Signal number.
+ */
 static void signalfd_callback(rt_wqueue_t *signalfd_queue, int signum)
 {
     struct rt_signalfd_ctx *sfd;
@@ -180,6 +212,11 @@ static void signalfd_callback(rt_wqueue_t *signalfd_queue, int signum)
     }
 }
 
+/**
+ * @brief   Adds a signal file descriptor notification.
+ * @param   sfd Pointer to the signalfd context.
+ * @return  Upon successful completion, returns 0; otherwise, returns an error code.
+ */
 static int signalfd_add_notify(struct rt_signalfd_ctx *sfd)
 {
     struct rt_lwp_notify *lwp_notify;
@@ -236,6 +273,13 @@ static int signalfd_add_notify(struct rt_signalfd_ctx *sfd)
     return ret;
 }
 
+/**
+ * @brief   Creates a new signalfd file descriptor or modifies an existing one.
+ * @param   fd      File descriptor to modify (-1 to create a new one).
+ * @param   mask    Signal mask.
+ * @param   flags   File descriptor flags.
+ * @return  Upon successful completion, returns the file descriptor number; otherwise, returns an error code.
+ */
 static int signalfd_do(int fd, const sigset_t *mask, int flags)
 {
     struct dfs_file *df;
@@ -328,6 +372,13 @@ static int signalfd_do(int fd, const sigset_t *mask, int flags)
     return ret;
 }
 
+/**
+ * @brief   Creates a new signalfd file descriptor or modifies an existing one.
+ * @param   fd      File descriptor to modify (-1 to create a new one).
+ * @param   mask    Signal mask.
+ * @param   flags   File descriptor flags.
+ * @return  Upon successful completion, returns the file descriptor number; otherwise, returns an error code.
+ */
 int signalfd(int fd, const sigset_t *mask, int flags)
 {
     return signalfd_do(fd, mask, flags);