michaelh/zephyr
1
0
Fork 0
Code Releases Activity

net: sockets: Add docstrings for BSD Sockets API

Browse source 
The current idea is that we document zsock_* prefixed symbols, refer
to Open Group POSIX website
(http://pubs.opengroup.org/onlinepubs/9699919799/) for normative
descriptions, and explicitly mention bare POSIX name of a function
too (so e.g. users could find it via search).

Fixes: #13397

Signed-off-by: Paul Sokolovsky <paul.sokolovsky@linaro.org>
This commit is contained in:
Paul Sokolovsky 2019-03-26 16:26:10 +02:00 • committed by Kumar Gala
commit bd10c72bc4
2 changed files with 375 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

81
include/net/socket_select.h
View file

@ -7,6 +7,13 @@
#ifndef ZEPHYR_INCLUDE_NET_SOCKET_SELECT_H_
#define ZEPHYR_INCLUDE_NET_SOCKET_SELECT_H_
/**
* @brief BSD Sockets compatible API
* @defgroup bsd_sockets BSD Sockets compatible API
* @ingroup networking
* @{
*/
#include <zephyr/types.h>
#ifdef __cplusplus
@ -23,17 +30,83 @@ typedef struct zsock_fd_set {
u32_t bitset[(CONFIG_POSIX_MAX_FDS + 31) / 32];
} zsock_fd_set;
/* select() API is inefficient, and implemented as inefficient wrapper on
* top of poll(). Avoid select(), use poll directly().
/**
* @brief Legacy function to poll multiple sockets for events
*
* @details
* @rststar
* See `POSIX.1-2017 article
* <http://pubs.opengroup.org/onlinepubs/9699919799/functions/select.html>`__
* for normative description. This function is provided to ease porting of
* existing code and not recommended for usage due to its inefficiency,
* use :c:func:`zsock_poll()` instead. In Zephyr this function works only with
* sockets, not arbitrary file descriptors.
* This function is also exposed as ``select()``
* if :option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined (in which case
* it may conflict with generic POSIX ``select()`` function).
* @endrststar
*/
int zsock_select(int nfds, zsock_fd_set *readfds, zsock_fd_set *writefds,
zsock_fd_set *exceptfds, struct zsock_timeval *timeout);
/** Number of file descriptors which can be added to zsock_fd_set */
#define ZSOCK_FD_SETSIZE (sizeof(((zsock_fd_set *)0)->bitset) * 8)
/**
* @brief Initialize (clear) fd_set
*
* @details
* @rststar
* See `POSIX.1-2017 article
* <http://pubs.opengroup.org/onlinepubs/9699919799/functions/select.html>`__
* for normative description.
* This function is also exposed as ``FD_ZERO()``
* if :option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined.
* @endrststar
*/
void ZSOCK_FD_ZERO(zsock_fd_set *set);
/**
* @brief Check whether socket is a member of fd_set
*
* @details
* @rststar
* See `POSIX.1-2017 article
* <http://pubs.opengroup.org/onlinepubs/9699919799/functions/select.html>`__
* for normative description.
* This function is also exposed as ``FD_ISSET()``
* if :option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined.
* @endrststar
*/
int ZSOCK_FD_ISSET(int fd, zsock_fd_set *set);
/**
* @brief Remove socket from fd_set
*
* @details
* @rststar
* See `POSIX.1-2017 article
* <http://pubs.opengroup.org/onlinepubs/9699919799/functions/select.html>`__
* for normative description.
* This function is also exposed as ``FD_CLR()``
* if :option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined.
* @endrststar
*/
void ZSOCK_FD_CLR(int fd, zsock_fd_set *set);
/**
* @brief Add socket to fd_set
*
* @details
* @rststar
* See `POSIX.1-2017 article
* <http://pubs.opengroup.org/onlinepubs/9699919799/functions/select.html>`__
* for normative description.
* This function is also exposed as ``FD_SET()``
* if :option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined.
* @endrststar
*/
void ZSOCK_FD_SET(int fd, zsock_fd_set *set);
#ifdef CONFIG_NET_SOCKETS_POSIX_NAMES
@ -75,4 +148,8 @@ static inline void FD_SET(int fd, zsock_fd_set *set)
}
#endif
/**
* @}
*/
#endif /* ZEPHYR_INCLUDE_NET_SOCKET_SELECT_H_ */