summaryrefslogtreecommitdiff
path: root/ext/socket/socket.c
diff options
context:
space:
mode:
authorakr <akr@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2017-10-21 13:13:02 +0000
committerakr <akr@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2017-10-21 13:13:02 +0000
commitb5c6fc856100b17b6f20e6e792a02ee7e33306bc (patch)
tree189708e38170550aa6c315ee1306c39dd7f4b114 /ext/socket/socket.c
parent7f7d5d0c905c982a75488c3b0c89154a5188b692 (diff)
Deprecation document for gethostbyname,gethostbyaddr.
[Feature #13097] I confirmed current ruby (Ruby 2.4 and trunk) uses gethostbyname() and gethostbyaddr(). Socket.gethostbyname uses getaddrinfo() and gethostbyname(). Socket.gethostbyaddr uses gethostbyaddr(). Socket.gethostbyname uses gethostbyname() to obtain alias hostnames. RFC 3493 defines getaddrinfo()/getnameinfo() and describes the problems of gethostbyname()/gethostbyaddr(). The problems are difficult protocol handling and thread-unsafety. Since Ruby has GVL, the thread-unsafety doesn't cause wrong result. But it may block other threads until finishing DNS query. Socket.gethostbyname has the protocol handling problem. It returns only one address family: ``` % ruby -rpp -rsocket -e 'pp Socket.gethostbyname("www.wide.ad.jp")' ["www.wide.ad.jp", [], 10, " \x01\x02\x00\r\xFF\xFF\xF1\x02\x16>\xFF\xFEKe\x1C", "\xCB\xB2\x89:"] ``` www.wide.ad.jp has one IPv6 address and one IPv4 address. But Socket.gethostbyname returns only one address family, 10 (AF_INET6), which is the address family of the first address. Also, Socket.gethostbyname and Socket.gethostbyaddr uses 4-bytes binary IPv4 address and 16-bytes binary IPv6 address. This is not usual in other socket API in Ruby. (Most socket API uses binary sockaddr string or Addrinfo object) I think Socket.gethostbyname and Socket.gethostbyaddr are too far from recommendable API. So, I added deprecation description for documents for them. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@60266 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'ext/socket/socket.c')
-rw-r--r--ext/socket/socket.c22
1 files changed, 20 insertions, 2 deletions
diff --git a/ext/socket/socket.c b/ext/socket/socket.c
index b6230bc..60dc6f1 100644
--- a/ext/socket/socket.c
+++ b/ext/socket/socket.c
@@ -983,7 +983,17 @@ sock_sockaddr(struct sockaddr *addr, socklen_t len)
* call-seq:
* Socket.gethostbyname(hostname) => [official_hostname, alias_hostnames, address_family, *address_list]
*
- * Obtains the host information for _hostname_.
+ * This method is deprecated since following reasons:
+ *
+ * - The 3rd element of result is the address family of the first address.
+ * The address families of rest addresses are not returned.
+ * - Uncommon address representation:
+ * 4/16-bytes binary string to represent IPv4/IPv6 address.
+ * - gethostbyname() is may take long time and it may block other threads.
+ * (GVL cannot be released since gethostbyname() is not thread safe.)
+ * - This method uses gethostbyname() function already removed from POSIX.
+ *
+ * This method obtains the host information for _hostname_.
*
* p Socket.gethostbyname("hal") #=> ["localhost", ["hal"], 2, "\x7F\x00\x00\x01"]
*
@@ -1000,7 +1010,15 @@ sock_s_gethostbyname(VALUE obj, VALUE host)
* call-seq:
* Socket.gethostbyaddr(address_string [, address_family]) => hostent
*
- * Obtains the host information for _address_.
+ * This method is deprecated since following reasons:
+ *
+ * - Uncommon address representation:
+ * 4/16-bytes binary string to represent IPv4/IPv6 address.
+ * - gethostbyaddr() is may take long time and it may block other threads.
+ * (GVL cannot be released since gethostbyname() is not thread safe.)
+ * - This method uses gethostbyname() function already removed from POSIX.
+ *
+ * This method obtains the host information for _address_.
*
* p Socket.gethostbyaddr([221,186,184,68].pack("CCCC"))
* #=> ["carbon.ruby-lang.org", [], 2, "\xDD\xBA\xB8D"]