akr	2017-10-21 22:13:02 +0900 (Sat, 21 Oct 2017)

  New Revision: 60266

  https://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=revision&revision=60266

  Log:
    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.

  Modified files:
    trunk/ext/socket/socket.c
Index: ext/socket/socket.c
===================================================================
--- ext/socket/socket.c	(revision 60265)
+++ ext/socket/socket.c	(revision 60266)
@@ -983,7 +983,17 @@ sock_sockaddr(struct sockaddr *addr, soc https://github.com/ruby/ruby/blob/trunk/ext/socket/socket.c#L983
  * 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 ho https://github.com/ruby/ruby/blob/trunk/ext/socket/socket.c#L1010
  * 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"]

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/