IO-FDPass/FDPass.pm

=head1 NAME

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

=head1 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: $!";

=head1 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?

=head1 FUNCTIONS

=over 4

=cut

package IO::FDPass;

BEGIN {
   $VERSION = 0.2;

   require XSLoader;
   XSLoader::load (__PACKAGE__, $VERSION);
}

=item $bool = IO::FDPass::send $socket_fd, $fd_to_pass

Sends the file descriptor given by C<$fd_to_pass> over the socket
C<$socket_fd>. Return true if it worked, false otherwise.

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

When used on non-blocking sockets, this function might fail with C<$!>
set to C<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
C<select>).

Example: pass a file handle over an open socket.

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

=item $fd = IO::FDPass::recv $socket_fd

Receive a file descriptor from the socket and return it if successful. On
errors, return C<-1>.

Note that I<both> C<$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 C<$!> set
to C<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
C<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: $!";

=back

=head1 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 C<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.

=head1 OTHER MODULES

At the time of this writing, the author of this module was aware of two
other file descriptor passing modules on CPAN: L<File::FDPasser> and
L<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.

=head1 AUTHOR

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

=cut

1

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