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 #include #include +/** + * @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 @@ -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);