1FDPass(3)             User Contributed Perl Documentation            FDPass(3)
2
3
4

NAME

6       IO::FDPass - pass a file descriptor over a socket
7

SYNOPSIS

9          use IO::FDPass;
10
11          IO::FDPass::send fileno $socket, fileno $fh_to_pass
12             or die "send failed: $!";
13
14          my $fd = IO::FDPass::recv fileno $socket;
15          $fd >= 0 or die "recv failed: $!";
16

DESCRIPTION

18       This small low-level module only has one purpose: pass a file
19       descriptor to another process, using a (streaming) unix domain socket
20       (on POSIX systems) or any (streaming) socket (on WIN32 systems). The
21       ability to pass file descriptors on windows is currently the unique
22       selling point of this module. Have I mentioned that it is really small,
23       too?
24

FUNCTIONS

26       $bool = IO::FDPass::send $socket_fd, $fd_to_pass
27           Sends the file descriptor given by $fd_to_pass over the socket
28           $socket_fd. Return true if it worked, false otherwise.
29
30           Note that both parameters must be file descriptors, not handles.
31
32           When used on non-blocking sockets, this function might fail with $!
33           set to "EAGAIN" or equivalent, in which case you are free to try.
34           It should succeed if called on a socket that indicates writability
35           (e.g. via "select").
36
37           Example: pass a file handle over an open socket.
38
39              IO::FDPass::send fileno $socket, fileno $fh
40                 or die "unable to pass file handle: $!";
41
42       $fd = IO::FDPass::recv $socket_fd
43           Receive a file descriptor from the socket and return it if
44           successful. On errors, return "-1".
45
46           Note that both $socket_fd and the returned file descriptor are, in
47           fact, file descriptors, not handles.
48
49           When used on non-blocking sockets, this function might fail with $!
50           set to "EAGAIN" or equivalent, in which case you are free to try
51           again. It should succeed if called on a socket that indicates
52           readability (e.g. via "select").
53
54           Example: receive a file descriptor from a blocking socket and
55           convert it to a file handle.
56
57             my $fd = IO::FDPass::recv fileno $socket;
58             $fd >= 0 or die "unable to receive file handle: $!";
59             open my $fh, "+<&=$fd"
60                or die "unable to convert file descriptor to handle: $!";
61

PORTABILITY NOTES

63       This module has been tested on GNU/Linux x86 and amd64, NetBSD 6, OS X
64       10.5, Windows 2000 ActivePerl 5.10, Solaris 10, OpenBSD 4.4, 4.5, 4.8
65       and 5.0, DragonFly BSD, FreeBSD 7, 8 and 9, Windows 7 + ActivePerl
66       5.16.3 32 and 64 bit and Strawberry Perl 5.16.3 32 and 64 bit, and
67       found to work, although ActivePerl 32 bit needed a newer MinGW version
68       (that supports XP and higher).
69
70       However, windows doesn't support asynchronous file descriptor passing,
71       so the source process must still be around when the destination process
72       wants to receive the file handle. Also, if the target process fails to
73       fetch the handle for any reason (crashes, fails to call "recv" etc.),
74       the handle will leak, so never do that.
75
76       Also, on windows, the receiving process must have the
77       PROCESS_DUP_HANDLE access right on the sender process for this module
78       to work.
79
80       Cygwin is not supported at the moment, as file descriptor passing in
81       cygwin is not supported, and cannot be rolled on your own as cygwin has
82       no (working) method of opening a handle as fd. That is, it has one, but
83       that one isn't exposed to programs, and only used for stdin/out/err.
84       Sigh.
85

OTHER MODULES

87       At the time of this writing, the author of this module was aware of two
88       other file descriptor passing modules on CPAN: File::FDPasser and
89       AnyEvent::FDPasser.
90
91       The former hasn't seen any release for over a decade, isn't 64 bit
92       clean and it's author didn't respond to my mail with the fix, so
93       doesn't work on many 64 bit machines. It does, however, support a
94       number of pre-standard unices, basically everything of relevance at the
95       time it was written.
96
97       The latter seems to have similar support for antique unices, and
98       doesn't seem to suffer from 64 bit bugs, but inexplicably has a large
99       perl part, doesn't support mixing data and file descriptors, and
100       requires AnyEvent. Presumably that makes it much more user friendly
101       than this module (skimming the manpage shows that a lot of thought has
102       gone into it, and you are well advised to read it and maybe use it
103       before trying a low-level module such as this one). In fact, the
104       manpage discusses even more file descriptor passing modules on CPAN.
105
106       Neither seems to support native win32 perls.
107

AUTHOR

109        Marc Lehmann <schmorp@schmorp.de>
110        http://home.schmorp.de/
111
112
113
114perl v5.34.0                      2021-07-22                         FDPass(3)
Impressum