[tor-commits] [tor/master] lib/net: improve the docs for tor_{ersatz_, }socketpair()

[nickm at torproject.org]

commit 671c34d9b496ecdde67527cc10b657ff6bd35c9e
Author: teor <teor at torproject.org>
Date:   Tue Jan 8 14:45:17 2019 +1000

    lib/net: improve the docs for tor_{ersatz_,}socketpair()
    
    Add some details about IP family support, and point to
    tor_socketpair() from tor_ersatz_socketpair().
    
    Closes ticket 29015.
---
 src/lib/net/socket.c     | 4 +++-
 src/lib/net/socketpair.c | 7 ++++++-
 2 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/src/lib/net/socket.c b/src/lib/net/socket.c
index 8940e0059..385c987e6 100644
--- a/src/lib/net/socket.c
+++ b/src/lib/net/socket.c
@@ -458,7 +458,9 @@ get_n_open_sockets(void)
  * localhost is inaccessible (for example, if the networking
  * stack is down). And even if it succeeds, the socket pair will not
  * be able to read while localhost is down later (the socket pair may
- * even close, depending on OS-specific timeouts).
+ * even close, depending on OS-specific timeouts). The socket pair
+ * should work on IPv4-only, IPv6-only, and dual-stack systems, as long
+ * as they have the standard localhost addresses.
  *
  * Returns 0 on success and -errno on failure; do not rely on the value
  * of errno or WSAGetLastError().
diff --git a/src/lib/net/socketpair.c b/src/lib/net/socketpair.c
index 380338f15..b23f08cab 100644
--- a/src/lib/net/socketpair.c
+++ b/src/lib/net/socketpair.c
@@ -105,7 +105,12 @@ sockaddr_eq(struct sockaddr *sa1, struct sockaddr *sa2)
 /**
  * Helper used to implement socketpair on systems that lack it, by
  * making a direct connection to localhost.
- */
+ *
+ * See tor_socketpair() for details.
+ *
+ * The direct connection defaults to IPv4, but falls back to IPv6 if
+ * IPv4 is not supported.
+ **/
 int
 tor_ersatz_socketpair(int family, int type, int protocol, tor_socket_t fd[2])
 {