Merge pull request #4995 from OlegHahm/conn_udp_doc_same_thread

doc: add notes that UDP receive functions must be called from same thread

sys/include/net/conn/udp.h

@@ -51,6 +51,10 @@ typedef struct conn_udp conn_udp_t;
  * @param[in] family    The family of @p addr (see @ref net_af).
  * @param[in] port      The local UDP port for @p conn.
  *
+ * @todo    With @ref net_gnrc @ref conn_udp_recvfrom needs to be called from the
+ *          same thread as for this function. This is undesired behavior and
+ *          will be fixed in upcoming versions of RIOT.
+ *
  * @return  0 on success.
  * @return  any other negative number in case of an error. For portability implementations should
  *          draw inspiration of the errno values from the POSIX' bind() function specification.
@@ -93,6 +97,10 @@ int conn_udp_getlocaladdr(conn_udp_t *conn, void *addr, uint16_t *port);
  *
  * @note    Function may block.
  *
+ * @todo    With @ref net_gnrc this function needs to be called from the same
+ *          thread as @ref conn_udp_create. This is undesired behavior and will
+ *          be fixed in upcoming versions of RIOT.
+ *
  * @return  The number of bytes received on success.
  * @return  0, if no received data is available, but everything is in order.
  * @return  any other negative number in case of an error. For portability, implementations should

sys/posix/include/sys/socket.h

@@ -206,6 +206,13 @@ int bind(int socket, const struct sockaddr *address,
  *                          on the address family of the socket.
  * @param[in] address_len   Specifies the length of the sockaddr structure
  *                          pointed to by the address argument.
+ * @post The socket will be implicitely bound to an addressed, if it is not already bound.
+ *       According to
+ *       http://pubs.opengroup.org/onlinepubs/009695399/functions/connect.html
+ *       for a "socket [that] has not already been bound to a local address,
+ *       connect() shall bind it to an address which, unless the socket's
+ *       address family is AF_UNIX, is an unused local address."
+ *
  * @return  Upon successful completion, connect() shall return 0; otherwise,
  *          -1 shall be returned and errno set to indicate the error.
  */
@@ -398,6 +405,17 @@ ssize_t send(int socket, const void *buffer, size_t length, int flags);
  * @param[in] address_len   Specifies the length of the sockaddr structure pointed
  *                          to by the @p address argument.
  *
+ * @post    The socket will implicitely be bound to the unspecified address and
+ *          a random port, in case it is not already bound. Rationale: A client
+ *          should not require to explicitly call bind() to receive packets,
+ *          but is expected to receive replies sent to the ephemeral port that
+ *          was selected as a source port by the UDP implementation.
+ *
+ * @todo    For @ref net_gnrc any @ref recvfrom call that is called to receive
+ *          an expected response to this send command, must be called from the
+ *          same thread. This is undesired behavior and will be fixed in
+ *          upcoming versions of RIOT.
+ *
  * @return  Upon successful completion, send() shall return the number of bytes
  *          sent. Otherwise, -1 shall be returned and errno set to indicate the
  *          error.