.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "FDPass 3pm"
.TH FDPass 3pm "2018-11-01" "perl v5.28.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
IO::FDPass \- pass a file descriptor over a socket
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&   use IO::FDPass;
\&
\&   IO::FDPass::send fileno $socket, fileno $fh_to_pass
\&      or die "send failed: $!";
\&
\&   my $fd = IO::FDPass::recv fileno $socket;
\&   $fd >= 0 or die "recv failed: $!";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This small low-level module only has one purpose: pass a file descriptor
to another process, using a (streaming) unix domain socket (on \s-1POSIX\s0
systems) or any (streaming) socket (on \s-1WIN32\s0 systems). The ability to pass
file descriptors on windows is currently the unique selling point of this
module. Have I mentioned that it is really small, too?
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.ie n .IP "$bool = IO::FDPass::send $socket_fd, $fd_to_pass" 4
.el .IP "\f(CW$bool\fR = IO::FDPass::send \f(CW$socket_fd\fR, \f(CW$fd_to_pass\fR" 4
.IX Item "$bool = IO::FDPass::send $socket_fd, $fd_to_pass"
Sends the file descriptor given by \f(CW$fd_to_pass\fR over the socket
\&\f(CW$socket_fd\fR. Return true if it worked, false otherwise.
.Sp
Note that \fIboth\fR parameters must be file descriptors, not handles.
.Sp
When used on non-blocking sockets, this function might fail with \f(CW$!\fR
set to \f(CW\*(C`EAGAIN\*(C'\fR or equivalent, in which case you are free to try. It
should succeed if called on a socket that indicates writability (e.g. via
\&\f(CW\*(C`select\*(C'\fR).
.Sp
Example: pass a file handle over an open socket.
.Sp
.Vb 2
\&   IO::FDPass::send fileno $socket, fileno $fh
\&      or die "unable to pass file handle: $!";
.Ve
.ie n .IP "$fd = IO::FDPass::recv $socket_fd" 4
.el .IP "\f(CW$fd\fR = IO::FDPass::recv \f(CW$socket_fd\fR" 4
.IX Item "$fd = IO::FDPass::recv $socket_fd"
Receive a file descriptor from the socket and return it if successful. On
errors, return \f(CW\*(C`\-1\*(C'\fR.
.Sp
Note that \fIboth\fR \f(CW$socket_fd\fR and the returned file descriptor are, in
fact, file descriptors, not handles.
.Sp
When used on non-blocking sockets, this function might fail with \f(CW$!\fR set
to \f(CW\*(C`EAGAIN\*(C'\fR or equivalent, in which case you are free to try again. It
should succeed if called on a socket that indicates readability (e.g. via
\&\f(CW\*(C`select\*(C'\fR).
.Sp
Example: receive a file descriptor from a blocking socket and convert it
to a file handle.
.Sp
.Vb 4
\&  my $fd = IO::FDPass::recv fileno $socket;
\&  $fd >= 0 or die "unable to receive file handle: $!";
\&  open my $fh, "+<&=$fd"
\&     or die "unable to convert file descriptor to handle: $!";
.Ve
.SH "PORTABILITY NOTES"
.IX Header "PORTABILITY NOTES"
This module has been tested on GNU/Linux x86 and amd64, NetBSD 6, \s-1OS X
10.5,\s0 Windows 2000 ActivePerl 5.10, Solaris 10, OpenBSD 4.4, 4.5, 4.8 and
5.0, DragonFly \s-1BSD,\s0 FreeBSD 7, 8 and 9, Windows 7 + ActivePerl 5.16.3 32
and 64 bit and Strawberry Perl 5.16.3 32 and 64 bit, and found to work,
although ActivePerl 32 bit needed a newer MinGW version (that supports \s-1XP\s0
and higher).
.PP
However, windows doesn't support asynchronous file descriptor passing, so
the source process must still be around when the destination process wants
to receive the file handle. Also, if the target process fails to fetch the
handle for any reason (crashes, fails to call \f(CW\*(C`recv\*(C'\fR etc.), the handle
will leak, so never do that.
.PP
Also, on windows, the receiving process must have the \s-1PROCESS_DUP_HANDLE\s0
access right on the sender process for this module to work.
.PP
Cygwin is not supported at the moment, as file descriptor passing in
cygwin is not supported, and cannot be rolled on your own as cygwin has no
(working) method of opening a handle as fd. That is, it has one, but that
one isn't exposed to programs, and only used for stdin/out/err. Sigh.
.SH "OTHER MODULES"
.IX Header "OTHER MODULES"
At the time of this writing, the author of this module was aware of two
other file descriptor passing modules on \s-1CPAN:\s0 File::FDPasser and
AnyEvent::FDPasser.
.PP
The former hasn't seen any release for over a decade, isn't 64 bit clean
and it's author didn't respond to my mail with the fix, so doesn't work on
many 64 bit machines. It does, however, support a number of pre-standard
unices, basically everything of relevance at the time it was written.
.PP
The latter seems to have similar support for antique unices, and doesn't
seem to suffer from 64 bit bugs, but inexplicably has a large perl
part, doesn't support mixing data and file descriptors, and requires
AnyEvent. Presumably that makes it much more user friendly than this
module (skimming the manpage shows that a lot of thought has gone into
it, and you are well advised to read it and maybe use it before trying a
low-level module such as this one). In fact, the manpage discusses even
more file descriptor passing modules on \s-1CPAN.\s0
.PP
Neither seems to support native win32 perls.
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 2
\& Marc Lehmann <schmorp@schmorp.de>
\& http://home.schmorp.de/
.Ve