ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/IO-FDPass/README
(Generate patch)

Comparing IO-FDPass/README (file contents):
Revision 1.3 by root, Fri Apr 5 08:20:36 2013 UTC vs.
Revision 1.4 by root, Sat Apr 6 22:42:42 2013 UTC

… …
2 IO::FDPass - pass a file descriptor over a socket 2 IO::FDPass - pass a file descriptor over a socket
3 3
4SYNOPSIS 4SYNOPSIS
5 use IO::FDPass; 5 use IO::FDPass;
6 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
7DESCRIPTION 13DESCRIPTION
8 This small low-level module only has one purpose: pass a file descriptor 14 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 15 to another process, using a (streaming) unix domain socket (on POSIX
10 systems) or any (streaming) socket (on WIN32 systems). 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?
11 19
12FUNCTIONS 20FUNCTIONS
13 $bool = IO::FDPass::send $socket_fd, $fd_to_pass 21 $bool = IO::FDPass::send $socket_fd, $fd_to_pass
14 Sends the file descriptor given by $fd_to_pass over the socket 22 Sends the file descriptor given by $fd_to_pass over the socket
15 $socket_fd. Return true if it worked, false otherwise. 23 $socket_fd. Return true if it worked, false otherwise.
… …
28 36
29 $fd = IO::FDPass::recv $socket_fd 37 $fd = IO::FDPass::recv $socket_fd
30 Receive a file descriptor from the socket and return it if 38 Receive a file descriptor from the socket and return it if
31 successful. On errors, return -1. 39 successful. On errors, return -1.
32 40
33 Note that *both* $socket_fd amd the returned file descriptor are, in 41 Note that *both* $socket_fd and the returned file descriptor are, in
34 fact, file descriptors, not handles. 42 fact, file descriptors, not handles.
35 43
36 When used on non-blocking sockets, this function might fail with $! 44 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 45 set to "EAGAIN" or equivalent, in which case you are free to try
38 should succeed if called on a socket that indicates readability 46 again. It should succeed if called on a socket that indicates
39 (e.g. via "select"). 47 readability (e.g. via "select").
40 48
41 Example: receive a file desriptor from a blockign socket and convetr 49 Example: receive a file descriptor from a blocking socket and
42 it to a file handle. 50 convert it to a file handle.
43 51
44 my $fd = IO::FDPass::recv fileno $socket; 52 my $fd = IO::FDPass::recv fileno $socket;
45 $fd >= 0 or die "unable to receive file handle: $!"; 53 $fd >= 0 or die "unable to receive file handle: $!";
46 open my $fh, "+<&=$fd" 54 open my $fh, "+<&=$fd"
47 or die "unable to convert file descriptor to handle: $!"; 55 or die "unable to convert file descriptor to handle: $!";
… …
55 supports XP and higher). 63 supports XP and higher).
56 64
57 However, windows doesn't support asynchronous file descriptor passing, 65 However, windows doesn't support asynchronous file descriptor passing,
58 so the source process must still be around when the destination process 66 so the source process must still be around when the destination process
59 wants to receive the file handle. Also, if the target process fails to 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.),
60 fetch the handle, the handle will leak, so never do that. 69 the handle will leak, so never do that.
61 70
62 Also, on windows, the receiving process must have the PROCESS_DUP_HANDLE 71 Also, on windows, the receiving process must have the PROCESS_DUP_HANDLE
63 access right on the sender process for this module to work. 72 access right on the sender process for this module to work.
64 73
65 Cygwin is not supported at the moment, as file descriptor passing in 74 Cygwin is not supported at the moment, as file descriptor passing in
… …
68 that one isn't exposed to programs, and only used for stdin/out/err. 77 that one isn't exposed to programs, and only used for stdin/out/err.
69 Sigh. 78 Sigh.
70 79
71OTHER MODULES 80OTHER MODULES
72 At the time of this writing, the author of this module was aware of two 81 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 82 other file descriptor passing modules on CPAN: File::FDPasser and
74 AnyEvent::FDPasser. 83 AnyEvent::FDPasser.
75 84
76 The former hasn't seen any release for over a decade, isn't 64 bit clean 85 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, 86 and it's author didn't respond to my mail with the fix, so doesn't work
78 however, support a snumber of pre-standard unices. 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.
79 90
80 The latter seems to have similar support for antique unices, and doesn't 91 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, 92 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 93 doesn't support mixing data and file descriptors, and requires AnyEvent.
83 than this module. 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.
84 99
85 Neither seems to support native win32 perls. 100 Neither seems to support native win32 perls.
86 101
87AUTHOR 102AUTHOR
88 Marc Lehmann <schmorp@schmorp.de> 103 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines