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

297
include/net/socket.h
View file

@ -38,23 +38,34 @@ struct zsock_pollfd {
short revents;
};
/* Values are compatible with Linux */
/* ZSOCK_POLL* values are compatible with Linux */
/** zsock_poll: Poll for readability */
#define ZSOCK_POLLIN 1
/** zsock_poll: Compatibility value, ignored */
#define ZSOCK_POLLPRI 2
/** zsock_poll: Poll for writability */
#define ZSOCK_POLLOUT 4
/** zsock_poll: Poll results in error condition (output value only) */
#define ZSOCK_POLLERR 8
/** zsock_poll: Poll detected closed connection (output value only) */
#define ZSOCK_POLLHUP 0x10
/** zsock_poll: Invalid socket (output value only) */
#define ZSOCK_POLLNVAL 0x20
/** zsock_recv: Read data without removing it from socket input queue */
#define ZSOCK_MSG_PEEK 0x02
/** zsock_recv/zsock_send: Override operation to non-blocking */
#define ZSOCK_MSG_DONTWAIT 0x40
/* Well-known values, e.g. from Linux man 2 shutdown:
* "The constants SHUT_RD, SHUT_WR, SHUT_RDWR have the value 0, 1, 2,
* respectively". Some software uses numeric values.
*/
/** zsock_shutdown: Shut down for reading */
#define ZSOCK_SHUT_RD 0
/** zsock_shutdown: Shut down for writing */
#define ZSOCK_SHUT_WR 1
/** zsock_shutdown: Shut down for both reading and writing */
#define ZSOCK_SHUT_RDWR 2
/** Protocol level for TLS.
@ -125,66 +136,292 @@ struct zsock_addrinfo {
char _ai_canonname[DNS_MAX_NAME_SIZE + 1];
};
/**
* @brief Create a network socket
*
* @details
* @rststar
* See `POSIX.1-2017 article
* <http://pubs.opengroup.org/onlinepubs/9699919799/functions/socket.html>`__
* for normative description.
* This function is also exposed as ``socket()``
* if :option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined.
* @endrststar
*/
__syscall int zsock_socket(int family, int type, int proto);
/**
* @brief Close a network socket
*
* @details
* @rststar
* Close a network socket.
* This function is also exposed as ``close()``
* if :option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined (in which case it
* may conflict with generic POSIX ``close()`` function).
* @endrststar
*/
__syscall int zsock_close(int sock);
/**
* @brief Shutdown socket send/receive operations
*
* @details
* @rststar
* See `POSIX.1-2017 article
* <http://pubs.opengroup.org/onlinepubs/9699919799/functions/shutdown.html>`__
* for normative description, but currently this function has no effect in
* Zephyr and provided solely for compatibility with existing code.
* This function is also exposed as ``shutdown()``
* if :option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined.
* @endrststar
*/
__syscall int zsock_shutdown(int sock, int how);
/**
* @brief Bind a socket to a local network address
*
* @details
* @rststar
* See `POSIX.1-2017 article
* <http://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html>`__
* for normative description.
* This function is also exposed as ``bind()``
* if :option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined.
* @endrststar
*/
__syscall int zsock_bind(int sock, const struct sockaddr *addr,
socklen_t addrlen);
/**
* @brief Connect a socket to a peer network address
*
* @details
* @rststar
* See `POSIX.1-2017 article
* <http://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html>`__
* for normative description.
* This function is also exposed as ``connect()``
* if :option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined.
* @endrststar
*/
__syscall int zsock_connect(int sock, const struct sockaddr *addr,
socklen_t addrlen);
/**
* @brief Set up a STREAM socket to accept peer connections
*
* @details
* @rststar
* See `POSIX.1-2017 article
* <http://pubs.opengroup.org/onlinepubs/9699919799/functions/listen.html>`__
* for normative description.
* This function is also exposed as ``listen()``
* if :option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined.
* @endrststar
*/
__syscall int zsock_listen(int sock, int backlog);
/**
* @brief Accept a connection on listening socket
*
* @details
* @rststar
* See `POSIX.1-2017 article
* <http://pubs.opengroup.org/onlinepubs/9699919799/functions/accept.html>`__
* for normative description.
* This function is also exposed as ``accept()``
* if :option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined.
* @endrststar
*/
__syscall int zsock_accept(int sock, struct sockaddr *addr, socklen_t *addrlen);
/**
* @brief Send data to an arbitrary network address
*
* @details
* @rststar
* See `POSIX.1-2017 article
* <http://pubs.opengroup.org/onlinepubs/9699919799/functions/sendto.html>`__
* for normative description.
* This function is also exposed as ``sendto()``
* if :option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined.
* @endrststar
*/
__syscall ssize_t zsock_sendto(int sock, const void *buf, size_t len,
int flags, const struct sockaddr *dest_addr,
socklen_t addrlen);
/**
* @brief Send data to a connected peer
*
* @details
* @rststar
* See `POSIX.1-2017 article
* <http://pubs.opengroup.org/onlinepubs/9699919799/functions/send.html>`__
* for normative description.
* This function is also exposed as ``send()``
* if :option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined.
* @endrststar
*/
static inline ssize_t zsock_send(int sock, const void *buf, size_t len,
int flags)
{
return zsock_sendto(sock, buf, len, flags, NULL, 0);
}
/**
* @brief Receive data from an arbitrary network address
*
* @details
* @rststar
* See `POSIX.1-2017 article
* <http://pubs.opengroup.org/onlinepubs/9699919799/functions/recvfrom.html>`__
* for normative description.
* This function is also exposed as ``recvfrom()``
* if :option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined.
* @endrststar
*/
__syscall ssize_t zsock_recvfrom(int sock, void *buf, size_t max_len,
int flags, struct sockaddr *src_addr,
socklen_t *addrlen);
/**
* @brief Receive data from a connected peer
*
* @details
* @rststar
* See `POSIX.1-2017 article
* <http://pubs.opengroup.org/onlinepubs/9699919799/functions/recv.html>`__
* for normative description.
* This function is also exposed as ``recv()``
* if :option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined.
* @endrststar
*/
static inline ssize_t zsock_recv(int sock, void *buf, size_t max_len,
int flags)
{
return zsock_recvfrom(sock, buf, max_len, flags, NULL, NULL);
}
/**
* @brief Control blocking/non-blocking mode of a socket
*
* @details
* @rststar
* This functions allow to (only) configure a socket for blocking or
* non-blocking operation (O_NONBLOCK).
* This function is also exposed as ``fcntl()``
* if :option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined (in which case
* it may conflict with generic POSIX ``fcntl()`` function).
* @endrststar
*/
__syscall int zsock_fcntl(int sock, int cmd, int flags);
/**
* @brief Efficiently poll multiple sockets for events
*
* @details
* @rststar
* See `POSIX.1-2017 article
* <http://pubs.opengroup.org/onlinepubs/9699919799/functions/poll.html>`__
* for normative description. (In Zephyr this function works only with
* sockets, not arbitrary file descriptors.)
* This function is also exposed as ``poll()``
* if :option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined (in which case
* it may conflict with generic POSIX ``poll()`` function).
* @endrststar
*/
__syscall int zsock_poll(struct zsock_pollfd *fds, int nfds, int timeout);
/**
* @brief Get various socket options
*
* @details
* @rststar
* See `POSIX.1-2017 article
* <http://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockopt.html>`__
* for normative description. In Zephyr this function supports a subset of
* socket options described by POSIX, but also some additional options
* available in Linux (some options are dummy and provided to ease porting
* of existing code).
* This function is also exposed as ``getsockopt()``
* if :option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined.
* @endrststar
*/
int zsock_getsockopt(int sock, int level, int optname,
void *optval, socklen_t *optlen);
/**
* @brief Set various socket options
*
* @details
* @rststar
* See `POSIX.1-2017 article
* <http://pubs.opengroup.org/onlinepubs/9699919799/functions/setsockopt.html>`__
* for normative description. In Zephyr this function supports a subset of
* socket options described by POSIX, but also some additional options
* available in Linux (some options are dummy and provided to ease porting
* of existing code).
* This function is also exposed as ``setsockopt()``
* if :option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined.
* @endrststar
*/
int zsock_setsockopt(int sock, int level, int optname,
const void *optval, socklen_t optlen);
/**
* @brief Get local host name
*
* @details
* @rststar
* See `POSIX.1-2017 article
* <http://pubs.opengroup.org/onlinepubs/9699919799/functions/gethostname.html>`__
* for normative description.
* This function is also exposed as ``gethostname()``
* if :option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined.
* @endrststar
*/
int zsock_gethostname(char *buf, size_t len);
/**
* @brief Convert network address from internal to numeric ASCII form
*
* @details
* @rststar
* See `POSIX.1-2017 article
* <http://pubs.opengroup.org/onlinepubs/9699919799/functions/inet_ntop.html>`__
* for normative description.
* This function is also exposed as ``inet_ntop()``
* if :option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined.
* @endrststar
*/
static inline char *zsock_inet_ntop(sa_family_t family, const void *src,
char *dst, size_t size)
{
return net_addr_ntop(family, src, dst, size);
}
/**
* @brief Convert network address from numeric ASCII form to internal representation
*
* @details
* @rststar
* See `POSIX.1-2017 article
* <http://pubs.opengroup.org/onlinepubs/9699919799/functions/inet_pton.html>`__
* for normative description.
* This function is also exposed as ``inet_pton()``
* if :option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined.
* @endrststar
*/
__syscall int zsock_inet_pton(sa_family_t family, const char *src, void *dst);
/** @cond INTERNAL_HIDDEN */
__syscall int z_zsock_getaddrinfo_internal(const char *host,
const char *service,
const struct zsock_addrinfo *hints,
struct zsock_addrinfo *res);
/** @endcond */
/* Flags for getaddrinfo() hints. */
@ -203,23 +440,76 @@ __syscall int z_zsock_getaddrinfo_internal(const char *host,
/** Assume service (port) is numeric */
#define AI_NUMERICSERV 0x400
/**
* @brief Resolve a domain name to one or more network addresses
*
* @details
* @rststar
* See `POSIX.1-2017 article
* <http://pubs.opengroup.org/onlinepubs/9699919799/functions/getaddrinfo.html>`__
* for normative description.
* This function is also exposed as ``getaddrinfo()``
* if :option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined.
* @endrststar
*/
int zsock_getaddrinfo(const char *host, const char *service,
const struct zsock_addrinfo *hints,
struct zsock_addrinfo **res);
/**
* @brief Free results returned by zsock_getaddrinfo()
*
* @details
* @rststar
* See `POSIX.1-2017 article
* <http://pubs.opengroup.org/onlinepubs/9699919799/functions/freeaddrinfo.html>`__
* for normative description.
* This function is also exposed as ``freeaddrinfo()``
* if :option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined.
* @endrststar
*/
static inline void zsock_freeaddrinfo(struct zsock_addrinfo *ai)
{
free(ai);
}
/**
* @brief Convert zsock_getaddrinfo() error code to textual message
*
* @details
* @rststar
* See `POSIX.1-2017 article
* <http://pubs.opengroup.org/onlinepubs/9699919799/functions/gai_strerror.html>`__
* for normative description.
* This function is also exposed as ``gai_strerror()``
* if :option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined.
* @endrststar
*/
const char *zsock_gai_strerror(int errcode);
/** zsock_getnameinfo(): Resolve to numeric address. */
#define NI_NUMERICHOST 1
/** zsock_getnameinfo(): Resolve to numeric port number. */
#define NI_NUMERICSERV 2
/** zsock_getnameinfo(): Return only hostname instead of FQDN */
#define NI_NOFQDN 4
/** zsock_getnameinfo(): Dummy option for compatibility */
#define NI_NAMEREQD 8
/** zsock_getnameinfo(): Dummy option for compatibility */
#define NI_DGRAM 16
/**
* @brief Resolve a network address to a domain name or ASCII address
*
* @details
* @rststar
* See `POSIX.1-2017 article
* <http://pubs.opengroup.org/onlinepubs/9699919799/functions/getnameinfo.html>`__
* for normative description.
* This function is also exposed as ``getnameinfo()``
* if :option:`CONFIG_NET_SOCKETS_POSIX_NAMES` is defined.
* @endrststar
*/
int zsock_getnameinfo(const struct sockaddr *addr, socklen_t addrlen,
char *host, socklen_t hostlen,
char *serv, socklen_t servlen, int flags);
@ -405,16 +695,21 @@ static inline char *inet_ntop(sa_family_t family, const void *src, char *dst,
#define EAI_SERVICE DNS_EAI_SERVICE
#endif /* defined(CONFIG_NET_SOCKETS_POSIX_NAMES) */
/** sockopt: Socket-level option */
#define SOL_SOCKET 1
/* Socket options for SOL_SOCKET level */
/** sockopt: Enable server address reuse (ignored, for compatibility) */
#define SO_REUSEADDR 2
/** sockopt: Async error (ignored, for compatibility) */
#define SO_ERROR 4
/* Socket options for IPPROTO_TCP level */
/** sockopt: Disable TCP buffering (ignored, for compatibility) */
#define TCP_NODELAY 1
/* Socket options for IPPROTO_IPV6 level */
/** sockopt: Don't support IPv4 access (ignored, for compatibility) */
#define IPV6_V6ONLY 26
#ifdef __cplusplus

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_ */