[ViewVC] Annotation of: cvs/IO-FDPass/README

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

SYNOPSIS
       use IO::FDPass;

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).

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 amd 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. It
        should succeed if called on a socket that indicates readability
        (e.g. via "select").

        Example: receive a file desriptor from a blockign socket and convetr
        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 "send" and "recv" will have to "rendezvous", that is, they have to
    wait for each other. Therefore, on windows, it's advisable to run them
    at the same time to avoid any unnecessary delays.

    Also, on windows, the passing process must give the receiving process
    the PROCESS_DUP_HANDLE access right 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: Linux::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. It does,
    however, support a snumber of pre-standard unices.

    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,
    and requires AnyEvent. Presumably that makes it much more user friendly
    than this module.

    Neither seems to support native win32 perls.

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

Revision:	1.2
Committed:	Fri Apr 5 05:04:59 2013 UTC (12 years, 10 months ago) by root
Branch:	MAIN
CVS Tags:	rel-0_1
Changes since 1.1:	+90 -0 lines
Log Message:	0.1
#	User	Rev	Content
1	root	1.2	NAME
2			IO::FDPass - pass a file descriptor over a socket
3
4			SYNOPSIS
5			use IO::FDPass;
6
7			DESCRIPTION
8			This small low-level module only has one purpose: pass a file descriptor
9			to another process, using a (streaming) unix domain socket (on POSIX
10			systems) or any (streaming) socket (on WIN32 systems).
11
12			FUNCTIONS
13			$bool = IO::FDPass::send $socket_fd, $fd_to_pass
14			Sends the file descriptor given by $fd_to_pass over the socket
15			$socket_fd. Return true if it worked, false otherwise.
16
17			Note that both parameters must be file descriptors, not handles.
18
19			When used on non-blocking sockets, this function might fail with $!
20			set to "EAGAIN" or equivalent, in which case you are free to try. It
21			should succeed if called on a socket that indicates writability
22			(e.g. via "select").
23
24			Example: pass a file handle over an open socket.
25
26			IO::FDPass::send fileno $socket, fileno $fh
27			or die "unable to pass file handle: $!";
28
29			$fd = IO::FDPass::recv $socket_fd
30			Receive a file descriptor from the socket and return it if
31			successful. On errors, return -1.
32
33			Note that both $socket_fd amd the returned file descriptor are, in
34			fact, file descriptors, not handles.
35
36			When used on non-blocking sockets, this function might fail with $!
37			set to "EAGAIN" or equivalent, in which case you are free to try. It
38			should succeed if called on a socket that indicates readability
39			(e.g. via "select").
40
41			Example: receive a file desriptor from a blockign socket and convetr
42			it to a file handle.
43
44			my $fd = IO::FDPass::recv fileno $socket;
45			$fd >= 0 or die "unable to receive file handle: $!";
46			open my $fh, "+<&=$fd"
47			or die "unable to convert file descriptor to handle: $!";
48
49			PORTABILITY NOTES
50			This module has been tested on GNU/Linux x86 and amd64, NetBSD 6, OS X
51			10.5, Windows 2000 ActivePerl 5.10, Solaris 10, OpenBSD 4.4, 4.5, 4.8
52			and 5.0, DragonFly BSD, FreeBSD 7, 8 and 9, Windows 7 + ActivePerl
53			5.16.3 32 and 64 bit and Strawberry Perl 5.16.3 32 and 64 bit, and found
54			to work, although ActivePerl 32 bit needed a newer MinGW version (that
55			supports XP and higher).
56
57			However, windows doesn't support asynchronous file descriptor passing,
58			so "send" and "recv" will have to "rendezvous", that is, they have to
59			wait for each other. Therefore, on windows, it's advisable to run them
60			at the same time to avoid any unnecessary delays.
61
62			Also, on windows, the passing process must give the receiving process
63			the PROCESS_DUP_HANDLE access right for this module to work.
64
65			Cygwin is not supported at the moment, as file descriptor passing in
66			cygwin is not supported, and cannot be rolled on your own as cygwin has
67			no (working) method of opening a handle as fd. That is, it has one, but
68			that one isn't exposed to programs, and only used for stdin/out/err.
69			Sigh.
70
71			OTHER MODULES
72			At the time of this writing, the author of this module was aware of two
73			other file descriptor passing modules on CPAN: Linux::FDPasser and
74			AnyEvent::FDPasser.
75
76			The former hasn't seen any release for over a decade, isn't 64 bit clean
77			and it's author didn't respond to my mail with the fix. It does,
78			however, support a snumber of pre-standard unices.
79
80			The latter seems to have similar support for antique unices, and doesn't
81			seem to suffer from 64 bit bugs, but inexplicably has a large perl part,
82			and requires AnyEvent. Presumably that makes it much more user friendly
83			than this module.
84
85			Neither seems to support native win32 perls.
86
87			AUTHOR
88			Marc Lehmann <schmorp@schmorp.de>
89			http://home.schmorp.de/
90