view release on metacpan or  search on metacpan

FDPass.pm  view on Meta::CPAN

=head1 NAME

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

=head1 SYNOPSIS

   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: $!";

=head1 DESCRIPTION

This small low-level module only has one purpose: pass a file descriptor
to another process, using a (streaming) unix domain socket (on POSIX
systems) or any (streaming) socket (on WIN32 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?

=head1 FUNCTIONS

=over 4

=cut

package IO::FDPass;

BEGIN {
   $VERSION = 1.3;

   require XSLoader;
   XSLoader::load (__PACKAGE__, $VERSION);
}

=item $bool = IO::FDPass::send $socket_fd, $fd_to_pass

Sends the file descriptor given by C<$fd_to_pass> over the socket
C<$socket_fd>. Return true if it worked, false otherwise.

Note that I<both> parameters must be file descriptors, not handles.

When used on non-blocking sockets, this function might fail with C<$!>
set to C<EAGAIN> or equivalent, in which case you are free to try. It
should succeed if called on a socket that indicates writability (e.g. via
C<select>).

Example: pass a file handle over an open socket.

   IO::FDPass::send fileno $socket, fileno $fh
      or die "unable to pass file handle: $!";

=item $fd = IO::FDPass::recv $socket_fd

Receive a file descriptor from the socket and return it if successful. On
errors, return C<-1>.

Note that I<both> C<$socket_fd> and the returned file descriptor are, in
fact, file descriptors, not handles.

When used on non-blocking sockets, this function might fail with C<$!> set
to C<EAGAIN> 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
C<select>).

Example: receive a file descriptor from a blocking socket and convert it
to a file handle.

  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: $!";

=back

=head1 PORTABILITY NOTES