NAME

       IO::FDPass - pass a file descriptor over a socket

SYNOPSIS

          use IO::FDPass;

          IO::FDPass::send fileno $socket, fileno $fh_to_pass
             or die "send failed: $!";

          my $fd = IO::FDPass::recv fileno $socket;
          $fd >= 0 or die "recv failed: $!";

DESCRIPTION

       This small low-level module only has one purpose: pass a file descriptor to another process, using a
       (streaming) unix domain socket (on POSIX systems) or any (streaming) socket (on WIN32 systems). The
       ability to pass file descriptors on windows is currently the unique selling point of this module. Have I
       mentioned that it is really small, too?

FUNCTIONS

       $bool = IO::FDPass::send $socket_fd, $fd_to_pass
           Sends  the file descriptor given by $fd_to_pass over the socket $socket_fd. Return true if it worked,
           false otherwise.

           Note that both parameters must be file descriptors, not handles.

           When used on non-blocking sockets, this function might fail with $!  set to "EAGAIN"  or  equivalent,
           in which case you are free to try. It should succeed if called on a socket that indicates writability
           (e.g. via "select").

           Example: pass a file handle over an open socket.

              IO::FDPass::send fileno $socket, fileno $fh
                 or die "unable to pass file handle: $!";

       $fd = IO::FDPass::recv $socket_fd
           Receive a file descriptor from the socket and return it if successful. On errors, return -1.

           Note  that  both  $socket_fd  and  the  returned  file descriptor are, in fact, file descriptors, not
           handles.

           When used on non-blocking sockets, this function might fail with $! set to "EAGAIN" or equivalent, in
           which case you are free to try again. It  should  succeed  if  called  on  a  socket  that  indicates
           readability (e.g. via "select").

           Example: receive a file descriptor from a blocking socket and convert it to a file handle.

             my $fd = IO::FDPass::recv fileno $socket;
             $fd >= 0 or die "unable to receive file handle: $!";
             open my $fh, "+<&=$fd"
                or die "unable to convert file descriptor to handle: $!";

PORTABILITY NOTES

       This  module  has  been  tested  on GNU/Linux x86 and amd64, NetBSD 6, OS X 10.5, Windows 2000 ActivePerl
       5.10, Solaris 10, OpenBSD 4.4, 4.5, 4.8 and 5.0,  DragonFly  BSD,  FreeBSD  7,  8  and  9,  Windows  7  +
       ActivePerl  5.16.3  32  and  64 bit and Strawberry Perl 5.16.3 32 and 64 bit, and found to work, although
       ActivePerl 32 bit needed a newer MinGW version (that supports XP and higher).

       However, windows doesn't support asynchronous file descriptor passing, so the source process  must  still
       be  around  when  the  destination  process wants to receive the file handle. Also, if the target process
       fails to fetch the handle for any reason (crashes, fails to call "recv" etc.), the handle will  leak,  so
       never do that.

       Also,  on  windows,  the  receiving  process  must have the PROCESS_DUP_HANDLE access right on the sender
       process for this module to work.

       Cygwin is not supported at the moment, as file descriptor passing in cygwin is not supported, and  cannot
       be  rolled  on your own as cygwin has no (working) method of opening a handle as fd. That is, it has one,
       but that one isn't exposed to programs, and only used for stdin/out/err. Sigh.

OTHER MODULES

       At the time of this writing, the author of this module was aware of two  other  file  descriptor  passing
       modules on CPAN: File::FDPasser and AnyEvent::FDPasser.

       The  former  hasn't seen any release for over a decade, isn't 64 bit clean and it's author didn't respond
       to my mail with the fix, so doesn't work on many 64 bit machines. It does, however, support a  number  of
       pre-standard unices, basically everything of relevance at the time it was written.

       The latter seems to have similar support for antique unices, and doesn't seem to suffer from 64 bit bugs,
       but  inexplicably  has  a large perl part, doesn't support mixing data and file descriptors, and requires
       AnyEvent. Presumably that makes it much more user friendly than this module (skimming the  manpage  shows
       that  a  lot  of  thought  has  gone into it, and you are well advised to read it and maybe use it before
       trying a low-level module such as this one). In fact, the manpage discusses  even  more  file  descriptor
       passing modules on CPAN.

       Neither seems to support native win32 perls.

AUTHOR

        Marc Lehmann <schmorp@schmorp.de>
        http://home.schmorp.de/

perl v5.38.2                                       2024-03-31                                        FDPass(3pm)