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.6 by root, Fri Apr 5 09:15:37 2013 UTC vs.
Revision 1.10 by root, Mon Jul 6 17:44:23 2015 UTC

… …
14 14
15=head1 DESCRIPTION 15=head1 DESCRIPTION
16 16
17This 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
18to another process, using a (streaming) unix domain socket (on POSIX 18to another process, using a (streaming) unix domain socket (on POSIX
19systems) 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?
20 22
21=head1 FUNCTIONS 23=head1 FUNCTIONS
22 24
23=over 4 25=over 4
24 26
25=cut 27=cut
26 28
27package IO::FDPass; 29package IO::FDPass;
28 30
29BEGIN { 31BEGIN {
30 $VERSION = 0.2; 32 $VERSION = 1.1;
31 33
32 require XSLoader; 34 require XSLoader;
33 XSLoader::load (__PACKAGE__, $VERSION); 35 XSLoader::load (__PACKAGE__, $VERSION);
34} 36}
35 37
… …
53=item $fd = IO::FDPass::recv $socket_fd 55=item $fd = IO::FDPass::recv $socket_fd
54 56
55Receive 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
56errors, return C<-1>. 58errors, return C<-1>.
57 59
58Note 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
59fact, file descriptors, not handles. 61fact, file descriptors, not handles.
60 62
61When used on non-blocking sockets, this function might fail with C<$!> 63When used on non-blocking sockets, this function might fail with C<$!> set
62set 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
63should 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
64C<select>). 66C<select>).
65 67
66Example: receive a file desriptor from a blockign socket and convetr it to 68Example: receive a file descriptor from a blocking socket and convert it
67a file handle. 69to a file handle.
68 70
69 my $fd = IO::FDPass::recv fileno $socket; 71 my $fd = IO::FDPass::recv fileno $socket;
70 $fd >= 0 or die "unable to receive file handle: $!"; 72 $fd >= 0 or die "unable to receive file handle: $!";
71 open my $fh, "+<&=$fd" 73 open my $fh, "+<&=$fd"
72 or die "unable to convert file descriptor to handle: $!"; 74 or die "unable to convert file descriptor to handle: $!";
… …
83and higher). 85and higher).
84 86
85However, windows doesn't support asynchronous file descriptor passing, so 87However, windows doesn't support asynchronous file descriptor passing, so
86the source process must still be around when the destination process wants 88the source process must still be around when the destination process wants
87to receive the file handle. Also, if the target process fails to fetch the 89to receive the file handle. Also, if the target process fails to fetch the
88handle, the handle will leak, so never do that. 90handle for any reason (crashes, fails to call C<recv> etc.), the handle
91will leak, so never do that.
89 92
90Also, on windows, the receiving process must have the PROCESS_DUP_HANDLE 93Also, on windows, the receiving process must have the PROCESS_DUP_HANDLE
91access right on the sender process for this module to work. 94access right on the sender process for this module to work.
92 95
93Cygwin is not supported at the moment, as file descriptor passing in 96Cygwin is not supported at the moment, as file descriptor passing in
… …
96one 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.
97 100
98=head1 OTHER MODULES 101=head1 OTHER MODULES
99 102
100At 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
101other file descriptor passing modules on CPAN: L<Linux::FDPasser> and 104other file descriptor passing modules on CPAN: L<File::FDPasser> and
102L<AnyEvent::FDPasser>. 105L<AnyEvent::FDPasser>.
103 106
104The 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
105and 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
106support a number 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.
107 111
108The 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
109seem 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
110and requires AnyEvent. Presumably that makes it much more user friendly 115AnyEvent. Presumably that makes it much more user friendly than this
111than 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.
112 120
113Neither seems to support native win32 perls. 121Neither seems to support native win32 perls.
114 122
115=head1 AUTHOR 123=head1 AUTHOR
116 124

Diff Legend

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