From ee0f31df9abf4213af449a85591db8ef7ae6caec Mon Sep 17 00:00:00 2001
From: Oleg Hahm <oleg@hobbykeller.org>
Date: Tue, 8 Mar 2016 18:01:27 +0100
Subject: [PATCH 1/2] conn_udp: document correct create & recv usage

Both functions must be called from the same thread.
---
 sys/include/net/conn/udp.h | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/sys/include/net/conn/udp.h b/sys/include/net/conn/udp.h
index c94969a38d..02d7cb9361 100644
--- a/sys/include/net/conn/udp.h
+++ b/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

From b61b8e9f0012c0363ab02d5b81cb40d170cd8046 Mon Sep 17 00:00:00 2001
From: Oleg Hahm <oleg@hobbykeller.org>
Date: Tue, 8 Mar 2016 18:03:30 +0100
Subject: [PATCH 2/2] sockets: add documentation about implicite binding

---
 sys/posix/include/sys/socket.h | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/sys/posix/include/sys/socket.h b/sys/posix/include/sys/socket.h
index ecadc5197f..2624d5ce4b 100644
--- a/sys/posix/include/sys/socket.h
+++ b/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.