… | |
… | |
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 | |
11 | 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 |
12 | to another process, using a (streaming) unix domain socket (on POSIX |
18 | to another process, using a (streaming) unix domain socket (on POSIX |
13 | 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? |
14 | |
22 | |
15 | =head1 FUNCTIONS |
23 | =head1 FUNCTIONS |
16 | |
24 | |
17 | =over 4 |
25 | =over 4 |
18 | |
26 | |
19 | =cut |
27 | =cut |
20 | |
28 | |
21 | package IO::FDPass; |
29 | package IO::FDPass; |
22 | |
30 | |
23 | BEGIN { |
31 | BEGIN { |
24 | $VERSION = 0.2; |
32 | $VERSION = 1.3; |
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 | |
49 | 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 |
50 | errors, return C<-1>. |
58 | errors, return C<-1>. |
51 | |
59 | |
52 | 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 |
53 | fact, file descriptors, not handles. |
61 | fact, file descriptors, not handles. |
54 | |
62 | |
55 | 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 |
56 | 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 |
57 | 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 |
58 | C<select>). |
66 | C<select>). |
59 | |
67 | |
60 | 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 |
61 | a file handle. |
69 | to 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: $!"; |
… | |
… | |
77 | and higher). |
85 | and higher). |
78 | |
86 | |
79 | However, windows doesn't support asynchronous file descriptor passing, so |
87 | However, windows doesn't support asynchronous file descriptor passing, so |
80 | 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 |
81 | 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 |
82 | 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. |
83 | |
92 | |
84 | 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 |
85 | access right on the sender process for this module to work. |
94 | access right on the sender process for this module to work. |
86 | |
95 | |
87 | 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 |
… | |
… | |
90 | 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. |
91 | |
100 | |
92 | =head1 OTHER MODULES |
101 | =head1 OTHER MODULES |
93 | |
102 | |
94 | 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 |
95 | other file descriptor passing modules on CPAN: L<Linux::FDPasser> and |
104 | other file descriptor passing modules on CPAN: L<File::FDPasser> and |
96 | L<AnyEvent::FDPasser>. |
105 | L<AnyEvent::FDPasser>. |
97 | |
106 | |
98 | 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 |
99 | 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 |
100 | 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. |
101 | |
111 | |
102 | 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 |
103 | 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 |
104 | and requires AnyEvent. Presumably that makes it much more user friendly |
115 | AnyEvent. Presumably that makes it much more user friendly than this |
105 | 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. |
106 | |
120 | |
107 | Neither seems to support native win32 perls. |
121 | Neither seems to support native win32 perls. |
108 | |
122 | |
109 | =head1 AUTHOR |
123 | =head1 AUTHOR |
110 | |
124 | |