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

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/

Revision:	1.4
Committed:	Sat Apr 6 22:42:42 2013 UTC (11 years, 1 month ago) by root
Branch:	MAIN
CVS Tags:	rel-1_1, rel-1_0, rel-1_3, rel-1_2, HEAD
Changes since 1.3:	+28 -13 lines
Log Message:	1.0
#	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	root	1.4	IO::FDPass::send fileno $socket, fileno $fh_to_pass
8			or die "send failed: $!";
9
10			my $fd = IO::FDPass::recv fileno $socket;
11			$fd >= 0 or die "recv failed: $!";
12
13	root	1.2	DESCRIPTION
14			This small low-level module only has one purpose: pass a file descriptor
15			to another process, using a (streaming) unix domain socket (on POSIX
16	root	1.4	systems) or any (streaming) socket (on WIN32 systems). The ability to
17			pass file descriptors on windows is currently the unique selling point
18			of this module. Have I mentioned that it is really small, too?
19	root	1.2
20			FUNCTIONS
21			$bool = IO::FDPass::send $socket_fd, $fd_to_pass
22			Sends the file descriptor given by $fd_to_pass over the socket
23			$socket_fd. Return true if it worked, false otherwise.
24
25			Note that both parameters must be file descriptors, not handles.
26
27			When used on non-blocking sockets, this function might fail with $!
28			set to "EAGAIN" or equivalent, in which case you are free to try. It
29			should succeed if called on a socket that indicates writability
30			(e.g. via "select").
31
32			Example: pass a file handle over an open socket.
33
34			IO::FDPass::send fileno $socket, fileno $fh
35			or die "unable to pass file handle: $!";
36
37			$fd = IO::FDPass::recv $socket_fd
38			Receive a file descriptor from the socket and return it if
39			successful. On errors, return -1.
40
41	root	1.4	Note that both $socket_fd and the returned file descriptor are, in
42	root	1.2	fact, file descriptors, not handles.
43
44			When used on non-blocking sockets, this function might fail with $!
45	root	1.4	set to "EAGAIN" or equivalent, in which case you are free to try
46			again. It should succeed if called on a socket that indicates
47			readability (e.g. via "select").
48	root	1.2
49	root	1.4	Example: receive a file descriptor from a blocking socket and
50			convert it to a file handle.
51	root	1.2
52			my $fd = IO::FDPass::recv fileno $socket;
53			$fd >= 0 or die "unable to receive file handle: $!";
54			open my $fh, "+<&=$fd"
55			or die "unable to convert file descriptor to handle: $!";
56
57			PORTABILITY NOTES
58			This module has been tested on GNU/Linux x86 and amd64, NetBSD 6, OS X
59			10.5, Windows 2000 ActivePerl 5.10, Solaris 10, OpenBSD 4.4, 4.5, 4.8
60			and 5.0, DragonFly BSD, FreeBSD 7, 8 and 9, Windows 7 + ActivePerl
61			5.16.3 32 and 64 bit and Strawberry Perl 5.16.3 32 and 64 bit, and found
62			to work, although ActivePerl 32 bit needed a newer MinGW version (that
63			supports XP and higher).
64
65			However, windows doesn't support asynchronous file descriptor passing,
66	root	1.3	so the source process must still be around when the destination process
67			wants to receive the file handle. Also, if the target process fails to
68	root	1.4	fetch the handle for any reason (crashes, fails to call "recv" etc.),
69			the handle will leak, so never do that.
70	root	1.2
71	root	1.3	Also, on windows, the receiving process must have the PROCESS_DUP_HANDLE
72			access right on the sender process for this module to work.
73	root	1.2
74			Cygwin is not supported at the moment, as file descriptor passing in
75			cygwin is not supported, and cannot be rolled on your own as cygwin has
76			no (working) method of opening a handle as fd. That is, it has one, but
77			that one isn't exposed to programs, and only used for stdin/out/err.
78			Sigh.
79
80			OTHER MODULES
81			At the time of this writing, the author of this module was aware of two
82	root	1.4	other file descriptor passing modules on CPAN: File::FDPasser and
83	root	1.2	AnyEvent::FDPasser.
84
85			The former hasn't seen any release for over a decade, isn't 64 bit clean
86	root	1.4	and it's author didn't respond to my mail with the fix, so doesn't work
87			on many 64 bit machines. It does, however, support a number of
88			pre-standard unices, basically everything of relevance at the time it
89			was written.
90	root	1.2
91			The latter seems to have similar support for antique unices, and doesn't
92			seem to suffer from 64 bit bugs, but inexplicably has a large perl part,
93	root	1.4	doesn't support mixing data and file descriptors, and requires AnyEvent.
94			Presumably that makes it much more user friendly than this module
95			(skimming the manpage shows that a lot of thought has gone into it, and
96			you are well advised to read it and maybe use it before trying a
97			low-level module such as this one). In fact, the manpage discusses even
98			more file descriptor passing modules on CPAN.
99	root	1.2
100			Neither seems to support native win32 perls.
101
102			AUTHOR
103			Marc Lehmann <schmorp@schmorp.de>
104			http://home.schmorp.de/
105