IO-FDPass/FDPass.pm

=head1 NAME

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

=head1 SYNOPSIS

   use IO::FDPass;

=head1 DESCRIPTION

This small low-level module only has one purpose: pass a file descriptor
to another process, using a unix domain socket (on POSIX systems) or any
socket (on WIN32 systems).

=head1 FUNCTIONS

=over 4

=cut

package IO::FDPass;

BEGIN {
   $VERSION = '0.0';

   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> amd 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. It
should succeed if called on a socket that indicates readability (e.g. via
C<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: $!";

=back

=head1 PORTABILITY NOTES

This module has been tested on 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
C<send> and C<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.

=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<Linux::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. 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.

=head1 AUTHOR

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

=cut

1

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