fdsend README Introduction ------------ fdsend is yet another file descriptor passing abstraction, specifically for Python. This package offers a few conveniences not commonly found together in other abstractions: sending multiple files at once, sending arbitrary data, and working with both files and file descriptors. License ------- fdsend is free software, licensed under the GPLv2+. It was originally developed by Michael J. Pomraning (http://pilcrow.madison.wi.us/) and is currently maintained by Philipp Kern and Fabian Knittel. Small portions of fdsend are adapted from other sources, see the main source file for details. Requirements ------------ Python >= 2.2 is required, as is SCM_RIGHTS support on AF_UNIX sockets. Only Linux has been tested. For setup.py setuptools is needed. Installation ------------ $ tar zxf fdsend-$VERSION.tar.gz $ cd fdsend-$VERSION $ python setup.py build $ python setup.py install Details ------- fdsend allows the passing of open files between unrelated processes via local sockets (using SCM_RIGHTS), a process known as file descriptor passing. The following functions are available: sendfds() recvfds() socketpair() Unlike some other simplifications of the sendmsg()/recvmsg() interface, fdsend allows multiple files to be transferred in a single operation, and permits ordinary socket messages to accompany the files. Additionally, fdsend understands bona fide Python sockets and files, as well as objects implementing fileno() methods and integers representing file descriptors. Errors are raised via the socket.error exception object. Example ------- import fdsend import socket # for socket.error # -- sender; send 12 files # nulldevs = [ file('/dev/null') for i in xrange(12) ] fdsend.sendfds(sock, "here you go!", fds = nulldevs) # -- recipient; receive up to 128-byte message, and up to 32 files # (msg, fds) = fdsend.recvfds(sock, 128, numfds = 32) import os fds = [ os.fdopen(fileno) for fileno in fds ] # -- exception handling # import socket try: notasock = file("/dev/null") fdsend.sendfds(notasock, "This won't work!") except socket.error, e: import errno if e[0] == errno.ENOTSOCK: print "What did you expect? :)" Known Bugs ---------- No provision is made to support msg_accrights systems (nor I_SENDFD fd passing). Feedback -------- Please report problems, bugs, feature requests, successes on the mailing list <python-fdsend@googlegroups.com>. Misc ---- - The usual limitation in "rights" send/recv fd implementations, wherein msg_iov conveys a single, often hardcoded, byte, is a venerable approach dating back at least as far as Stevens' APUE examples (1992). For many applications, it's no limitation at all. - socketpair() is only for Python versions lacking this under the 'socket' module. Related Interest ---------------- - scgi: (python) contains a passfd module. (http://www.mems-exchange.org/software/scgi/) - sendmsg: The sendmsg module (python) is a mostly complete sendmsg interface. (http://www.python.org/pycon/dc2004/papers/51/migration-code/sendmsg/) - Socket::MsgHdr: (perl) offers a full sendmsg interface. (http://search.cpan.org/dist/Socket-MsgHdr/lib/Socket/MsgHdr.pm) - bglibs: provides a variety of UNIX-ish conveniences, including a socket_sendfd function. (http://untroubled.org/bglibs/) - I_SENDFD ioctl: The I_SENDFD ioctl is an alternative approach for streams-based systems (http://pubs.opengroup.org/onlinepubs/007908799/xsh/ioctl.html)