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