… | |
… | |
14 | |
14 | |
15 | =head1 DESCRIPTION |
15 | =head1 DESCRIPTION |
16 | |
16 | |
17 | This small low-level module only has one purpose: pass a file descriptor |
17 | This small low-level module only has one purpose: pass a file descriptor |
18 | to another process, using a (streaming) unix domain socket (on POSIX |
18 | to another process, using a (streaming) unix domain socket (on POSIX |
19 | systems) or any (streaming) socket (on WIN32 systems). |
19 | 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? |
20 | |
22 | |
21 | =head1 FUNCTIONS |
23 | =head1 FUNCTIONS |
22 | |
24 | |
23 | =over 4 |
25 | =over 4 |
24 | |
26 | |
… | |
… | |
53 | =item $fd = IO::FDPass::recv $socket_fd |
55 | =item $fd = IO::FDPass::recv $socket_fd |
54 | |
56 | |
55 | Receive a file descriptor from the socket and return it if successful. On |
57 | Receive a file descriptor from the socket and return it if successful. On |
56 | errors, return C<-1>. |
58 | errors, return C<-1>. |
57 | |
59 | |
58 | Note that I<both> C<$socket_fd> amd the returned file descriptor are, in |
60 | Note that I<both> C<$socket_fd> and the returned file descriptor are, in |
59 | fact, file descriptors, not handles. |
61 | fact, file descriptors, not handles. |
60 | |
62 | |
61 | When used on non-blocking sockets, this function might fail with C<$!> |
63 | When used on non-blocking sockets, this function might fail with C<$!> set |
62 | set to C<EAGAIN> or equivalent, in which case you are free to try. It |
64 | to C<EAGAIN> or equivalent, in which case you are free to try again. It |
63 | should succeed if called on a socket that indicates readability (e.g. via |
65 | should succeed if called on a socket that indicates readability (e.g. via |
64 | C<select>). |
66 | C<select>). |
65 | |
67 | |
66 | Example: receive a file desriptor from a blockign socket and convetr it to |
68 | Example: receive a file descriptor from a blocking socket and convert it |
67 | a file handle. |
69 | to 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: $!"; |
… | |
… | |
83 | and higher). |
85 | and higher). |
84 | |
86 | |
85 | However, windows doesn't support asynchronous file descriptor passing, so |
87 | However, windows doesn't support asynchronous file descriptor passing, so |
86 | the source process must still be around when the destination process wants |
88 | the source process must still be around when the destination process wants |
87 | to receive the file handle. Also, if the target process fails to fetch the |
89 | to receive the file handle. Also, if the target process fails to fetch the |
88 | handle, the handle will leak, so never do that. |
90 | handle for any reason (crashes, fails to call C<recv> etc.), the handle |
|
|
91 | will leak, so never do that. |
89 | |
92 | |
90 | Also, on windows, the receiving process must have the PROCESS_DUP_HANDLE |
93 | Also, on windows, the receiving process must have the PROCESS_DUP_HANDLE |
91 | access right on the sender process for this module to work. |
94 | access right on the sender process for this module to work. |
92 | |
95 | |
93 | Cygwin is not supported at the moment, as file descriptor passing in |
96 | Cygwin is not supported at the moment, as file descriptor passing in |
… | |
… | |
96 | one isn't exposed to programs, and only used for stdin/out/err. Sigh. |
99 | one 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 | |
100 | At the time of this writing, the author of this module was aware of two |
103 | At the time of this writing, the author of this module was aware of two |
101 | other file descriptor passing modules on CPAN: L<Linux::FDPasser> and |
104 | other file descriptor passing modules on CPAN: L<File::FDPasser> and |
102 | L<AnyEvent::FDPasser>. |
105 | L<AnyEvent::FDPasser>. |
103 | |
106 | |
104 | The former hasn't seen any release for over a decade, isn't 64 bit clean |
107 | The former hasn't seen any release for over a decade, isn't 64 bit clean |
105 | and it's author didn't respond to my mail with the fix. It does, however, |
108 | and it's author didn't respond to my mail with the fix, so doesn't work on |
106 | support a snumber of pre-standard unices. |
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. |
107 | |
111 | |
108 | The latter seems to have similar support for antique unices, and doesn't |
112 | The latter seems to have similar support for antique unices, and doesn't |
109 | seem to suffer from 64 bit bugs, but inexplicably has a large perl part, |
113 | 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 |
110 | and requires AnyEvent. Presumably that makes it much more user friendly |
115 | AnyEvent. Presumably that makes it much more user friendly than this |
111 | than this module. |
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. |
112 | |
120 | |
113 | Neither seems to support native win32 perls. |
121 | Neither seems to support native win32 perls. |
114 | |
122 | |
115 | =head1 AUTHOR |
123 | =head1 AUTHOR |
116 | |
124 | |