ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/IO-FDPass/FDPass.pm
(Generate patch)

Comparing IO-FDPass/FDPass.pm (file contents):
Revision 1.1 by root, Fri Apr 5 04:10:51 2013 UTC vs.
Revision 1.8 by root, Sat Apr 6 22:26:41 2013 UTC

… …
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use IO::FDPass; 7 use IO::FDPass;
8 8
9 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
9=head1 DESCRIPTION 15=head1 DESCRIPTION
10 16
11This small low-level module only has one purpose: pass a file descriptor 17This small low-level module only has one purpose: pass a file descriptor
12to another process, using a unix domain socket (on POSIX systems) or any 18to another process, using a (streaming) unix domain socket (on POSIX
13socket (on WIN32 systems). 19systems) or any (streaming) socket (on WIN32 systems). The ability to pass
20file descriptors on windows is currently the unique selling point of this
21module. Have I mentioned that it is really small, too?
14 22
15=head1 FUNCTIONS 23=head1 FUNCTIONS
16 24
17=over 4 25=over 4
18 26
19=cut 27=cut
20 28
21package IO::FDPass; 29package IO::FDPass;
22 30
23BEGIN { 31BEGIN {
24 $VERSION = '0.0'; 32 $VERSION = 0.2;
25 33
26 require XSLoader; 34 require XSLoader;
27 XSLoader::load (__PACKAGE__, $VERSION); 35 XSLoader::load (__PACKAGE__, $VERSION);
28} 36}
29 37
… …
47=item $fd = IO::FDPass::recv $socket_fd 55=item $fd = IO::FDPass::recv $socket_fd
48 56
49Receive a file descriptor from the socket and return it if successful. On 57Receive a file descriptor from the socket and return it if successful. On
50errors, return C<-1>. 58errors, return C<-1>.
51 59
52Note that I<both> C<$socket_fd> amd the returned file descriptor are, in 60Note that I<both> C<$socket_fd> and the returned file descriptor are, in
53fact, file descriptors, not handles. 61fact, file descriptors, not handles.
54 62
55When used on non-blocking sockets, this function might fail with C<$!> 63When used on non-blocking sockets, this function might fail with C<$!> set
56set to C<EAGAIN> or equivalent, in which case you are free to try. It 64to C<EAGAIN> or equivalent, in which case you are free to try again. It
57should succeed if called on a socket that indicates readability (e.g. via 65should succeed if called on a socket that indicates readability (e.g. via
58C<select>). 66C<select>).
59 67
60Example: receive a file desriptor from a blockign socket and convetr it to 68Example: receive a file descriptor from a blocking socket and convert it
61a file handle. 69to a file handle.
62 70
63 my $fd = IO::FDPass::recv fileno $socket; 71 my $fd = IO::FDPass::recv fileno $socket;
64 $fd >= 0 or die "unable to receive file handle: $!"; 72 $fd >= 0 or die "unable to receive file handle: $!";
65 open my $fh, "+<&=$fd" 73 open my $fh, "+<&=$fd"
66 or die "unable to convert file descriptor to handle: $!"; 74 or die "unable to convert file descriptor to handle: $!";
67 75
68=back 76=back
69 77
70=head1 PORTABILITY NOTES 78=head1 PORTABILITY NOTES
71 79
72This module has been tested on NEtBSD 6, OS X 10.5, Windows 2000 80This module has been tested on GNU/Linux x86 and amd64, NetBSD 6, OS X
73ActivePerl 5.10, Solaris 10, OpenBSD 4.4, 4.5, 4.8 and 5.0, DragonFly 8110.5, Windows 2000 ActivePerl 5.10, Solaris 10, OpenBSD 4.4, 4.5, 4.8 and
74BSD, FreeBSD 7, 8 and 9, Windows 7 + ActivePerl 5.16.3 32 and 64 bit and 825.0, DragonFly BSD, FreeBSD 7, 8 and 9, Windows 7 + ActivePerl 5.16.3 32
75Strawberry Perl 5.16.3 32 and 64 bit, and found to work. 83and 64 bit and Strawberry Perl 5.16.3 32 and 64 bit, and found to work,
84although ActivePerl 32 bit needed a newer MinGW version (that supports XP
85and higher).
76 86
77However, windows doesn't support asynchronous file descriptor passing, so 87However, windows doesn't support asynchronous file descriptor passing, so
78C<send> and C<recv> will have to "rendezvous", that is, they have to wait 88the source process must still be around when the destination process wants
79for each other. Therefore, on windows, it's advisable to run them at the 89to receive the file handle. Also, if the target process fails to fetch the
80same time to avoid any unnecessary delays. 90handle for any reason (crashes, fails to call C<recv> etc.), the handle
91will leak, so never do that.
81 92
82Also, on windows, the passing process must give the receiving process the 93Also, on windows, the receiving process must have the PROCESS_DUP_HANDLE
83PROCESS_DUP_HANDLE access right for this module to work. 94access right on the sender process for this module to work.
95
96Cygwin is not supported at the moment, as file descriptor passing in
97cygwin 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
99one isn't exposed to programs, and only used for stdin/out/err. Sigh.
84 100
85=head1 OTHER MODULES 101=head1 OTHER MODULES
86 102
87At the time of this writing, the author of this module was aware of two 103At the time of this writing, the author of this module was aware of two
88other file descriptor passing modules on CPAN: L<Linux::FDPasser> and 104other file descriptor passing modules on CPAN: L<File::FDPasser> and
89L<AnyEvent::FDPasser>. 105L<AnyEvent::FDPasser>.
90 106
91The former hasn't seen any release for over a decade, isn't 64 bit clean 107The former hasn't seen any release for over a decade, isn't 64 bit clean
92and it's author didn't respond to my mail with the fix. It does, however, 108and it's author didn't respond to my mail with the fix, so doesn't work on
93support a snumber of pre-standard unices. 109many 64 bit machines. It does, however, support a number of pre-standard
110unices, basically everything of relevance at the time it was written.
94 111
95The latter seems to have similar support for antique unices, and doesn't 112The latter seems to have similar support for antique unices, and doesn't
96seem to suffer from 64 bit bugs, but inexplicably has a large perl part, 113seem to suffer from 64 bit bugs, but inexplicably has a large perl
114part, doesn't support mixing data and file descriptors, and requires
97and requires AnyEvent. Presumably that makes it much more user friendly 115AnyEvent. Presumably that makes it much more user friendly than this
98than this module. 116module (skimming the manpage shows that a lot of thought has gone into
117it, and you are well advised to read it and maybe use it before trying a
118low-level module such as this one). In fact, the manpage discusses even
119more file descriptor passing modules on CPAN.
99 120
100Neither seems to support native win32 perls. 121Neither seems to support native win32 perls.
101 122
102=head1 AUTHOR 123=head1 AUTHOR
103 124

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines