bpo-28724: Add methods send_fds, recv_fds to the socket module

Doc/library/socket.rst

@@ -669,6 +669,30 @@ The following functions all create :ref:`socket objects <socket-objects>`.
    .. versionadded:: 3.3
 
 
+.. function:: socket.send_fds(sock, buffers, fds[, flags[, address]])
+
+   :func:`socket.send_fds` sends the list of file descriptors *fds*
+   over an :const:`AF_UNIX` socket, on systems which support the
+   :const:`SCM_RIGHTS` mechanism.
+
+   .. availability:: most Unix platforms, possibly others.
+
+   .. versionadded:: 3.8
+
+
+.. function:: socket.recv_fds(sock, bufsize, maxfds[, flags])
+
+   On systems which support the :const:`SCM_RIGHTS` mechanism,
+   :func:`socket.recv_fds` will receive up to *maxfds* file descriptors,
+   returning the message data and a list containing the descriptors
+   (while ignoring unexpected conditions such as unrelated control
+   messages being received).
+
+   .. availability:: most Unix platforms, possibly others.
+
+   .. versionadded:: 3.8
+
+
 .. data:: SocketType
 
    This is a Python type object that represents the socket object type. It is the

Doc/whatsnew/3.8.rst

@@ -560,6 +560,11 @@ The :func:`socket.if_nameindex()`, :func:`socket.if_nametoindex()`, and
 :func:`socket.if_indextoname()` functions have been implemented on Windows.
 (Contributed by Zackery Spytz in :issue:`37007`.)
 
+Added :func:`socket.send_fds()` and :func:`socket.recv_fds` to send and
+receive a file descriptor from the socket.
+(Contributed by Joannah Nanjekye in :issue:`28724`.)
+
+
 shlex
 ----------
 

Lib/socket.py

@@ -12,6 +12,8 @@
 socket() -- create a new socket object
 socketpair() -- create a pair of new socket objects [*]
 fromfd() -- create a socket object from an open file descriptor [*]
+send_fds() -- Send file descriptor to the socket.
+recv_fds() -- Recieve file descriptor from the socket.
 fromshare() -- create a socket object from data received from socket.share() [*]
 gethostname() -- return the current hostname
 gethostbyname() -- map a hostname to its IP number
@@ -49,7 +51,7 @@
 import _socket
 from _socket import *
 
-import os, sys, io, selectors
+import os, sys, io, selectors, array
 from enum import IntEnum, IntFlag
 
 try:
@@ -463,6 +465,34 @@ def fromfd(fd, family, type, proto=0):
     nfd = dup(fd)
     return socket(family, type, proto, nfd)
 
+if hasattr(_socket.socket, "sendmsg"):
+    def send_fds(sock, buffers, fds, flags=0, address=None):
+        """ send_fds(sock, buffers, fds[, flags[, address]]) -> socket object
+
+        Send the list of file descriptors fds over an AF_UNIX socket.
+        """
+        return sock.sendmsg(buffers, [(_socket.SOL_SOCKET,
+            _socket.SCM_RIGHTS, array.array("i", fds))])
+    __all__.append("send_fds")
+
+if hasattr(_socket.socket, "recvmsg"):
+    def recv_fds(sock, bufsize, maxfds, flags=0):
+        """ recv_fds(sock, bufsize, maxfds[, flags]) -> (socket object, socket object)
+
+        receive up to maxfds file descriptors returning the message
+        data and a list containing the descriptors.
+        """
+        # Array of ints
+        fds = array.array("i")
+        msg, ancdata, flags, addr = sock.recvmsg(bufsize,
+            _socket.CMSG_LEN(maxfds * fds.itemsize))
+        for cmsg_level, cmsg_type, cmsg_data in ancdata:
+            if (cmsg_level == _socket.SOL_SOCKET and cmsg_type == _socket.SCM_RIGHTS):
+                # Append data, ignoring any truncated integers at the end.
+                fds.fromstring(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)])
+        return msg, list(fds), flags, addr
+    __all__.append("recv_fds")
+
 if hasattr(_socket.socket, "share"):
     def fromshare(info):
         """ fromshare(info) -> socket object

Lib/test/test_socket.py

@@ -2275,6 +2275,31 @@ def testFromFd(self):
     def _testFromFd(self):
         self.serv_conn.send(MSG)
 
+    @requireAttrs(socket.socket, "sendmsg")
+    @requireAttrs(socket, "AF_UNIX")
+    @unittest.skipIf(sys.platform == 'darwin', 'test not working for MacOSX')
+    @unittest.skipIf(sys.platform.startswith(('freebsd', 'netbsd', 'gnukfreebsd')), 'test not working for freebsd')
+    def testSendAndRecvFds(self):
+        fds = []
+        # create two new file descriptors.
+        for i in range(2):
+            fd, path = tempfile.mkstemp()
+            self.addCleanup(os.unlink, path)
+            self.addCleanup(os.close, fd)
+            os.write(fd, str(i).encode())
+            fds.append(fd)
+        f = self.cli_conn.detach()
+        sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM, fileno=f)
+        self.addCleanup(sock.close)
+        with sock:
+            socket.send_fds(sock, [MSG], fds)
+            msg, fds_list, flags, addr  = socket.recv_fds(sock, len(MSG), 1024)
+            self.assertEqual(msg, MSG)
+
+    @testSendAndRecvFds.client_skip
+    def _testSendAndRecvFds(self):
+        self.serv_conn.send(MSG)
+
     def testDup(self):
         # Testing dup()
         sock = self.cli_conn.dup()

Misc/NEWS.d/next/Library/2019-05-30-15-51-42.bpo-28724.34TrS8.rst

@@ -0,0 +1,2 @@
+The socket module now has the :func:`socket.send_fds()` and :func:`socket.recv.fds()` functions.
+Contributed by Joannah Nanjekye and Shinya Okano .