|
|
1 | NAME |
|
|
2 | IO::FDPass - pass a file descriptor over a socket |
|
|
3 | |
|
|
4 | SYNOPSIS |
|
|
5 | use IO::FDPass; |
|
|
6 | |
|
|
7 | IO::FDPass::send fileno $socket, fileno $fh_to_pass |
|
|
8 | or die "send failed: $!"; |
|
|
9 | |
|
|
10 | my $fd = IO::FDPass::recv fileno $socket; |
|
|
11 | $fd >= 0 or die "recv failed: $!"; |
|
|
12 | |
|
|
13 | DESCRIPTION |
|
|
14 | This small low-level module only has one purpose: pass a file descriptor |
|
|
15 | to another process, using a (streaming) unix domain socket (on POSIX |
|
|
16 | systems) or any (streaming) socket (on WIN32 systems). The ability to |
|
|
17 | pass file descriptors on windows is currently the unique selling point |
|
|
18 | of this module. Have I mentioned that it is really small, too? |
|
|
19 | |
|
|
20 | FUNCTIONS |
|
|
21 | $bool = IO::FDPass::send $socket_fd, $fd_to_pass |
|
|
22 | Sends the file descriptor given by $fd_to_pass over the socket |
|
|
23 | $socket_fd. Return true if it worked, false otherwise. |
|
|
24 | |
|
|
25 | Note that *both* parameters must be file descriptors, not handles. |
|
|
26 | |
|
|
27 | When used on non-blocking sockets, this function might fail with $! |
|
|
28 | set to "EAGAIN" or equivalent, in which case you are free to try. It |
|
|
29 | should succeed if called on a socket that indicates writability |
|
|
30 | (e.g. via "select"). |
|
|
31 | |
|
|
32 | Example: pass a file handle over an open socket. |
|
|
33 | |
|
|
34 | IO::FDPass::send fileno $socket, fileno $fh |
|
|
35 | or die "unable to pass file handle: $!"; |
|
|
36 | |
|
|
37 | $fd = IO::FDPass::recv $socket_fd |
|
|
38 | Receive a file descriptor from the socket and return it if |
|
|
39 | successful. On errors, return -1. |
|
|
40 | |
|
|
41 | Note that *both* $socket_fd and the returned file descriptor are, in |
|
|
42 | fact, file descriptors, not handles. |
|
|
43 | |
|
|
44 | When used on non-blocking sockets, this function might fail with $! |
|
|
45 | set to "EAGAIN" or equivalent, in which case you are free to try |
|
|
46 | again. It should succeed if called on a socket that indicates |
|
|
47 | readability (e.g. via "select"). |
|
|
48 | |
|
|
49 | Example: receive a file descriptor from a blocking socket and |
|
|
50 | convert it to a file handle. |
|
|
51 | |
|
|
52 | my $fd = IO::FDPass::recv fileno $socket; |
|
|
53 | $fd >= 0 or die "unable to receive file handle: $!"; |
|
|
54 | open my $fh, "+<&=$fd" |
|
|
55 | or die "unable to convert file descriptor to handle: $!"; |
|
|
56 | |
|
|
57 | PORTABILITY NOTES |
|
|
58 | This module has been tested on GNU/Linux x86 and amd64, NetBSD 6, OS X |
|
|
59 | 10.5, Windows 2000 ActivePerl 5.10, Solaris 10, OpenBSD 4.4, 4.5, 4.8 |
|
|
60 | and 5.0, DragonFly BSD, FreeBSD 7, 8 and 9, Windows 7 + ActivePerl |
|
|
61 | 5.16.3 32 and 64 bit and Strawberry Perl 5.16.3 32 and 64 bit, and found |
|
|
62 | to work, although ActivePerl 32 bit needed a newer MinGW version (that |
|
|
63 | supports XP and higher). |
|
|
64 | |
|
|
65 | However, windows doesn't support asynchronous file descriptor passing, |
|
|
66 | so the source process must still be around when the destination process |
|
|
67 | wants to receive the file handle. Also, if the target process fails to |
|
|
68 | fetch the handle for any reason (crashes, fails to call "recv" etc.), |
|
|
69 | the handle will leak, so never do that. |
|
|
70 | |
|
|
71 | Also, on windows, the receiving process must have the PROCESS_DUP_HANDLE |
|
|
72 | access right on the sender process for this module to work. |
|
|
73 | |
|
|
74 | Cygwin is not supported at the moment, as file descriptor passing in |
|
|
75 | cygwin is not supported, and cannot be rolled on your own as cygwin has |
|
|
76 | no (working) method of opening a handle as fd. That is, it has one, but |
|
|
77 | that one isn't exposed to programs, and only used for stdin/out/err. |
|
|
78 | Sigh. |
|
|
79 | |
|
|
80 | OTHER MODULES |
|
|
81 | At the time of this writing, the author of this module was aware of two |
|
|
82 | other file descriptor passing modules on CPAN: File::FDPasser and |
|
|
83 | AnyEvent::FDPasser. |
|
|
84 | |
|
|
85 | The former hasn't seen any release for over a decade, isn't 64 bit clean |
|
|
86 | and it's author didn't respond to my mail with the fix, so doesn't work |
|
|
87 | on many 64 bit machines. It does, however, support a number of |
|
|
88 | pre-standard unices, basically everything of relevance at the time it |
|
|
89 | was written. |
|
|
90 | |
|
|
91 | The latter seems to have similar support for antique unices, and doesn't |
|
|
92 | seem to suffer from 64 bit bugs, but inexplicably has a large perl part, |
|
|
93 | doesn't support mixing data and file descriptors, and requires AnyEvent. |
|
|
94 | Presumably that makes it much more user friendly than this module |
|
|
95 | (skimming the manpage shows that a lot of thought has gone into it, and |
|
|
96 | you are well advised to read it and maybe use it before trying a |
|
|
97 | low-level module such as this one). In fact, the manpage discusses even |
|
|
98 | more file descriptor passing modules on CPAN. |
|
|
99 | |
|
|
100 | Neither seems to support native win32 perls. |
|
|
101 | |
|
|
102 | AUTHOR |
|
|
103 | Marc Lehmann <schmorp@schmorp.de> |
|
|
104 | http://home.schmorp.de/ |
|
|
105 | |