socket: expand docs+tests for recv_io/send_io

* ext/socket/unixsocket.c (unix_send_io): document args
  (unix_recv_io): ditto
* test/socket/test_unix.rb (test_fd_passing_class_mode): added

I was working on these when I encountered the problem in
with BasicSocket.for_fd not handling mode args:
https://bugs.ruby-lang.org/issues/11778

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@52922 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

ChangeLog

@@ -1,3 +1,9 @@
+Tue Dec  8 03:30:34 2015  Eric Wong  <e@80x24.org>
+
+	* ext/socket/unixsocket.c (unix_send_io): document args
+	  (unix_recv_io): ditto
+	* test/socket/test_unix.rb (test_fd_passing_class_mode): added
+
 Tue Dec 08 02:21:35 2015  Koichi Sasada  <ko1@atdot.net>
 
 	* iseq.c (iseq_translate): at the end of constructing an iseq,

ext/socket/unixsocket.c

@@ -201,6 +201,8 @@ sendmsg_blocking(void *data)
  *   p stdout.fileno #=> 6
  *
  *   stdout.puts "hello" # outputs "hello\n" to standard output.
+ *
+ * _io_ may be any kind of IO object or integer file descriptor.
  */
 static VALUE
 unix_send_io(VALUE sock, VALUE val)
@@ -297,6 +299,11 @@ recvmsg_blocking(void *data)
  *     }
  *   }
  *
+ * _klass_ will determine the class of _io_ returned (using the
+ * IO.for_fd singleton method or similar).
+ * If _klass_ is +nil+, an integer file descriptor is returned.
+ *
+ * _mode_ is the same as the argument passed to IO.for_fd
  */
 static VALUE
 unix_recv_io(int argc, VALUE *argv, VALUE sock)

test/socket/test_unix.rb

@@ -37,6 +37,26 @@ class TestSocket_UNIXSocket < Test::Unit::TestCase
     end
   end
 
+  def test_fd_passing_class_mode
+    UNIXSocket.pair do |s1, s2|
+      s1.send_io(s1.fileno)
+      r = s2.recv_io(nil)
+      assert_kind_of Integer, r, 'recv_io with klass=nil returns integer FD'
+      assert_not_equal s1.fileno, r
+      r = IO.for_fd(r)
+      assert_equal s1.stat.ino, r.stat.ino
+      r.close
+
+      s1.send_io(s1)
+      # klass = UNIXSocket FIXME: [ruby-core:71860] [Bug #11778]
+      klass = IO
+      r = s2.recv_io(klass, 'r+')
+      assert_instance_of klass, r, 'recv_io with proper klass'
+      assert_not_equal s1.fileno, r.fileno
+      r.close
+    end
+  end
+
   def test_fd_passing_n
     io_ary = []
     return if !defined?(Socket::SCM_RIGHTS)