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.3 by root, Fri Apr 5 05:04:59 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 (streaming) unix domain socket (on POSIX 18to another process, using a (streaming) unix domain socket (on POSIX
13systems) or any (streaming) socket (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.1'; 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: $!";
… …
75and 64 bit and Strawberry 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,
76although ActivePerl 32 bit needed a newer MinGW version (that supports XP 84although ActivePerl 32 bit needed a newer MinGW version (that supports XP
77and higher). 85and higher).
78 86
79However, windows doesn't support asynchronous file descriptor passing, so 87However, windows doesn't support asynchronous file descriptor passing, so
80C<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
81for 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
82same 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.
83 92
84Also, on windows, the passing process must give the receiving process the 93Also, on windows, the receiving process must have the PROCESS_DUP_HANDLE
85PROCESS_DUP_HANDLE access right for this module to work. 94access right on the sender process for this module to work.
86 95
87Cygwin is not supported at the moment, as file descriptor passing in 96Cygwin is not supported at the moment, as file descriptor passing in
88cygwin is not supported, and cannot be rolled on your own as cygwin has no 97cygwin is not supported, and cannot be rolled on your own as cygwin has no
89(working) method of opening a handle as fd. That is, it has one, but that 98(working) method of opening a handle as fd. That is, it has one, but that
90one isn't exposed to programs, and only used for stdin/out/err. Sigh. 99one isn't exposed to programs, and only used for stdin/out/err. Sigh.
91 100
92=head1 OTHER MODULES 101=head1 OTHER MODULES
93 102
94At 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
95other file descriptor passing modules on CPAN: L<Linux::FDPasser> and 104other file descriptor passing modules on CPAN: L<File::FDPasser> and
96L<AnyEvent::FDPasser>. 105L<AnyEvent::FDPasser>.
97 106
98The 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
99and 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
100support 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.
101 111
102The 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
103seem 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
104and requires AnyEvent. Presumably that makes it much more user friendly 115AnyEvent. Presumably that makes it much more user friendly than this
105than 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.
106 120
107Neither seems to support native win32 perls. 121Neither seems to support native win32 perls.
108 122
109=head1 AUTHOR 123=head1 AUTHOR
110 124

Diff Legend

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